{"id":33258584,"url":"https://github.com/mariusmm/RISC-V-TLM","last_synced_at":"2025-11-21T21:01:06.790Z","repository":{"id":47631412,"uuid":"148187358","full_name":"mariusmm/RISC-V-TLM","owner":"mariusmm","description":"RISC-V SystemC-TLM simulator","archived":false,"fork":false,"pushed_at":"2025-11-08T12:05:01.000Z","size":2722,"stargazers_count":329,"open_issues_count":6,"forks_count":81,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-11-08T14:17:53.633Z","etag":null,"topics":["risc-v","riscv","systemc","tlm2"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mariusmm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-09-10T16:41:14.000Z","updated_at":"2025-11-08T12:05:03.000Z","dependencies_parsed_at":"2024-07-31T19:27:15.330Z","dependency_job_id":"c4d2718a-4a4e-4356-bd6f-67cf8822e0b9","html_url":"https://github.com/mariusmm/RISC-V-TLM","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mariusmm/RISC-V-TLM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariusmm%2FRISC-V-TLM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariusmm%2FRISC-V-TLM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariusmm%2FRISC-V-TLM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariusmm%2FRISC-V-TLM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mariusmm","download_url":"https://codeload.github.com/mariusmm/RISC-V-TLM/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariusmm%2FRISC-V-TLM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285689538,"owners_count":27215143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-21T02:00:06.175Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["risc-v","riscv","systemc","tlm2"],"created_at":"2025-11-17T03:00:41.008Z","updated_at":"2025-11-21T21:01:06.784Z","avatar_url":"https://github.com/mariusmm.png","language":"C","funding_links":[],"categories":["Hardware Verification"],"sub_categories":["Tools"],"readme":"# Another RISC-V ISA simulator.\n\n**This code is suitable to hard refactor at any time**\n\n\nThis is another RISC-V ISA simulator, this is coded in SystemC + TLM-2.\nIt supports RV32IMAC and RV64IMAC Instruction set.\n\n[![travis](https://api.travis-ci.com/mariusmm/RISC-V-TLM.svg?branch=master)](https://app.travis-ci.com/github/mariusmm/RISC-V-TLM)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/0f7ccc8435f14ce2b241b3bfead772a2)](https://www.codacy.com/gh/mariusmm/RISC-V-TLM/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=mariusmm/RISC-V-TLM\u0026amp;utm_campaign=Badge_Grade)\n[![Coverity Scan Build Status](https://img.shields.io/coverity/scan/18772.svg)](https://scan.coverity.com/projects/mariusmm-risc-v-tlm)\n[![license](https://img.shields.io/badge/license-GNU--3.0-green.svg)](https://github.com/mariusmm/RISC-V-TLM/blob/master/LICENSE)\n![last commit](https://img.shields.io/github/last-commit/Mariusmm/RISC-V-TLM)\n![commit activity](https://img.shields.io/github/commit-activity/w/Mariusmm/RISC-V-TLM)\n[![Docker](https://img.shields.io/docker/cloud/automated/mariusmm/riscv-tlm.svg?style=flat)](https://hub.docker.com/r/mariusmm/riscv-tlm)\n[![Twitter URL](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/mariusmonton)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7181526.svg)](https://doi.org/10.5281/zenodo.7181526)\n\n---\nTable of Contents\n=================\n\u003c!--ts--\u003e\n   * [Another RISC-V ISA simulator.](./README.md#another-risc-v-isa-simulator)\n   * [Table of Contents](./README.md#table-of-contents)\n      * [Description](./README.md#description)\n         * [Structure](./README.md#structure)\n         * [Memory Map](./README.md#memory-map)\n      * [TODO](./README.md#todo)\n      * [Compile](./README.md#compile)\n      * [Cross-compiler](./README.md#cross-compiler)\n      * [Debug](./README.md#debug)\n      * [Docker container](./README.md#docker-container)\n         * [How to use Docker](./README.md#how-to-use-docker)\n      * [Test](./README.md#test)\n         * [C code](./README.md#c-code)\n         * [FreeRTOS](./README.md#freertos)\n      * [Documentation](./README.md#documentation)\n         * [Publications](./README.md#publications)\n      * [Contribute](./README.md#contribute)\n      * [Authors and credits](./README.md#Authors-and-credits)\n      * [License](./README.md#license)\n\n\u003c!-- Added by: marius, at: 2019-02-11T20:15+01:00 --\u003e\n\n\u003c!--te--\u003e\n\n## Description\n\nBrief description of the modules:\n* CPU: Top entity that includes all other modules.\n* Memory: Memory highly based on TLM-2 example with read file capability\n* Registers: Implements the register file, PC register \u0026 CSR registers\n* Instruction: Decodes instruction type and keeps instruction field\n* BASE_ISA: Executes Base ISA, Zifencei and Zicsr.\n  * C_extension: Decodes \u0026 Executes Compressed instructions (C extension)\n  * M_extension: Decodes \u0026 Executes Multiplication and Division instructions (M extension)\n  * A_extension: Decodes \u0026 Executes Atomic instructions (A extension)\n* Simulator: Top-level entity that builds \u0026 starts the simulation\n* BusCtrl: Simple bus manager\n* Trace: Simple trace peripheral\n* Timer: Simple IRQ programable real-time counter peripheral\n* Debug: GDB server for remote debugging (Beta)\n\nHelper classes:\n* Performance: Performance indicators stores here (singleton class)\n* Log: Log class to log them all (singleton class)\n\nCurrent performance is about 3.000.000 instructions / sec in a Intel Core\ni5-5200\u003cspan\u003e@\u003c/span\u003e2.2Ghz and about 4.500.000 instructions / sec in a Intel Core i7-8550U\u003cspan\u003e@\u003c/span\u003e1.8Ghz.\n\nTrace perihperal creates a xterm window where it prints out all received data. \n\n### Structure\n![Modules' hierarchy](doc/Hierarchy.png)\n\n\n### Memory map\n\n| Base | Module | Description | \n| ---- | :----: | ---- |\n| 0x40000000 | Trace | Output data to xterm | \n| 0x40004000 | Timer | LSB Timer |\n| 0x40004004 | Timer | MSB Timer |\n| 0x40004008 | Timer | MSB Timer Comparator |\n| 0x4000400C | Timer | LSB Timer Comparator |\n\n\n## TODO\nThis is a preliminar and incomplete version.\n\nTask to do:\n- [x] Implement all missing instructions (Execute)\n- [x] Implement CSRs ~~(where/how?)~~\n- [ ] Add full support to read file with memory contents (to memory.h)\n   - [ ] .elf files\n   - [x] .hex files (only partial .hex support)\n- [ ]  Connect some TLM peripherals\n     - [x] Debug module similiar to ARM's ITM\n     - [ ] Some standard UART model\n     - [ ] ...\n- [ ] Implement interrupts\n     - [x] implement timer (mtimecmp) \u0026 timer interrupt  \n     - [ ] generic IRQ comtroller\n- [x] Test, test, test \u0026 test. I'm sure there are a ~~lot of~~ some bugs in the code\n     - [x] riscv-test almost complete (see [Test](https://github.com/mariusmm/RISC-V-TLM/wiki/Tests))\n     - [x] riscv-compliance \n* [ ] Improve structure and modules hierarchy\n* [X] Add 64 architecture (RV64I)\n* [x] Debug capabilities\n* [ ] Add [Trace v2.0](https://github.com/riscv-non-isa/riscv-trace-spec) support\n* [x] Support to SystemC 3.0.0\n\n## Compile\nIn order to compile the project you need SystemC-2.3.3/4 installed in your system, and Boost Library Headers.\n\n```sh\n# Following Environment are needed to configure the project\nexport SYSTEMC_HOME=\u003cPath to SystemC Library Installation\u003e\n# Check the SystemC Installation path for this setting\nexport LD_LIBRARY_PATH=$SYSTEMC_HOME/lib-linux64\n# Optional BOOST_ROOT if not specified one should have Boost Header Package Installed\nexport BOOST_ROOT=\u003cPath to extracted boost library sources\u003e\n# Clone the repo with submodules initialized\ngit clone --recurse-submodules https://github.com/mariusmm/RISC-V-TLM.git\n\n# If already cloned one need to run the following command to initialize the git submodule from within the RISC-V-TLM cloned directory\ngit submodule update --init --recursive\n# Configure, Build and deploy spdlog dependency\ncd spdlog\n# Configure spdlog submodule\ncmake -H. -B_builds -DCMAKE_INSTALL_PREFIX=install -DCMAKE_BUILD_TYPE=Release\n# Build spdlog\ncmake --build _builds --config Release\n# Install spdlog\ncmake --build _builds --target install\ncd ..\n# Setup SPDLOG_HOME to point to spdlog dependency installation path for the built library, here PWD is the RISC-V-TLM project cloned directory\nexport SPDLOG_HOME=$PWD/spdlog/install\n```\n\nThen, you need to modifiy your LD_LIBRARY_PATH environtment variable to add\npath systemc library. In my case:\n```sh\nexport LD_LIBRARY_PATH=/home/marius/Work/RiscV/code/systemc-2.3.2/lib-linux64\n```\n\nAnd then you can execute the simulator:\n```sh\n./RISCV_TLM asm/BasicLoop.hex\n```\n\n### Using cmake\n\nIt is possible to use cmake:\n```sh\n# Create and cd into the build directory for RISC-V-TLM project\nmkdir build\ncd build\n# Configure the project using CMake\ncmake -DCMAKE_BUILD_TYPE=Release ..\n# For additional configuration one can refer the CMake documentation on additional configuration options.\nmake\n```\n\nnote that SystemC must be compiled with cmake:\n```sh\ncd \u003csystemc directory\u003e\nmkdir build\ncd build\ncmake ../ -DCMAKE_CXX_STANDARD=17\nmake\n```\n\n### Arguments\n-L loglevel: 3 for detailed (INFO) log, 0 to ERROR log level\n\n-f filename .hex binary filename to use\n\n-D Enter in Debug mode, simulator starts gdb server (Beta)\n\n-R 32 or 64 to choose 32-bit or 64-bit architecture\n\n## Cross-compiler\nIt is possible to use gcc as risc-v compiler. Follow the instructions (from https://github.com/riscv/riscv-gnu-toolchain):\n~~~sh\ngit clone --recursive https://github.com/riscv/riscv-gnu-toolchain\ncd riscv-gnu-toolchain\n./configure --prefix=/opt/riscv --with-arch=rv32gc --with-abi=ilp32\nmake\n# ...\n# wait for long time ...\n# ...\nexport PATH=$PATH:/opt/riscv/bin\n~~~\n\nIn test/C/long_test/ example there is a Makefile that compiles a project with any .c files and links them against new-lib nano. \nThere is a Helper_functions.c file with defiitions of all missing functions needed by the library (**_read()**, **_close()**, **_fstat_r()**, \n**_lseek_r()**, **_isatty_r()**, **_write()**). All of them are defined empty except **_write()** that is written to use the Trace perihperal. \nThe definition of the function **_write()** allows developer to use printf() as usual and the stdout will be redirected to the Trace perihperal.\n\n## Debug\nIt is possible to debug an application running in RISC-V-TLM simulator. \nIt is tested with riscv32-unknown-elf-gdb version 8.3.0.20190516-git and eclipse.\nConfigure a \"C/C++ Remote Application\" debug configuration as the figure\n\n![Modules' hierarchy](doc/DebugConfiguration.png)\n \ngdbinit.txt file must contain: \n\n```\nset debug remote 1\nset arch riscv:rv32\n```\n\nWith this configuration, eclipse debuggins is almost normal (I experienced some problems wiith \"step-over\" and \"step-into\" commands)\n\n## Docker container\n\nThere is a Docker container available with the latest release at https://hub.docker.com/r/mariusmm/riscv-tlm. \nThis container has RISCV-TLM already build at /usr/src/riscv64/RISCV-TLM directory.\n\n### How to use Docker\n```sh\ndocker pull mariusmm/riscv-tlm\ndocker run -v \u003cpath_to_RISCV-V-TLM\u003e/:/tmp -u $UID -e DISPLAY=$DISPLAY --volume=\"/tmp/.X11-unix:/tmp/.X11-unix:rw\"  -it mariusmm/riscv-tlm /bin/bash\n\n./RISC-V-TLM/build/RISCV_TLM /tmp/\u003cyour_hex_file\u003e\n```\n\nor you can call binary inside docker image directly:\n\n```sh\ndocker run -v \u003cpath_to_RISCV-V-TLM\u003e/:/tmp -u $UID -e DISPLAY=$DISPLAY --volume=\"/tmp/.X11-unix:/tmp/.X11-unix:rw\"  -it mariusmm/riscv-tlm /usr/src/riscv64/RISC-V-TLM/RISCV_TLM /tmp/\u003cyour_hex_file\u003e\n```\n\nI'm using docker image [zmors/riscv_gcc](https://hub.docker.com/r/zmors/riscv_gcc) to have a cross-compiler,  I'm using both docker images this way:\n\n```sh\n# console1:\ndocker run -v /tmp:/PRJ -it zmors/riscv_gcc:1  bash\n\n# cd /PRJ/func3\n# make\n\n# console2:\ndocker run -v /tmp:/tmp -u $UID -e DISPLAY=$DISPLAY --volume=\"/tmp/.X11-unix:/tmp/.X11-unix:rw\" -it mariusmm/riscv-tlm /bin/bash\n\n# Run following commands as root/su user\ncd /usr/src/riscv64/RISC-V-TLM/ \n./RISCV-TLM /tmp/file.hex\n# ...\n```\n\nor \n\n```sh\n# ...\n# console 2:\ndocker run -v /tmp/tmp -it  mariusmm/riscv-tlm /usr/src/riscv64/RISC-V-TLM/RISCV_TLM /tmp/file.hex\n```\n\nPerformance is not affected by running the simulator inside the container\n\n## Test\nSee [Test page](Test) for more information.\n\nIn the asm directory there are some basic assembly examples.\n\nI \"compile\" one file with the follwing command:\n```sh\ncd asm\nriscv32-unknown-elf-as  EternalLoop.asm -o EternalLoop.o\nriscv32-unknown-elf-ld EternalLoop.o -o EternalLoop.elf\nriscv32-unknown-elf-objcopy -O ihex EternalLoop.elf EternalLoop.hex\ncd ..\n./RISCV_SCTLM asm/EternalLoop.hex\n```\nThis example needs that you hit Ctr+C to stop execution.\n\n### C code\nThe C directory contains simple examples in C. Each directory contains\nan example, to compile it just:\n```sh\nmake\n```\nand then execute the .hex file like the example before.\n\n### FreeRTOS\nFreeRTOS can run in this simulator!\n\nIn test/FreeRTOS/ directory there is portable files (port.c, portmacro.c portasm.S) and main file (freertos_test.c) ported to this RISC-V model.\n\n## Documentation\nThe code is documented using doxygen. In the doc folder there is a Doxygen.cfg\nfile ready to be used.\n\n## Contribute\nThere are several ways to contribute to this project:\n* Test\n* Pull request are welcome (see TODO list)\n* Good documentation\n* RTL-Level simulation\n\n\n## Authors and credits\nRISC-V-TLM is managed by Màrius Montón.\n\nIf you find this code useful, please consider citing:\n```\n@inproceedings{montonriscvtlm2020,\n        title = {A {RISC}-{V} {SystemC}-{TLM} simulator},\n        booktitle = {Workshop on {Computer} {Architecture} {Research} with {RISC}-{V} ({CARRV 2020}),\n        author = {Montón, Màrius},\n        year = {2020}\n}\n```\n\n## Publications\nI've published a paper describing the RISC-V simulator in [CARRV 2020](https://carrv.github.io/2020/) conference ([pdf](http://mariusmonton.com/wp-uploads/2020/05/CARRV2020_paper_7_Monton.pdf)).\n\n##  License\n\nCopyright (C) 2018, 2019, 2020, 2021, 2022 Màrius Montón ([@mariusmonton](https://twitter.com/mariusmonton/))\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariusmm%2FRISC-V-TLM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmariusmm%2FRISC-V-TLM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariusmm%2FRISC-V-TLM/lists"}