diff options
Diffstat (limited to 'riscv/riscv-probe/README.md')
| -rw-r--r-- | riscv/riscv-probe/README.md | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/riscv/riscv-probe/README.md b/riscv/riscv-probe/README.md new file mode 100644 index 0000000..577e09d --- /dev/null +++ b/riscv/riscv-probe/README.md @@ -0,0 +1,347 @@ +# riscv-probe + +Simple machine mode program to probe RISC-V control and status registers. + +riscv-probe currently builds for +[Spike](https://github.com/riscv/riscv-isa-sim), +[QEMU](https://github.com/riscv/riscv-qemu) and the +[SiFive E21](https://www.sifive.com/products/risc-v-core-ip/e2/e21/) core. +riscv-probe is a testing tool designed be used to compare CSRs (Control and +Status Registers) between mutliple RISC-V simulators and RISC-V hardware +implementations. + +riscv-probe contains libfemto which is a lightweight bare-metal C library +conforming to a reduced set ot the _POSIX.1-2017 / IEEE 1003.1-2017_ standard. +libfemto can be used as a starting point for bare metal RISC-V programs that +require interrupt handling, basic string routines and printf. + +## Dependencies + +A recent version of `riscv-tools` with a multilib build of RISC-V GCC. + +- [riscv-tools](https://github.com/riscv/riscv-tools) + - [riscv-isa-sim](https://github.com/riscv/riscv-isa-sim) + - [riscv-openocd](https://github.com/riscv/riscv-openocd) + - [riscv-gnu-toolchain](https://github.com/riscv/riscv-gnu-toolchain) +- [riscv-qemu](https://github.com/riscv/riscv-qemu) + +## Build + +The build system uses `CROSS_COMPILE` as the toolchain prefix and expects +the toolchain to be present in the `PATH` environment variable. The default +value for `CROSS_COMPILE` is `riscv64-unknown-elf-` however this can be +overridden e.g. `make CROSS_COMPILE=riscv64-unknown-linux-gnu-`. The build +system expects a multilib toolchain as it uses the same toolchain to build +for _riscv32_ and _riscv64_. Make sure to use `--enable-multilib` when +configuring [riscv-gnu-toolchain](https://github.com/riscv/riscv-gnu-toolchain). +The examples are all built with `-nostartfiles -nostdlib -nostdinc` so either +the RISC-V GCC Newlib toolchain or RISC-V GCC Glibc Linux toolchain can be used. + +To build the examples after environent setup, type: + +``` +make +``` + +## Invocation + +To invoke the probe example in spike and RISC-V QEMU: + +- `$ spike --isa=RV32IMAFDC build/bin/rv32imac/spike/probe` +- `$ spike --isa=RV64IMAFDC build/bin/rv64imac/spike/probe` +- `$ qemu-system-riscv32 -nographic -machine spike -kernel build/bin/rv32imac/spike/probe` -bios none +- `$ qemu-system-riscv64 -nographic -machine spike -kernel build/bin/rv64imac/spike/probe` -bios none +- `$ qemu-system-riscv32 -nographic -machine virt -kernel build/bin/rv32imac/virt/probe` -bios none +- `$ qemu-system-riscv64 -nographic -machine virt -kernel build/bin/rv64imac/virt/probe` -bios none +- `$ qemu-system-riscv32 -nographic -machine sifive_e -kernel build/bin/rv32imac/qemu-sifive_e/probe` -bios none +- `$ qemu-system-riscv64 -nographic -machine sifive_e -kernel build/bin/rv64imac/qemu-sifive_e/probe` -bios none +- `$ qemu-system-riscv32 -nographic -machine sifive_u -kernel build/bin/rv32imac/qemu-sifive_u/probe` -bios none +- `$ qemu-system-riscv64 -nographic -machine sifive_u -kernel build/bin/rv64imac/qemu-sifive_u/probe` -bios none + +## libfemto + +libfemto is a lightweight bare-metal C library for embedded RISC-V development. +libfemto provides: + +- Reduced set of the _POSIX.1-2017 / IEEE 1003.1-2017_ standard +- Simple lightweight hardware configuration mechanism +- RISC-V machine mode functions and macros +- Console and power device drivers + +libfemto implements a reduced set of the _POSIX.1-2017 / IEEE 1003.1-2017_ +standard, with the addition of glibc's `getauxval` API to access hardware +configuration in an auxiliary vector (`__auxv`) that contains tuples +describing the target environment. The auxiliary vector is intended as a +lightweight mechanism to pass dynamic configuration information on embedded +targets, serving as an alternative to compile time constants used during +hardware initialization. The auxiliary vector API has been repurposed to +allow retrieval of hardware configuration parameters such as clock +frequencies and device base addresses for use as a compact alternative to +(DTB) Device Tree Binary, which is not available on small embedded targets. + +libfemto contains the following device drivers: + +- HTIF (Host Target Interface) +- NS16550A UART Console +- SiFive UART Console +- SiFive Test Device +- Semihosting Syscalls + +### Environments + +This project contains a simple build system that allows building applications +targeting multiple embedded environments. A distinguishing characteristic of +the build system is that program objects do not need to be recompiled to target +a different environment, rather they are relinked with a different hardware +configuration and setup function. The config object causes the correct drivers +to be linked via compile time dependencies expressed by symbol references. +The following environments are currently supported: + +- _default_ - environment where IO defaults to `ebreak` +- _spike_- the RISC-V ISA Simulator Golden Model +- _virt_ - the RISC-V VirtIO Virtual Machine +- _qemu-sifive_e_ - QEMU Functional Model of the SiFive E Series +- _qemu-sifive_u_ - QEMU Functional Model of the SiFive U Series +- _coreip-e2-arty_ - SiFive E2 CoreIP Arty A7 FPGA evaluation image + +To create a new environment simply add a directory to `env` with two files: + +- `default.lds` - linker script describing the target's memory layout +- `config.c` - environment specific configuration + +The following is an example configuration from `env/<boardname>/config.c` +showing the auxiliary vector used by `getauxval` via the `setup` function +called by `_start` before entering `main`. + +``` +auxval_t __auxv[] = { + { UART0_CLOCK_FREQ, 32000000 }, + { UART0_BAUD_RATE, 115200 }, + { SIFIVE_UART0_CTRL_ADDR, 0x20000000 }, + { SIFIVE_TEST_CTRL_ADDR, 0x4000 }, + { 0, 0 } +}; + +void setup() +{ + /* + * clock setup code should be placed here and should modify the + * uart clock speed before calling register_console, which calls + * uart_init and reads the uart clock speed from the config array. + */ + register_console(&console_sifive_uart); + register_poweroff(&poweroff_sifive_test); +} +``` + +## Examples + +The build system automatically includes any directory added to `examples` +which contains a `rules.mk` file. + +### hello + +The following is the `rules.mk` file from the _hello_ example: + +``` +$ cat examples/hello/rules.mk +hello_objs = hello.o +``` + +and `hello.c` + +``` +$ cat examples/hello/hello.c +#include <stdio.h> + +int main(int argc, char **argv) +{ + printf("hello\n"); +} +``` + +### symbols + +libfemto linker scripts define the following special symbols: + +Symbol | Value +------ | ----- +`_text_start` | start of `.text` section +`_text_end` | end of `.text` section +`_rodata_start` | start of `.rodata` section +`_rodata_end` | end of `.rodata` section +`_data_start` | start of `.data` section +`_data_end` | end of `.data` section +`_bss_start` | start of `.bss` section +`_bss_end` | end of `.bss` section +`_memory_start` | start of RAM +`_memory_end` | end of RAM + +The symbols example program shows how to access these special symbols. They +can be used for example to locate data section in a flat image in ROM to copy +into memory and to zero the bss section. + +### user + +Simple example program that sets up PMP (Physical Memory Protection) +to allow all memory accesses and then switches to U mode. The code to +set up PMP to allow all memory access is `pmp_allow_all()` in `machine.h`. +The code is derived from _bbl_. + +Note: PMP is enabled by default on systems that implement it, so it is +mandatory to include code to configure PMPs to allow memory access when +switching from M mode to S mode or U mode, otherwise memory accesses will trap. + +### enclave + +Simple enclave example using RISC-V PMP (Physical Memory Protection) + +Physical memory protection is enabled for the program text (RX) +program data (RW), UART, and the hart is switch to U mode, however, +there is only one program and the default trap vector points into +the executable text, so traps are handled in M mode, in the same +executable text segment. + +A future example will load a second process and provide ecall APIs +to the process running in the protected enclave. + +### probe + +`riscv-probe` is a utility that probes the Control and Status Register +address space of a RISC-V emulator, FPGA or board: + +#### qemu-system-riscv32 + +``` +$ qemu-system-riscv32 -nographic -machine spike_v1.10 -kernel build/bin/rv32/spike/probe +isa: rv32imafdcsu +csr: fflags illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: frm illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: fcsr illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: mcycle 0xdbfa9cbd +csr: minstret 0xdc03f6a4 +csr: mcycleh 0x0007c452 +csr: minstreth 0x0007c452 +csr: cycle 0xdc1d7e08 +csr: time illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: instret 0xdc393bf6 +csr: cycleh 0x0007c452 +csr: timeh illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: instreth 0x0007c452 +csr: mvendorid 0x00000000 +csr: marchid 0x00000000 +csr: mimpid 0x00000000 +csr: mhartid 0x00000000 +csr: mstatus 0x00000000 +csr: misa 0x4014112d +csr: medeleg 0x00000000 +csr: mideleg 0x00000000 +csr: mie 0x00000000 +csr: mtvec 0x80000004 +csr: mcounteren 0x00000000 +csr: mscratch 0x00000000 +csr: mepc 0x800002a4 +csr: mcause 0x00000002 +csr: mtval 0x00000000 +csr: mip 0x00000000 +csr: sstatus 0x00000000 +csr: sedeleg illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: sideleg illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: sie 0x00000000 +csr: stvec 0x00000000 +csr: scounteren 0x00000000 +csr: sscratch 0x00000000 +csr: sepc 0x00000000 +csr: scause 0x00000000 +csr: stval 0x00000000 +csr: sip 0x00000000 +csr: satp 0x00000000 +csr: pmpcfg0 0x00000000 +csr: pmpcfg1 0x00000000 +csr: pmpcfg2 0x00000000 +csr: pmpcfg3 0x00000000 +csr: pmpaddr0 0x00000000 +csr: pmpaddr1 0x00000000 +csr: pmpaddr2 0x00000000 +csr: pmpaddr3 0x00000000 +csr: pmpaddr4 0x00000000 +csr: pmpaddr5 0x00000000 +csr: pmpaddr6 0x00000000 +csr: pmpaddr7 0x00000000 +csr: pmpaddr8 0x00000000 +csr: pmpaddr9 0x00000000 +csr: pmpaddr10 0x00000000 +csr: pmpaddr11 0x00000000 +csr: pmpaddr12 0x00000000 +csr: pmpaddr13 0x00000000 +csr: pmpaddr14 0x00000000 +csr: pmpaddr15 0x00000000 +``` + +#### qemu-system-riscv64 + +``` +$ qemu-system-riscv64 -nographic -machine spike_v1.10 -kernel build/bin/rv64/spike/probe +isa: rv64imafdcsu +csr: fflags illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: frm illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: fcsr illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: mcycle 0x0007c452dfeeddd3 +csr: minstret 0x0007c452dff8a765 +csr: mcycleh illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: minstreth illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: cycle 0x0007c452e01f105f +csr: time illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: instret 0x0007c452e03d0a50 +csr: cycleh illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: timeh illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: instreth illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: mvendorid 0x0000000000000000 +csr: marchid 0x0000000000000000 +csr: mimpid 0x0000000000000000 +csr: mhartid 0x0000000000000000 +csr: mstatus 0x0000000000000000 +csr: misa 0x800000000014112d +csr: medeleg 0x0000000000000000 +csr: mideleg 0x0000000000000000 +csr: mie 0x0000000000000000 +csr: mtvec 0x0000000080000004 +csr: mcounteren 0x0000000000000000 +csr: mscratch 0x0000000000000000 +csr: mepc 0x00000000800002f4 +csr: mcause 0x0000000000000002 +csr: mtval 0x0000000000000000 +csr: mip 0x0000000000000000 +csr: sstatus 0x0000000000000000 +csr: sedeleg illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: sideleg illegal_instruction cause=0x00000002 mtval=0x00000000 +csr: sie 0x0000000000000000 +csr: stvec 0x0000000000000000 +csr: scounteren 0x0000000000000000 +csr: sscratch 0x0000000000000000 +csr: sepc 0x0000000000000000 +csr: scause 0x0000000000000000 +csr: stval 0x0000000000000000 +csr: sip 0x0000000000000000 +csr: satp 0x0000000000000000 +csr: pmpcfg0 0x0000000000000000 +csr: pmpcfg1 0x0000000000000000 +csr: pmpcfg2 0x0000000000000000 +csr: pmpcfg3 0x0000000000000000 +csr: pmpaddr0 0x0000000000000000 +csr: pmpaddr1 0x0000000000000000 +csr: pmpaddr2 0x0000000000000000 +csr: pmpaddr3 0x0000000000000000 +csr: pmpaddr4 0x0000000000000000 +csr: pmpaddr5 0x0000000000000000 +csr: pmpaddr6 0x0000000000000000 +csr: pmpaddr7 0x0000000000000000 +csr: pmpaddr8 0x0000000000000000 +csr: pmpaddr9 0x0000000000000000 +csr: pmpaddr10 0x0000000000000000 +csr: pmpaddr11 0x0000000000000000 +csr: pmpaddr12 0x0000000000000000 +csr: pmpaddr13 0x0000000000000000 +csr: pmpaddr14 0x0000000000000000 +csr: pmpaddr15 0x0000000000000000 +``` |