Skip to content

Latest commit

 

History

History
207 lines (177 loc) · 16 KB

cli.md

File metadata and controls

207 lines (177 loc) · 16 KB

The command line

embsim is one binary that links the core. Every subcommand is a client of the session protocol (SPEC-008); --json switches any output to the machine-readable report of SPEC-008 §8.

Command What it does
embsim run PROJECT [--until T] [--scenario FILE] [--policy P] [--probe TARGET]... [--record FILE] [--coverage FILE] [--profile FILE] [--stack FILE] [--faults FILE] [--board ID] [--json] loads the project, runs it headless to --until (default 50 ms) or through the scenario's inputs and assertions, prints nets, outputs, assertions and statistics; with --coverage, --profile, --stack and --faults, writes the firmware's coverage, profile, stack depths and faults (below); exit 0 ok, 1 an assertion failed, 2 usage or load error, 3 a fatal diagnostic
embsim run --target BOARD --image FILE [--until T] [--until-text TEXT] [--console] [--json] one board of the catalog (emblink/arduino_uno) running an image, with no project: the way an RTOS's or a library's test runner uses the simulator as an emulated target (CI). --console prints the board's console as the run goes (to stderr with --json); --until-text ends the run at the millisecond the text appears on a console (ended reason until_text), exit 1 when it never does. With a project, --image [ID=]FILE replaces a board's image
embsim run PROJECT ... [--build] [--dump-regs PERIPH[,BOARD.PERIPH]...] [--circuit-profile FILE] [--rtos FILE] [--quiet] --build first builds each board whose image is missing or older than its sources (mcu.stale_image), as embsim build would; --dump-regs prints the named peripherals' registers as the run leaves them, each with its set fields (SR = 0x00C0: TC TXE); --circuit-profile writes the analog islands by solve time, the nets by edges and the parts by events (.json for JSON, - to stderr); --rtos writes each board's FreeRTOS tasks (below); --quiet leaves out the nets and components
embsim export svg PROJECT [-o FILE] [--theme light|dark] the schematic sheet as SVG, as the workbench lays it out: symbols, boards as the block of their ports, wires, net labels and notes, and a dashed line for a net no wire draws
embsim export svg PROJECT --component ID [--at T] [--scenario FILE] [--scale N] [-o FILE] what a display shows at T after the scenario's inputs to then: a graphic display's pixels (an SSD1306's), a character module's lines (an HD44780's)
embsim plan BOARD --needs spi,i2c,uart,can,pwm:N,adc:N,gpio:N [--prefer arduino|CONNECTOR] [--header FILE] [--json] a pin plan on the board's headers: each peripheral on one instance, each signal on a pin whose alternate function carries it (the MCU's io.alternate), no pin twice, clear of what the board's own nets put on a pin (an LED, a crystal, the console) and never the SWD pins; --header writes the pins as C defines. An MCU without an alternate-function table gets GPIO only (exit 1 for the rest)
embsim replay RECORDING [--allow-drift] [--json] runs a recording again: its project from reset, its inputs at their times, to its end, comparing what the run observes with what was recorded, in order; exit 0 when all match, 4 at the first divergence (both observations printed, or in divergence with --json), 2 when the project or an image changed since the recording unless --allow-drift
embsim record to-scenario RECORDING [-o FILE] [--assert probes,serial|none] [--name N] a scenario from a recording: its inputs at their times, and assertions on each digital probe's last level and edges and each serial probe's text
embsim validate PATH... loads each project through the real loader and reports its diagnostics (descriptions are validated against the schemas by tools/validate.py)
embsim serve [PROJECT] [--port N] [--host H] [--ui DIR] [--open] [--allow-origin ORIGIN]... [--serial B1]... [--stlink [PORT]] [--usbip [PORT]] [--run] the WebSocket endpoint on loopback plus the workbench assets (the built ui/apps/workbench/dist when present, else a built-in console page); --allow-origin admits browser pages from another origin, such as a desktop webview (SPEC-008 §1). Without a project the session starts empty and the workbench opens one; --stlink shares the boards' ST-LINK probes on the host as stlink-server does, for OpenOCD and the IDEs, and --usbip serves the bench's free USB devices (the ST-LINK itself) over USB/IP for the tools that open a USB device (docs/user/nucleo-st-link.md)
embsim ide PROJECT [--embsim CMD] [--force] VS Code's launch configurations and tasks for the project's boards in .vscode next to it: through a board's own probe with OpenOCD (the NUCLEO's ST-LINK) and on EmbSIM's GDB server for any board (docs/user/nucleo-st-link.md)
embsim sidecar [PROJECT] the protocol over stdin and stdout, one JSON object per line, for the desktop shell and IDEs
embsim gdb PROJECT [--board B] [--port N] [--host H] runs the project and serves GDB's remote protocol for one board's MCU on loopback (default port 3333): target extended-remote :3333 in GDB, gdb-remote 3333 in LLDB; see firmware
embsim build PROJECT [--board B] [--toolchain T] builds a board's firmware from its firmware block (sources, flags, linker script) with the named or the block's toolchain profile, writing the block's image
embsim toolchains the toolchain profiles and whether each is found on this host, with its version
embsim catalog list [KIND] | search QUERY | info ID | libraries [--library DIR] browses the bundled catalog and extra libraries
embsim catalog validate [DIR] [--library DEP] [--json] instantiates every part of a library and runs its fixtures (bundled catalog by default); exit 1 unless all are ok
embsim catalog new component|board NAME [--library DIR] [--lua] writes a part that validates as written (SDK, sdk/README.md)
embsim catalog install DIR|ARCHIVE.zip|URL [--to LIBRARIES_DIR] [--force] validates a library and copies it into the user library directory: a directory, a zip archive of one (the library at its top or in its top directory), or an http(s):// URL to such an archive, fetched with curl (SPEC-014 §6)
embsim board list | info ID boards and their descriptions
embsim models the model primitives the core implements, digital and electrical
embsim version engine, protocol and ABI versions

Times are written with units: 10ms, 1.5us, 12345ps, 2s. The bundled catalog is found next to the executable (../catalog, ../../catalog, ../../../catalog from a build tree), from EMBSIM_CATALOG, or from the source tree the binary was built from. --library DIR adds a library; projects also name libraries relative to their own file.

Recordings

embsim run ... --record FILE writes what the run did (SPEC-012): the engine, the project's and each image's SHA-256, the policy, every input in order, and the observations, each with its time in picoseconds:

  • irq: a core entered an exception or interrupt (board, core on a part with two, n: a Cortex-M's exception number, an AVR's vector, a RISC-V cause, 16 plus an interrupt's cause or vector on RISC-V and MIPS, a PIC24's vector number);
  • probe: a digital probe's level changed (0, 1, Z, X), its first level at reset included;
  • serial: each serial probe's text at the end; diagnostic: each warning, error or fatal code; end.

A run that records starts from reset, as a scenario does, so embsim replay sees the same thing from the same start. In the workbench, the protocol's record.start and record.stop record from the moment recording starts; replay compares from there.

Coverage, profile, stacks and faults

--coverage FILE, --profile FILE, --stack FILE and --faults FILE watch every board's firmware (one board's with --board ID) instruction by instruction and write, at the end of the run, which source lines and functions ran and where the time went (- writes to stderr). Functions come from the image's ELF symbol table, lines from its DWARF line tables, so build it with -g; a HEX image or a stripped ELF is refused.

  • --coverage-format text (the default): per source file, its lines and functions hit, and the source with each line's count beside it, as gcov lays it out (##### a line with code that never ran, - a line with none). A line's count is its most-executed instruction's, a function's its first instruction's: the times it was entered.
  • --coverage-format lcov: an lcov tracefile (TN the board, SF, FN, FNDA, DA, LF, LH), which genhtml and CI coverage services read.
  • --profile-format text (the default): each function's own and inclusive instructions and cycles, and its calls, by own cycles. The cycles are the instructions' (and exception entries'); the time a core sleeps in WFI is no instruction's, and the header gives the machine's elapsed cycles beside them.
  • --profile-format collapsed (or collapsed-insns): one line per call path, Reset_Handler;main;putc 1234, by cycles (or instructions), for flamegraph.pl, speedscope and inferno; a part's second core's paths start with core1, and several boards' with the board's ID.
  • --stack-format text (the default): each core's stacks, their top, how deep they went and of how much (down to the link's __stack_limit, else the end of .data and .bss, else the RAM's end), an overflow, and the functions by depth: the deepest sp in each, its own frame (as -fstack-usage counts it) and its depth with its callees. A Cortex-M's process stack (PSP, an RTOS's threads) is reported beside its main stack. The main stack going past its limit is the error diagnostic mcu.stack_overflow, naming where; the run goes on.
  • --faults-format text (the default): each fault the firmware took, as its core took it: a Cortex-M's HardFault, MemManage, BusFault or UsageFault with HFSR and CFSR in words (FORCED, PRECISERR at 0x30000000), a RISC-V exception with mcause and mtval, a MIPS exception with BadVAddr, a PIC24 trap; the instruction, the registers (a Cortex-M's stacked frame), a backtrace from the image's .debug_frame (build with -g), else from the calls the core was seen to make, and the handler it goes to. Each is also the error diagnostic mcu.fault; the run goes on.
  • json for any: what the protocol's analysis.coverage, analysis.profile, analysis.stack and analysis.faults return (SPEC-008 §5). With --json, the run's report also carries coverage, profile, stack and faults summaries.

Calls and returns are recognized from each core's instructions (BL and BX on a Cortex-M, JAL and JALR on RISC-V, CALL and RET on an AVR, MIPS's JAL and JR after their delay slots, a PIC24's CALL and RETURN), and exception entries and returns from the core itself, so a handler's time is its own. The analyses cost little: the Pico's two-core scenario runs in the same wall time with both on.

embsim run examples/bluepill-button-led/project.json --scenario examples/bluepill-button-led/scenarios/press.json \
    --coverage cov.info --coverage-format lcov --profile prof.folded --profile-format collapsed
genhtml cov.info -o coverage-html
flamegraph.pl prof.folded > profile.svg

Diagnostics go to stderr as embsim: <severity>: <code> (<subject>) followed by the message; their codes are listed in diagnostics.

Timing measurements

--measure [NAME=]FROM..TO (up to 16) measures, each time it happens, the cycles and the simulated time from one boundary to the next. The report goes to --measure-out FILE; the default - is stderr, and a .json file gets JSON. A boundary is:

Boundary When it is stamped
SYMBOL or 0xADDR the instruction at that address starts (before its own cycles, after any exception sequence before it)
exc:N the core starts taking exception N (before the entry's or tail-chain's cycles)
pend:N exception N becomes pending: an interrupt asserted, a PendSV or an SVC requested, at the cycle the device or instruction did it
ret:N exception N's return is done: the first instruction after it starts, or the tail-chain that takes its place starts

N is a number or a name: Reset, NMI, HardFault, MemManage, BusFault, UsageFault, SVCall, DebugMon, PendSV, SysTick, or IRQn (exception 16 + n). A sample starts at the first FROM after the last sample and ends at the next TO. When FROM and TO are the same boundary, each occurrence ends one sample and starts the next, which measures a period.

embsim run --target emblink/nucleo_f446re --image freertos.elf --until 200ms \
    --measure ctxsw=pend:PendSV..ret:PendSV --measure tick=exc:SysTick..exc:SysTick

ctxsw is an RTOS context switch, from the PendSV request to the first instruction of the task switched to. tick is the SysTick period.

The numbers are simulated: cycles of the target's core, converted to time at the core clock that ran them. The host's speed does not change them, and the same image and inputs give the same numbers every time. The host's wall time is reported on a line of its own, apart from the measurements. The simulator watches from outside, so a measurement adds no instruction or cycle to the firmware; a DWT.CYCCNT read in the program does add its own.

Measurements are as exact as the target's timing model. See docs/engineering/timing-fidelity.md for what each core models. On Cortex-M, instructions are estimated from the TRM's table, while exception entry, return and tail-chaining follow the TRM; flash wait states are not modelled yet.

Traces

--trace FILE records every boundary as it happens:

  • each instruction starting, with its address and function;
  • each exception becoming pending, being taken, and returning;
  • each load and store the core makes, right after its instruction (an exception's entry: its stacking and its vector fetch). Each carries its address, its size and value (or bus error), and the register it names (USART2.DR, RCC.CR, scs+0xd04 for the core's own system space). --trace-accesses peripherals keeps the ones plain memory does not answer, none none (all by default).

Each event carries the core's cycle and the simulated time. --trace-start BOUNDARY starts recording at the first such boundary (for example pend:PendSV), and --trace-limit N caps the events (100 000 by default; the file says how many it dropped).

A file ending in .vcd gets a value change dump at 1 ps resolution, with pc, the exception active, the last exception pended, the cycle count, and for the data accesses their address, data, write (1 for a store) and an access event. GTKWave and other waveform viewers open it. Any other name gets a tab-separated table.

embsim run --target emblink/nucleo_f446re --image freertos.elf --until 50ms \
    --trace switch.vcd --trace-start pend:PendSV --trace-limit 400

FreeRTOS tasks

--rtos FILE reads the FreeRTOS kernel's tasks from the firmware's memory at the end of the run, as a debugger's RTOS awareness does: pxCurrentTCB, the ready, delayed, suspended and pending lists and each TCB, through the image's symbols, with the structures' layouts from its DWARF (so FreeRTOSConfig.h moves nothing). For each task: its state (running, ready, blocked, suspended, deleted), priority, what it waits on (a delay until a tick, a notification index, a queue named by the queue registry, another event list) and for how long, its stack's high-water mark (the 0xA5 fill the kernel writes when stack checking, the trace facility or uxTaskGetStackHighWaterMark is on) and its notifications by index. A scenario's rtos assertion samples them each millisecond:

{"id": "stacks", "always": true, "rtos": {"stack_free_min": 64}},
{"id": "waits", "always": true, "rtos": {"blocked_max": "1s", "ignore": ["rx_task"]}}

Not read: SMP kernels (one current task per core), 16-bit ports (an AVR's), and without DWARF the notification state. A task that wakes and blocks again on the same indefinite wait within a millisecond counts as one stretch.