Skip to content

Commit 77427d9

Browse files
ccattutoccattuto
committed
expanded documentation
1 parent 22ad1e9 commit 77427d9

File tree

2 files changed

+39
-30
lines changed

2 files changed

+39
-30
lines changed

‎README.md‎

Lines changed: 35 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,33 @@ pip install -r requirements.txt
6060

6161
## 🚀 Usage
6262

63+
### ▶️ Command-Line Options
64+
65+
`riscv-emu.py` accepts the following options:
66+
67+
| Option | Description |
68+
|-------------------------|-----------------------------------------------------------------------------|
69+
| `--regs REGS` | Print selected registers at each instruction |
70+
| `--trace` | Log the names of functions traversed during execution |
71+
| `--syscalls` | Log Newlib syscalls |
72+
| `--traps` | Enable trap tracing |
73+
| `--check-inv` | Enable runtime invariant checks on stack/heap alignment and boundaries |
74+
| `--check-ram` | Check validity of memory accesses |
75+
| `--check-text` | Ensure the `.text` segment remains unmodified during execution |
76+
| `--check-all` | Enable all checks |
77+
| `--start-checks WHEN` | Condition to enable checks (auto, early, main, first-call, 0xADDR) |
78+
| `--init-regs VALUE` | Initial register state (zero, random, 0xDEADBEEF) |
79+
| `--init-ram PATTERN` | Initialize RAM with pattern (zero, random, addr, 0xAA) |
80+
| `--ram-size KBS` | Emulated RAM size (kB, default 1024) |
81+
| `--timer {csr,mmio}` | Enable machine timer |
82+
| `--uart` | Enable PTY UART |
83+
| `--blkdev PATH` | Enable MMIO block device |
84+
| `--blkdev-size NUM` | Block device size in 512-byte blocks (default 1024) |
85+
| `--raw-tty` | Enable raw terminal mode |
86+
| `--no-color` | Remove ANSI colors in debugging output |
87+
| `--log LOG_FILE` | Log debug information to file `LOG_FILE` |
88+
| `--help` | Show usage help and available options |
89+
6390
### Compiling Examples
6491
```
6592
make all
@@ -146,42 +173,20 @@ Run an example using the memory-mapped UART,
146173
./riscv-emu.py --uart prebuilt/test_peripheral_uart.elf
147174
000.001s [INFO] [UART] PTY created: /dev/ttys015
148175
```
149-
and connect to the serial device using your favorite terminal program:
150-
```
151-
screen /dev/ttys015 115200
152-
```
176+
and connect to the serial device using your favorite terminal program, e.g., `screen /dev/ttys015 115200`.
153177

154178
Run an example using a file-backed block device:
155179
```
156180
./riscv-emu.py --blkdev=image.img prebuilt/test_peripheral_blkdev.elf
157181
```
158182

159-
### ▶️ Command-Line Options
160-
161-
`riscv-emu.py` accepts the following options:
162-
163-
| Option | Description |
164-
|-------------------------|-----------------------------------------------------------------------------|
165-
| `--regs REGS` | Print selected registers at each instruction |
166-
| `--trace` | Log the names of functions traversed during execution |
167-
| `--syscalls` | Log Newlib syscalls |
168-
| `--traps` | Enable trap tracing |
169-
| `--check-inv` | Enable runtime invariant checks on stack/heap alignment and boundaries |
170-
| `--check-ram` | Check validity of memory accesses |
171-
| `--check-text` | Ensure the `.text` segment remains unmodified during execution |
172-
| `--check-all` | Enable all checks |
173-
| `--start-checks WHEN` | Condition to enable checks (auto, early, main, first-call, 0xADDR) |
174-
| `--init-regs VALUE` | Initial register state (zero, random, 0xDEADBEEF) |
175-
| `--init-ram PATTERN` | Initialize RAM with pattern (zero, random, addr, 0xAA) |
176-
| `--ram-size KBS` | Emulated RAM size (kB, default 1024) |
177-
| `--timer {csr,mmio}` | Enable machine timer |
178-
| `--uart` | Enable PTY UART |
179-
| `--blkdev PATH` | Enable MMIO block device |
180-
| `--blkdev-size NUM` | Block device size in 512-byte blocks (default 1024) |
181-
| `--raw-tty` | Enable raw terminal mode |
182-
| `--no-color` | Remove ANSI colors in debugging output |
183-
| `--log LOG_FILE` | Log debug information to file `LOG_FILE` |
184-
| `--help` | Show usage help and available options |
183+
Run CircuitPython:
184+
```
185+
./riscv-emu.py --timer=mmio --ram-size=4096 --uart --blkdev=prebuilt/circuitpy_fatfs.img prebuilt/circuitpython.elf
186+
000.001s [INFO] [UART] PTY created: /dev/ttys015
187+
000.002s [INFO] [BLOCK] Opening block device image: prebuilt/circuitpy.img
188+
```
189+
and connect to the console using your favorite terminal program, e.g., `screen /dev/ttys015 115200`.
185190

186191
## 🧪 Running Unit Tests
187192
```

‎tests/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,7 @@
2929
- `test_newlib12.c`: Soft floating point test.
3030

3131
- `test_newlib13.c`: Test using `setjump`/`longjump` C exception handling.
32+
33+
- `test_peripheral_uart.c`: Test the memory-mapped UART implementation backed by a pseudo-terminal on the host. Run this example with the `--uart` option, and then connect to the indicated PTY using your preferred terminal program, e.g., `screen /dev/ttys015 115200`.
34+
35+
- `test_peripheral_blkdev.c`: Test the memory-mapped block device implementation backed by a file on the host. Run this example with the `--blkdev=image` option, where `image` is the filename you want to use. If the file does not exist, it will be created by the emulator.

0 commit comments

Comments
 (0)