refactor(errors): adopt reportable error terminology

This commit is contained in:
Onur Özkan committed 2026-08-23 00:49:25 +03:00
1 parent 21e9497915
commit 9fec2fa095
92 files changed
+270 -269

No files matched your search

+9 -9
View File
@@ -11,18 +11,18 @@ kaptan_log::trace!("prediction step complete");
```
All five macros emit `KAPTAN_LOG`; their level never selects a different wire
message. When a terminal typed firmware error escapes a reviewed
`#[kaptan_err_propagate::propagate]` function, it makes one bounded admission attempt
message. When a reportable firmware error escapes a reviewed
`#[kaptan_err_reportable::propagate]` function, it makes one bounded admission attempt
to the separate `KAPTAN_ERROR` ingress.
`kaptan-log` formats each event once into a fixed bounded buffer and never
sends MAVLink, allocates, blocks, changes flight state, or touches DMA. The
composition fans the event into each enabled sink; the sole MAVLink worker
drains its bounded sink queue. Ordinary log text uses one 160-byte bounded
record. Typed-error records contain the explicit ID and a static reference to
the annotated propagation boundary until the MAVLink adapter copies its
record. Reportable-error records contain the explicit ID and a static reference
to the reporting point until the MAVLink adapter copies its
`file:line` into the 96-byte `raised_at` field.
Logs and typed errors use independent fixed atomic
Logs and reportable errors use independent fixed atomic
ingresses; interrupt and worker producers make one nonblocking admission
attempt, and only the MAVLink worker encodes or transmits a retained event.
Panic and hard-fault paths still do not attempt live telemetry.
@@ -30,7 +30,7 @@ Panic and hard-fault paths still do not attempt live telemetry.
## Receiver contract
`definitions/kaptan/log.xml` and `definitions/kaptan/error.xml` separate
ordinary logs and typed errors:
ordinary logs and reportable errors:
```text
KAPTAN_LOG { level, flags, message_length, message[160] }
@@ -46,12 +46,12 @@ or the complete field when no zero is present.
`KAPTAN_LOG.level` accepts only Error (3), Warning (4), Info (6), and Debug
(7); Trace is encoded as Debug (7) plus the `TRACE` flag. Other MAVLink
severity numbers are not Kaptan log levels.
The `KAPTAN_ERROR` message kind already means a typed firmware error, so it has
The `KAPTAN_ERROR` message kind already means a reportable firmware error, so it has
no redundant level or flags field.
`error_id` is the stable nonzero catalog number explicitly assigned to the
Rust error variant. Renaming or reordering a variant does not change it.
`raised_at` identifies the annotated boundary where the `Err` entered
`raised_at` identifies the reporting point where the `Err` entered
diagnostics. Error details requiring
machine action stay in their owning protocol, notably `KAPTAN_CONFIG_RESULT`.
Delivery is bounded and lossy under link pressure; heartbeat and safety
@@ -65,7 +65,7 @@ event.
The single restart-only `mavlink.logging.level_filter` field uses the familiar
Off, Error, Warn, Info, Debug, and Trace choices. `Info`, for example, accepts
Error, Warn, and Info log events. `Off` suppresses `KAPTAN_LOG` on MAVLink
without suppressing typed `KAPTAN_ERROR` reports or events sent to another
without suppressing reportable `KAPTAN_ERROR` events or logs sent to another
sink. There is no separate enable flag and no MAVLink-specific set of extra
runtime log levels. F722 uses the validated filter recovered at boot, falling
back to its board factory when the journal is empty or invalid.