risc-v-tlm/README.md

236 lines
8.2 KiB
Markdown
Raw Normal View History

2018-09-27 21:11:02 +08:00
# Another RISC-V ISA simulator.
**This code is suitable to hard refactor at any time**
This is another RISC-V ISA simulator, this is coded in SystemC + TLM-2.
2019-02-12 18:39:15 +08:00
It supports RV32IMAC Instruction set by now.
2018-09-27 21:11:02 +08:00
[![travis](https://travis-ci.org/mariusmm/RISC-V-TLM.svg?branch=master)](https://travis-ci.org/mariusmm/RISC-V-TLM)
2018-09-28 02:26:17 +08:00
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/0f7ccc8435f14ce2b241b3bfead772a2)](https://www.codacy.com/app/mariusmm/RISC-V-TLM?utm_source=github.com&utm_medium=referral&utm_content=mariusmm/RISC-V-TLM&utm_campaign=Badge_Grade)
2019-07-12 23:50:07 +08:00
[![Coverity Scan Build Status](https://img.shields.io/coverity/scan/18772.svg)](https://scan.coverity.com/projects/mariusmm-risc-v-tlm)
2018-09-28 02:26:17 +08:00
[![license](https://img.shields.io/badge/license-GNU--3.0-green.svg)](https://github.com/mariusmm/RISC-V-TLM/blob/master/LICENSE)
2019-02-15 21:30:12 +08:00
[![Docker](https://img.shields.io/docker/automated/mariusmm/riscv-tlm.svg?style=flat)](https://hub.docker.com/r/mariusmm/riscv-tlm)
2018-09-27 22:15:59 +08:00
[![Twitter URL](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/mariusmonton)
2019-02-04 20:16:50 +08:00
---
Table of Contents
=================
<!--ts-->
2019-02-12 03:16:32 +08:00
* [Another RISC-V ISA simulator.](./README.md#another-risc-v-isa-simulator)
* [Table of Contents](./README.md#table-of-contents)
* [Description](./README.md#description)
* [Structure](./README.md#structure)
2019-04-10 17:16:14 +08:00
* [Memory Map](./README.md#memory-map)
2019-02-12 03:16:32 +08:00
* [TODO](./README.md#todo)
* [Compile](./README.md#compile)
2019-06-22 23:07:34 +08:00
* [Cross-compiler](./README.md#cross-compiler)
2019-02-12 03:16:32 +08:00
* [Docker container](./README.md#docker-container)
* [How to use Docker](./README.md#how-to-use-docker)
* [Test](./README.md#test)
* [C code](./README.md#c-code)
* [FreeRTOS](./README.md#freertos)
* [Documentation](./README.md#documentation)
* [Contribute](./README.md#contribute)
* [License](./README.md#license)
<!-- Added by: marius, at: 2019-02-11T20:15+01:00 -->
2019-02-04 20:16:50 +08:00
<!--te-->
## Description
2018-09-27 21:11:02 +08:00
Brief description of the modules:
* CPU: Top entity that includes all other modules.
* Memory: Memory highly based on TLM-2 example with read file capability
* Registers: Implements the register file, PC register & CSR registers
2018-10-18 05:51:53 +08:00
* Execute: Executes ISA instructions
2018-11-15 02:19:05 +08:00
* Executes C instruction extensions
* Executes M instruction extensions
2019-01-02 04:11:34 +08:00
* Executes A instruction extensions
2018-09-27 21:11:02 +08:00
* Instruction: Decodes instruction and acces to any instruction field
* C_Instruction: Decodes Compressed instructions (C extension)
2018-11-15 19:33:21 +08:00
* M_Instruction: Decodes Multiplication and Division instructions (M extension)
2019-01-02 04:11:34 +08:00
* A_Instruction: Decodes Atomic instructions (A extension)
2018-09-27 21:11:02 +08:00
* Simulator: Top-level entity that builds & starts the simulation
* BusCtrl: Simple bus manager
* Trace: Simple trace peripheral
2019-01-14 01:39:35 +08:00
* Timer: Simple IRQ programable real-time counter peripheral
2018-09-27 21:11:02 +08:00
Helper classes:
* Performance: Performance indicators stores here (singleton class)
* Log: Log class to log them all (singleton class)
2019-01-23 01:34:48 +08:00
Current performance is about 1.500.000 instructions / sec in a Intel Core
2019-09-12 17:30:57 +08:00
i5-5200<span>@</span>2.2Ghz and about 3.000.000 instructions / sec in a Intel Core i7-8550U<span>@</span>1.8Ghz.
2018-09-27 21:11:02 +08:00
### Structure
2018-10-18 05:51:53 +08:00
![Modules' hierarchy](https://github.com/mariusmm/RISC-V-TLM/blob/master/doc/Hierarchy.png)
2018-09-27 21:11:02 +08:00
2019-04-10 17:16:14 +08:00
### Memory map
| Base | Module | Description |
| ---- | :----: | ---- |
| 0x40000000 | Trace | Output data directly to stdout |
| 0x40004000 | Timer | LSB Timer |
| 0x40004004 | Timer | MSB Timer |
| 0x40004008 | Timer | MSB Timer Comparator |
| 0x4000400C | Timer | LSB Timer Comparator |
2018-09-27 21:11:02 +08:00
## TODO
This is a preliminar and incomplete version.
Task to do:
2019-01-13 08:36:38 +08:00
- [x] Implement all missing instructions (Execute)
2019-02-15 21:30:12 +08:00
- [x] Implement CSRs ~~(where/how?)~~
2019-01-10 21:58:27 +08:00
- [ ] Add full support to read file with memory contents (to memory.h)
- [ ] .elf files
- [x] .hex files (only partial .hex support)
- [ ] Connect some TLM peripherals
2019-01-13 08:36:38 +08:00
- [x] Debug module similiar to ARM's ITM
2019-01-10 21:58:27 +08:00
- [ ] Some standard UART model
- [ ] ...
- [ ] Implement interrupts
2019-01-13 08:36:38 +08:00
- [x] implement timer (mtimecmp) & timer interrupt
- [ ] generic IRQ comtroller
2019-01-10 21:58:27 +08:00
- [x] Test, test, test & test. I'm sure there are a ~~lot of~~ some bugs in the code
2019-01-10 22:02:41 +08:00
- [x] riscv-test almost complete (see [Test](https://github.com/mariusmm/RISC-V-TLM/wiki/Tests))
2019-01-10 21:58:27 +08:00
- [ ] riscv-compliance WiP
2018-09-27 21:11:02 +08:00
* Improve structure and modules hierarchy
* Add 64 & 128 bits architecture (RV64I, RV128I)
## Compile
In order to compile the project you need SystemC-2.3.2 installed in your system.
Just change SYSTEMC path in Makefile.
```
$ make
```
Then, you need to modifiy your LD_LIBRARY_PATH environtment variable to add
path systemc library. In my case:
```
$ export LD_LIBRARY_PATH=/home/marius/Work/RiscV/code/systemc-2.3.2/lib-linux64
```
And then you can execute the simulator:
```
$ ./RISCV_TLM asm/BasicLoop.hex
```
2019-02-15 21:30:12 +08:00
### Arguments
-D loglevel: 3 for detailed (INFO) log, 0 to ERROR log level
-f filename .hex filename to use
2019-02-03 19:05:06 +08:00
## Cross-compiler
It is possible to use gcc for risc-v compiler. Follow the instructions (from https://github.com/riscv/riscv-gnu-toolchain):
~~~
$ git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
$ cd riscv-gnu-toolchain
2019-06-22 23:07:34 +08:00
$ ./configure --prefix=/opt/riscv --with-arch=rv32gc --with-abi=ilp32
$ make
...
wait for long time ...
...
$ export PATH=$PATH:/opt/riscv/bin
~~~
2019-02-03 19:05:06 +08:00
## Docker container
There is a Docker container available with the latest release at https://hub.docker.com/r/mariusmm/riscv-tlm.
This container has RISCV-TLM already build at /usr/src/riscv64/RISCV-TLM directory.
### How to use Docker
```
$ docker pull mariusmm/riscv-tlm
2019-09-09 20:09:06 +08:00
$ docker run -v <path_to_RISCV-V-TLM>/:/tmp -u $UID -e DISPLAY=$DISPLAY --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" -it mariusmm/riscv-tlm /bin/bash
2019-02-03 19:05:06 +08:00
# cd /usr/src/riscv64/RISCV_TLM/
# ./RISCV_TLM /tmp/<your_hex_file>
```
2019-02-04 04:46:38 +08:00
I'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:
```
console1:
$ docker run -v /tmp:/PRJ -it zmors/riscv_gcc:1 bash
# cd /PRJ/func3
# make
console2:
2019-09-09 20:13:45 +08:00
$ docker run -v /tmp:/tmp -u $UID -e DISPLAY=$DISPLAY --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" -it mariusmm/riscv-tlm /bin/bash
2019-02-04 04:46:38 +08:00
# cd /usr/src/riscv64/RISC-V-TLM/
# ./RISCV-TLM /tmp/file.hex
...
```
2019-02-15 21:30:12 +08:00
or
```
...
console 2:
$ docker run -v /tmp/tmp -it mariusmm/riscv-tlm /usr/src/riscv64/RISC-V-TLM/RISCV_TLM /tmp/file.hex
```
2019-02-03 19:05:06 +08:00
Performance is not affected by running the simulator inside the container
2018-09-27 21:11:02 +08:00
## Test
2018-10-18 05:51:53 +08:00
See [Test page](Test) for more information.
2018-09-27 21:11:02 +08:00
In the asm directory there are some basic assembly examples.
I "compile" one file with the follwing command:
```
$ cd asm
2019-01-14 01:39:35 +08:00
$ riscv32-unknown-elf-as EternalLoop.asm -o EternalLoop.o
2019-06-10 03:19:47 +08:00
$ riscv32-unknown-elf-ld EternalLoop.o -o EternalLoop.elf
2019-01-14 01:39:35 +08:00
$ riscv32-unknown-elf-objcopy -O ihex EternalLoop.elf EternalLoop.hex
2018-09-27 21:11:02 +08:00
$ cd ..
$ ./RISCV_SCTLM asm/EternalLoop.hex
```
This example needs that you hit Ctr+C to stop execution.
### C code
The C directory contains simple examples in C. Each directory contains
an example, to compile it just:
```
$ make
```
and then execute the .hex file like the example before.
2019-02-12 03:16:32 +08:00
### FreeRTOS
FreeRTOS can run in this simulator!
In 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.
2018-11-15 19:33:21 +08:00
2018-09-27 21:11:02 +08:00
## Documentation
The code is documented using doxygen. In the doc folder there is a Doxygen.cfg
file ready to be used.
## Contribute
There are several ways to contribute to this project:
* Test
* Pull request are welcome (see TODO list)
* Good documentation
2019-02-15 21:30:12 +08:00
* RTL-Level simulation
2018-09-27 21:11:02 +08:00
## License
2019-06-10 03:19:47 +08:00
Copyright (C) 2018, 2019 Màrius Montón ([\@mariusmonton](https://twitter.com/mariusmonton/))
2018-09-27 21:11:02 +08:00
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.