Tiny1-C vendor mailbox protocol: snapshot reads, controls and evidence text. More...

Go to the source code of this file.
Data Structures | |
| struct | state_query |
| One mailbox getter, shared by snapshot reads and control read-back. More... | |
Functions | |
| static unsigned | remaining_ms (const struct lwir_state_io *io, uint64_t deadline) |
Time left before deadline, as a per-transfer timeout. | |
| static bool | transfer (const struct lwir_state_io *io, uint64_t deadline, bool input, uint16_t address, uint8_t *data, unsigned length, struct lwir_state_value *value) |
| Perform one deadline-bounded mailbox transfer and classify failure. | |
| static bool | valid_value (enum lwir_state_field field, const uint8_t *data) |
| Plausibility check of one snapshot reply. | |
| void | lwir_state_read (const struct lwir_state_io *io, struct lwir_device_state *state) |
| Read all fields of struct lwir_device_state within LWIR_STATE_BUDGET_MS. | |
| bool | lwir_control_valid (const struct lwir_control_request *request) |
| Range-check a control request (vendor-header limits). | |
| static bool | control_idle (const struct lwir_state_io *io, uint64_t deadline, struct lwir_state_value *reply) |
| Poll the mailbox status until idle, an error class, or the deadline. | |
| static const struct state_query * | control_query (enum lwir_control_kind kind) |
| Map a control to the getter row whose subcommand/parameter it writes. | |
| static bool | control_readback (const struct lwir_state_io *io, uint64_t deadline, const struct state_query *query, struct lwir_control_result *result) |
| Read one extended two-byte setting back from the device. | |
| bool | lwir_state_control_read (const struct lwir_state_io *io, enum lwir_control_kind kind, struct lwir_control_result *result) |
| Targeted read of one controllable setting; performs no setting writes. | |
| bool | lwir_state_control (const struct lwir_state_io *io, const struct lwir_control_request *request, struct lwir_control_result *result) |
| Apply one setting with read-back verification, or trigger FFC. | |
| bool | lwir_state_u16 (const struct lwir_device_state *state, enum lwir_state_field field, uint16_t *value) |
| Decode a validated big-endian two-byte snapshot field. | |
| size_t | lwir_state_format (const struct lwir_device_state *state, char *output, size_t capacity) |
| Render snapshot evidence as key=value lines for the JPEG APP14 segment. | |
Variables | |
| static const struct state_query | queries [LWIR_STATE_FIELDS] |
| Getter table indexed by enum lwir_state_field; names become evidence keys. | |
Detailed Description
Tiny1-C vendor mailbox protocol: snapshot reads, controls and evidence text.
Transport-agnostic implementation of the protocol summarised in lwir_state.h. Every operation is driven by an absolute deadline: each transfer timeout is the remaining budget capped at 50 ms, and every poll loop is bounded both by an iteration cap and by that deadline, so a stuck device cannot stall the capture path. Storage is caller-owned or on the stack; no heap, no memcpy.
Definition in file lwir_state.c.
Function Documentation
◆ control_idle()
|
static |
Poll the mailbox status until idle, an error class, or the deadline.
- Parameters
-
io Transport. deadline Absolute deadline in now_us() microseconds. reply Receives device_status and the failure status.
- Returns
- True once status reads 0. False with LWIR_STATE_UNSUPPORTED, LWIR_STATE_INVALID or LWIR_STATE_IO_ERROR for an error class, LWIR_STATE_CANCELLED, or LWIR_STATE_TIMEOUT when the deadline or the 512-poll cap is reached; transfer failures keep transfer()'s status.
Pauses at most 10 ms between polls. The larger cap than the snapshot's 32 polls fits the 1-5 s control budgets.
Definition at line 255 of file lwir_state.c.
◆ control_query()
|
static |
Map a control to the getter row whose subcommand/parameter it writes.
- Parameters
-
kind Control kind.
- Returns
- Table row, or NULL for FFC/unknown kinds (no readable value).
- Note
- Reusing the snapshot table keeps getter, setter and range limits in one place.
Definition at line 283 of file lwir_state.c.
◆ control_readback()
|
static |
Read one extended two-byte setting back from the device.
- Parameters
-
io Transport. deadline Absolute deadline in now_us() microseconds. query Getter row (extended command 0x14). result Receives reply bytes, length 2 and the decoded readback.
- Returns
- True for an in-range value. False with the failing step's status, or LWIR_STATE_INVALID when the value is outside the vendor range (readback is still stored for diagnostics).
Writes the held half (0x9d00), triggers with the second half (0x1d08, byte 15 = reply length 2), waits idle, then reads the big-endian reply at 0x1d10.
- Precondition
- The mailbox is idle.
Definition at line 307 of file lwir_state.c.
◆ lwir_control_valid()
| bool lwir_control_valid | ( | const struct lwir_control_request * | request | ) |
Range-check a control request (vendor-header limits).
Check a control request against the vendor value ranges.
- Returns
- True for a known kind with an in-range value; FFC accepts only 0.
Definition at line 231 of file lwir_state.c.
◆ lwir_state_control()
| bool lwir_state_control | ( | const struct lwir_state_io * | io, |
| const struct lwir_control_request * | request, | ||
| struct lwir_control_result * | result ) |
Apply one setting with read-back verification, or trigger FFC.
Apply one setting or trigger FFC, then confirm it.
- Returns
- True when the setter was verified or FFC was acknowledged. False on invalid input, budget overflow or any failed step; result->submitted tells whether the device may already have acted.
- Budget: 1 s; gain and FFC 5 s (gain may involve internal correction).
- Always wait for an idle mailbox first so a pending command is not overwritten.
- FFC: standard command 0d c1 02 (OOC+B combined update, not shutter open/close) at 0x1d00, then a fixed 3 s wait (300 x 10 ms) mirroring the vendor's special 3000 ms poll delay, then an idle check. Result is an acknowledgement only; verified stays false.
- Setters: SET subcommand = getter + 0x40 (0x83->0xc3 image, 0x85->0xc5 TPD), value big-endian in header bytes 6..7 (verified against vendor reference source). Held half to 0x9d00, trigger half to 0x1d08, wait idle, read back, and mark verified only on an exact match.
- Warning
- After a false return with submitted set, never replay the command; read the setting back to learn the device state.
Definition at line 366 of file lwir_state.c.
◆ lwir_state_control_read()
| bool lwir_state_control_read | ( | const struct lwir_state_io * | io, |
| enum lwir_control_kind | kind, | ||
| struct lwir_control_result * | result ) |
Targeted read of one controllable setting; performs no setting writes.
Read one controllable setting without writing anything.
- Returns
- True with verified and readback set; false on bad arguments or any failed step (see result->reply).
Budget 1 s: wait idle, then control_readback(). Only the getter header is written, so submitted stays false.
Definition at line 331 of file lwir_state.c.
◆ lwir_state_format()
| size_t lwir_state_format | ( | const struct lwir_device_state * | state, |
| char * | output, | ||
| size_t | capacity ) |
Render snapshot evidence as key=value lines for the JPEG APP14 segment.
Render a snapshot as key=value evidence lines for the JPEG APP14 segment.
- Returns
- Bytes written excluding the NUL; 0 on NULL/zero-sized output, overflow, or a corrupt status/length (output may then hold a truncated prefix).
A fixed header records provenance and two constant caveats: device_state_bench=unverified and device_state_frame_atomic=0. For a requested snapshot, each field adds three lines: status name, reply hex ("unknown" unless OK) and "transport_error,device_status" so failures stay diagnosable.
- Note
- Returning 0 rather than truncating lets the caller refuse incomplete evidence.
Definition at line 430 of file lwir_state.c.
◆ lwir_state_read()
| void lwir_state_read | ( | const struct lwir_state_io * | io, |
| struct lwir_device_state * | state ) |
Read all fields of struct lwir_device_state within LWIR_STATE_BUDGET_MS.
Take a best-effort, read-only snapshot of all device-state fields.
Algorithm:
- Zero the state, mark it requested and every field skipped.
- Refuse to start unless the mailbox status is idle (0), so a command still running from an earlier aborted snapshot is not clobbered.
- For each field in table order: write the command header (standard at 0x1d00, or extended as held half at 0x9d00 plus trigger half at 0x1d08), poll 0x0200 up to 32 times at <= 10 ms intervals until idle, read the reply at 0x1d00 + header length and validate it. Unsupported/invalid fields continue with the next field because the device is still responsive; timeout, I/O error and cancellation stop the snapshot since further transfers would only burn budget or hit a busy mailbox.
- Note
- Failures are reported only through
state; field 0 carries LWIR_STATE_INVALID for an unusableioor LWIR_STATE_BUSY for a busy mailbox.
Definition at line 159 of file lwir_state.c.
◆ lwir_state_u16()
| bool lwir_state_u16 | ( | const struct lwir_device_state * | state, |
| enum lwir_state_field | field, | ||
| uint16_t * | value ) |
Decode a validated big-endian two-byte snapshot field.
Decode a validated two-byte big-endian field.
- Returns
- False for NULL arguments, invalid index, non-OK status or a string field.
Definition at line 412 of file lwir_state.c.
◆ remaining_ms()
|
static |
Time left before deadline, as a per-transfer timeout.
- Parameters
-
io Clock provider. deadline Absolute deadline in now_us() microseconds.
- Returns
- Whole milliseconds remaining, capped at 50; 0 when less than 1 ms remains.
- Note
- The 50 ms cap keeps one slow transfer from consuming the whole budget.
Definition at line 81 of file lwir_state.c.
◆ transfer()
|
static |
Perform one deadline-bounded mailbox transfer and classify failure.
- Parameters
-
io Transport. deadline Absolute deadline in now_us() microseconds. input True to read from the device, false to write. address Mailbox register address. data Source or destination buffer of at least lengthbytes.length Exact number of bytes expected. value Receives status (and transport_error) on failure; untouched on success.
- Returns
- True only for a complete transfer that also finished before the deadline.
- Warning
- A complete transfer that ends after the deadline is reported as LWIR_STATE_TIMEOUT even though a write may have executed.
Definition at line 102 of file lwir_state.c.
◆ valid_value()
|
static |
Plausibility check of one snapshot reply.
- Parameters
-
field Field the reply belongs to. data Reply bytes, at least the field's query length.
- Returns
- True if acceptable as evidence.
64-byte strings must be neither all zero (no data) nor all 0xff (erased/unprogrammed); shutter bytes must each be 0 or 1; other fields are big-endian and must fall inside the vendor range.
Definition at line 127 of file lwir_state.c.
Variable Documentation
◆ queries
|
static |
Getter table indexed by enum lwir_state_field; names become evidence keys.
Ranges come from the vendor headers. Order is read order, so the most important evidence (gain, firmware identity) is fetched while budget remains.
Definition at line 51 of file lwir_state.c.