blob: e354fd52c1dc21a54f5b9dab2ea18416e852b655 [file] [view] [edit]
# FPGA telemetry map
FPGA telemetry is data driven. A rows file lists, for every telemetry item,
the FPGA commands to send, how to wait on them, which bytes to keep and how to
turn them into a reading. libnsm runs those rows one MMIO frame at a time and
nsmd only sends the frames and publishes the result. Adding telemetry is a
rows change, not an engine change.
## Files
- `fpga-rules-lp30.rows` - the LP30 map: window, stations and the list of
parts.
- `fpga-rules-lp30-<part>.rows` - one part per telemetry group: its rules
and groups. These are the files to edit.
- `gen-fpga-rules.py` - turns a rows file into its C tables. Run
`python3 gen-fpga-rules.py <name>.rows <name>.c` after editing; the test
`libnsm_fpga_generated_<name>` fails when the C file is stale.
- `fpga-rules-lp30*.c` - generated, never edited by hand.
- `fpga-tables.h` / `.c` - the table model (stations, rows, compares, rule
kinds, state maps, numeric and identity decodes) and its validator.
- `fpga-run.h` / `.c` - the row runner: hands nsmd the next frame, takes the
reply back, applies poll, expect, capture and run_if, fences on a lost grant.
- `fpga-controller.h` / `.c` - the record codec and the reply classifier.
- nsmd side: `nsmFpgaController` (one session per FPGA, the send and reply
loop), `nsmFpgaSensors` (publish per rule kind), `nsmFpgaStatus` and
`nsmFpgaDiscoveryCheck`.
## Rows file
Lines are tokens separated by spaces; `#` starts a comment. Numbers may be
decimal, hex or an expression over `const` names (`IOSSM_DATA+4`,
`0xa0|($reg<<8)`). Blocks end with `end`.
```
map p0
window <type> <control_write> <control_read> <data_write> <completion_read> <status> <word>
part <name> # one line per part file, in link order
end
const NAME value
station <name> <selector> i2c|word|sdm <first_byte> <last_byte>
include <rows file> # take its consts and station names
```
A part file starts with `part <name>`, includes the map file for its station
names and consts, and holds sequences, rules and groups. Rows name their
station; the map file alone binds a name to the selector the FPGA build uses,
so a build that renumbers its stations is a map file change only.
Rows, one FPGA command each:
```
read32 <station> <address> [poll set|any <mask>] [capture item|group] [remember] [expect & <mask> <op> <value> [else end_group <state> <health>]] [if <compare>] [period <us>] [limit <n>] [unless_clean]
write32 <station> <address> <value> [if <compare>]
ack_clear <station> <address> <mask> [if <compare>] [unless_clean|leaves_clean] # write the last polled or remembered word back with mask cleared
pop <station> <status_address> <mask> <data_address> limit <n> [unless_clean|leaves_clean] # drain a FIFO
write <station> <device> <byte> [start] [stop] [if <compare>] # one I2C byte
read <station> <device> [start] [stop] [nack] [capture ...] [expect ...] [if ...]
reads <station> <device> <count> [capture item|group] # a register's bytes: start first, stop and nack last
write_captured <station> word <address> <offset> | byte <device> <offset> [start] [stop]
check <station> <compare> else end_group <state> <health> # compares a buffer, sends nothing
xfer <station> <device> [w <byte>...] [wc <offset>] [r <count>] [capture ...] [expect ...] [if ...]
```
`xfer` is one bounded I2C transaction: up to three write bytes (`wc` takes
one from the group buffer at the offset), then up to four read bytes with the
NACK and STOP. A read over four bytes after one pointer byte expands into
four-byte steps. Use it on controllers that advertise bounded transactions;
`write`, `read` and `reads` send one byte per command.
A compare is `item|group <offset> [w <width>] & <mask> == | >= | <= <value>`, or on a row `word & <mask> <op> <value>` against the word the last read returned;
on `expect` without a buffer it tests the value just read. A row marked
`leaves_clean` that completes in an item that did not fail leaves its station
clean until any row touches that station again or the session changes; rows
marked `unless_clean` are skipped while the station is clean, so a guard that
clears a stale response runs only when something may have left one. `<state>` is
enabled, starting, standby, absent, unavailable or fault; `<health>` is ok,
warning or critical.
Sequences hold lines that repeat; `$name` is replaced by the argument, and an
`if` on the `use` line gates every row of the sequence:
```
seq hub_ready st
read32 $st IOSSM_RESPONSE_STATUS poll set IOSSM_RESPONSE_READY
end
use hub_ready 28
use bank_read 1 $reg $count if group 8 & 0x3 >= 1
```
Rules and groups:
```
rule <Name> # the suffix an entity-manager Name ends with
kind state | numeric <sensor_type> | identity | array tx_power|rx_power|tx_fault|rx_los
group <Group>
state <mask> <value> <state> <health> # state rules: first match wins
state default <state> <health>
word group <offset> # a row-less state rule reads the group buffer
decode <format> item|group <offset> [shift n] [width n] [signed] [scale x] [bias x] [range lo hi] [count n stride bits]
field serial|model|part|manufacturer|revision hex_le|hex_be|ascii item|group <offset> <length>
valid_if <compare> # publish only when it holds
run_if <compare> # skip the item this round when it fails
<rows>
cleanup
<rows run on every exit once a write went out>
end
group <Group>
setup
<rows run once per round before the items>
cleanup
<rows run after the last item>
end
```
Formats: fixed (a bit field of a little-endian word: shift, width, signed),
u16be, s16be.
## To add a telemetry item
1. Write its rows in the part file of its group, or start a new part file
and list it in `fpga-rules-lp30.rows`: the words or bytes to send, the
reads to repeat until a condition holds, the reads to capture, the cleanup
that leaves the station clean. Reuse a `seq` when one fits.
2. Give the rule its kind and decode: a state map, a numeric spec, identity
fields or an array spec. Items that share a bus setup and a refresh rate
go in one group; its setup rows fill the group buffer that row-less items,
`run_if` and `check` read. A device read at two rates gets two groups with
the same setup, one per rate, so every round reads its whole group.
3. Regenerate the C files, list a new part's C file in `libnsm/meson.build`
and its rows file in the test list, and add an entity-manager entry whose
Name ends with the rule name.
Every row is checked against the station policy before it is sent, so a wrong
row is a logged rule bug, never a faulted station.
## When the engine also changes
Extend the engine, as a separate change, only when an item needs a new row
op, a new numeric format or a new D-Bus property. Once it exists, every later
item that uses it is a rows change again.