API reference
Target API of release 0.5.0, API_VERSION=3. Each group gives signatures, the first release, API 3 changes and examples.
API 3 in short
An ordinary def runs operations in order. In async def, navigation (reach, step, until, finish, resume, reset) and call are awaited; resume(sync=False) lets the target go and await wait/halt wait with a timeout. Reads, writes, checks and journal records need no await. Expressions never call target functions.
Method groups
Scenario: def and async def
The decorator declares a scenario; the function form selects the execution mode.
Navigation: reach, step, until, finish
Run to a function or line, step, run until return. Each operation returns the stop.
Live window: resume, wait, halt
Let the target run, wait for a stop with a timeout, halt with confirmation.
Data: read and write
Read an object by name or expression, write a value or a table of writes.
Expressions and memory: evaluate, memory, symbol
An expression value of the required type; SRAM/Flash bytes at a symbol address.
Registers: mmio.read and mmio.write
One direct request to a register named in the SVD snapshot, with access-right and effect checks.
Checks: check, matchers, refused
A named check or a table of checks; an expected API refusal with its code.
Injection: ret and call
Replace the return of the current function; call a firmware function and get its result.
Points: breakpoint, watch, Point, clear
Breakpoints and watchpoints as Point objects with state and removal.
Journal and SKIP: record, records, skip
Arbitrary data into the report; selecting your records; ending a non-applicable scenario.
Context: profile, registers, frames, locals
Run and project data; core registers, call stack, locals and arguments.
Reset and GDB commands: reset, execute
Reset the target with a halt; an arbitrary GDB command as a low-level escape.
Errors: ApiError, CheckFailed, RecordError
An operation refusal with code, stage and effect; a failed check; a journal error.
Removed names
Available from 0.1.0-rc.1 to 0.3.0 (with a deprecated warning in 0.3.0), removed in 0.4.0.
| Name | Replacement |
|---|---|
value | read, evaluate |
fields | read(path, fields=…), check(rows) |
set_value | write |
force_return | ret |