Skip to content

Commit

Permalink
Docs: Describe +firmware, +max_sim_time
Browse files Browse the repository at this point in the history
Added "Simulation parameters" section to Simulate.md describing the
`+firmware` and `+max_sim_time` plusargs, and also mention the
`MAX_SIM_TIME` Makefile variable for Verilator simulation.
  • Loading branch information
Javier Mora committed Jan 10, 2025
1 parent 844ff8b commit b63a2c5
Showing 1 changed file with 22 additions and 1 deletion.
23 changes: 22 additions & 1 deletion docs/source/How_to/Simulate.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,27 @@ and type to run your compiled software:
make run PLUSARGS="c firmware=../../../sw/build/main.hex"
```

## Simulation parameters

You may pass additional simulation parameters to the generated simulation executable, in the form of *plusargs*: `+<parameter>=<value>`.

- `+firmware=<path>`:
Loads the hex file specified in `<path>` into memory.
This allows you to run a compiled executable directly, as if it were already written in memory since the beginning of the simulation.
For example, `./Vtestharness +firmware=../../../sw/build/main.hex` will launch the Verilator simulation and instruct it to load the compiled application executable into memory and run it.

- `+max_sim_time=<time>`:
Runs the simulation for a maximum of `<time>` clock cycles.
This is useful in case your application gets stuck in a certain point and never finishes; this parameter will force the simulation to terminate after a certain time so that you can later analyze the generated `waveform.vcd` file.
In that case, the simulation executable will exit with a return code of 2, indicating premature termination.
If this parameter is not provided, the simulation will run until the program finishes (the `main()` function ends).

Alternatively, you may add a time suffix (`s`, `ms`, `us`, `ns`, `ps`) to run the simulation until the specified simulation time has been reached (1 clock cycle = 10ns).
This is, `+max_sim_time=750us` is the same as `+max_sim_time=75000`.
(Note that there's no space between the number and the unit, and that fractional values are not supported.)

If you're launching the Verilator simulation via `make`, you may pass this parameter via the `MAX_SIM_TIME=` command line argument, e.g. `make run-helloworld MAX_SIM_TIME=750us`.

## UART DPI

To simulate the UART, we use the LowRISC OpenTitan [UART DPI](https://github.com/lowRISC/opentitan/tree/master/hw/dv/dpi/uartdpi).
Expand All @@ -157,4 +178,4 @@ For example, to see the "hello world!" output of the Verilator simulation:
cd ./build/openhwgroup.org_systems_core-v-mini-mcu_0/sim-verilator
./Vtestharness +firmware=../../../sw/build/main.hex
cat uart0.log
```
```

0 comments on commit b63a2c5

Please sign in to comment.