Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
lwir_state.c
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file lwir_state.c
20 * @brief Tiny1-C vendor mailbox protocol: snapshot reads, controls and evidence text.
21 * @details Transport-agnostic implementation of the protocol summarised in
22 * lwir_state.h. Every operation is driven by an absolute deadline: each transfer
23 * timeout is the remaining budget capped at 50 ms, and every poll loop is bounded
24 * both by an iteration cap and by that deadline, so a stuck device cannot stall
25 * the capture path. Storage is caller-owned or on the stack; no heap, no memcpy.
26 */
27#include "lwir_state.h"
28
29#include <stdio.h>
30
31/**
32 * @brief One mailbox getter, shared by snapshot reads and control read-back.
33 * @details @c command 0x14 selects the extended 16-byte header; others use the
34 * 8-byte standard header. @c parameter selects the item within the command,
35 * @c length is the reply size requested in the last header byte, and
36 * @c minimum/@c maximum bound two-byte replies (unused for strings/shutter).
37 */
39 const char *name;
40 uint8_t command;
41 uint8_t subcommand;
42 uint8_t parameter;
43 uint8_t length;
44 uint16_t minimum;
45 uint16_t maximum;
46};
47
48/** @brief Getter table indexed by enum lwir_state_field; names become evidence keys.
49 * @details Ranges come from the vendor headers. Order is read order, so the most
50 * important evidence (gain, firmware identity) is fetched while budget remains. */
51static const struct state_query queries[LWIR_STATE_FIELDS] = {
52 {"gain_select", 0x14, 0x85, 5, 2, 0, 1},
53 {"fw_build", 0x05, 0x84, 5, 64, 0, 0},
54 {"fw_date", 0x05, 0x84, 1, 64, 0, 0},
55 {"chip", 0x05, 0x84, 0, 64, 0, 0},
56 {"shutter", 0x0c, 0x83, 0, 2, 0, 0},
57 {"distance_128_per_m", 0x14, 0x85, 0, 2, 0, 32767},
58 {"reflected_k", 0x14, 0x85, 1, 2, 230, 900},
59 {"ambient_k", 0x14, 0x85, 2, 2, 230, 900},
60 {"emissivity_128", 0x14, 0x85, 3, 2, 1, 128},
61 {"transmittance_128", 0x14, 0x85, 4, 2, 1, 128},
62 {"tnr", 0x14, 0x83, 0, 2, 0, 3},
63 {"snr", 0x14, 0x83, 1, 2, 0, 3},
64 {"dde", 0x14, 0x83, 2, 2, 0, 6},
65 {"brightness", 0x14, 0x83, 3, 2, 0, 255},
66 {"contrast", 0x14, 0x83, 4, 2, 0, 255},
67 {"agc_mode", 0x14, 0x83, 5, 2, 0, 5},
68 {"agc_max_gain", 0x14, 0x83, 6, 2, 0, 255},
69 {"agc_bos", 0x14, 0x83, 7, 2, 0, 255},
70 {"agc_enable", 0x14, 0x83, 8, 2, 0, 1},
71 {"mirror_flip", 0x14, 0x83, 9, 2, 0, 3}
72};
73
74/**
75 * @brief Time left before @p deadline, as a per-transfer timeout.
76 * @param io Clock provider.
77 * @param deadline Absolute deadline in now_us() microseconds.
78 * @return Whole milliseconds remaining, capped at 50; 0 when less than 1 ms remains.
79 * @note The 50 ms cap keeps one slow transfer from consuming the whole budget.
80 */
81static unsigned remaining_ms(const struct lwir_state_io *io, uint64_t deadline)
82{
83 const uint64_t now = io->now_us(io->context);
84 if (now >= deadline) return 0;
85 const uint64_t remaining = (deadline - now) / 1000U;
86 return (unsigned)(remaining > 50U ? 50U : remaining);
87}
88
89/**
90 * @brief Perform one deadline-bounded mailbox transfer and classify failure.
91 * @param io Transport.
92 * @param deadline Absolute deadline in now_us() microseconds.
93 * @param input True to read from the device, false to write.
94 * @param address Mailbox register address.
95 * @param data Source or destination buffer of at least @p length bytes.
96 * @param length Exact number of bytes expected.
97 * @param value Receives status (and transport_error) on failure; untouched on success.
98 * @return True only for a complete transfer that also finished before the deadline.
99 * @warning A complete transfer that ends after the deadline is reported as
100 * #LWIR_STATE_TIMEOUT even though a write may have executed.
101 */
102static bool transfer(const struct lwir_state_io *io, uint64_t deadline, bool input,
103 uint16_t address, uint8_t *data, unsigned length, struct lwir_state_value *value)
104{
105 const unsigned timeout = remaining_ms(io, deadline);
106 if (!timeout) { value->status = LWIR_STATE_TIMEOUT; return false; }
107 const int result = io->transfer(io->context, input, address, data, length, timeout);
108 if (result != (int)length) {
109 value->transport_error = result;
111 return false;
112 }
113 /* Re-check after the call: a transfer may block up to its timeout, and the budget must stay hard. */
114 if (!remaining_ms(io, deadline)) { value->status = LWIR_STATE_TIMEOUT; return false; }
115 return true;
116}
117
118/**
119 * @brief Plausibility check of one snapshot reply.
120 * @param field Field the reply belongs to.
121 * @param data Reply bytes, at least the field's query length.
122 * @return True if acceptable as evidence.
123 * @details 64-byte strings must be neither all zero (no data) nor all 0xff
124 * (erased/unprogrammed); shutter bytes must each be 0 or 1; other fields are
125 * big-endian and must fall inside the vendor range.
126 */
127static bool valid_value(enum lwir_state_field field, const uint8_t *data)
128{
129 const struct state_query *query = &queries[field];
130 if (query->length == 64) {
131 bool nonempty = false, nonerased = false;
132 for (unsigned index = 0; index < 64; ++index) {
133 nonempty |= data[index] != 0;
134 nonerased |= data[index] != 255;
135 }
136 return nonempty && nonerased;
137 }
138 if (field == LWIR_STATE_SHUTTER) return data[0] <= 1 && data[1] <= 1;
139 const uint16_t number = (uint16_t)((unsigned)data[0] * 256U + data[1]);
140 return number >= query->minimum && number <= query->maximum;
141}
142
143/**
144 * @brief Read all fields of struct lwir_device_state within #LWIR_STATE_BUDGET_MS.
145 * @details Algorithm:
146 * 1. Zero the state, mark it requested and every field skipped.
147 * 2. Refuse to start unless the mailbox status is idle (0), so a command still
148 * running from an earlier aborted snapshot is not clobbered.
149 * 3. For each field in table order: write the command header (standard at
150 * 0x1d00, or extended as held half at 0x9d00 plus trigger half at 0x1d08),
151 * poll 0x0200 up to 32 times at <= 10 ms intervals until idle, read the reply
152 * at 0x1d00 + header length and validate it.
153 * Unsupported/invalid fields continue with the next field because the device is
154 * still responsive; timeout, I/O error and cancellation stop the snapshot since
155 * further transfers would only burn budget or hit a busy mailbox.
156 * @note Failures are reported only through @p state; field 0 carries
157 * #LWIR_STATE_INVALID for an unusable @p io or #LWIR_STATE_BUSY for a busy mailbox.
158 */
159void lwir_state_read(const struct lwir_state_io *io, struct lwir_device_state *state)
160{
161 if (!state) return;
162 unsigned char *storage = (unsigned char *)state;
163 /* Byte loop instead of memset/memcpy per project policy; also clears padding so evidence is deterministic. */
164 for (size_t index = 0; index < sizeof(*state); ++index) storage[index] = 0;
165 state->requested = true;
166 for (unsigned field = 0; field < LWIR_STATE_FIELDS; ++field) state->values[field].status = LWIR_STATE_SKIPPED;
167 if (!io || !io->transfer || !io->now_us || !io->pause) { state->values[0].status = LWIR_STATE_INVALID; return; }
168 state->started_us = io->now_us(io->context);
169 if (state->started_us > UINT64_MAX - LWIR_STATE_BUDGET_MS * 1000U) { state->values[0].status = LWIR_STATE_INVALID; return; }
170 const uint64_t deadline = state->started_us + LWIR_STATE_BUDGET_MS * 1000U;
171 uint8_t status = 0;
172 struct lwir_state_value *first = &state->values[0];
173 /* Step 1: only start from an idle mailbox; never queue behind someone else's command. */
174 if (!transfer(io, deadline, true, 0x0200, &status, 1, first)) goto finished;
175 if (status != 0) { first->status = LWIR_STATE_BUSY; first->device_status = status; goto finished; }
176 for (unsigned field = 0; field < LWIR_STATE_FIELDS; ++field) {
177 const struct state_query *query = &queries[field];
178 struct lwir_state_value *value = &state->values[field];
179 uint8_t header[16] = {0}, reply[64] = {0};
180 const bool extended = query->command == 0x14;
181 const unsigned header_length = extended ? 16U : 8U;
182 /* Step 2: the item selector sits at byte 2 (standard) or 3 (extended); the last byte requests the reply length. */
183 header[0] = query->command; header[1] = query->subcommand;
184 header[extended ? 3 : 2] = query->parameter;
185 header[header_length - 1] = query->length;
186 if (extended) {
187 /* 0x9d00 only holds the first half; the write to 0x1d08 starts execution, so order is mandatory. */
188 if (!transfer(io, deadline, false, 0x9d00, header, 8, value) ||
189 !transfer(io, deadline, false, 0x1d08, header + 8, 8, value)) break;
190 } else if (!transfer(io, deadline, false, 0x1d00, header, 8, value)) break;
191 bool complete = false;
192 /* Step 3: poll for completion; 32 x 10 ms pauses alone exceed the budget, so the deadline usually ends a hung poll. */
193 for (unsigned attempt = 0; attempt < 32; ++attempt) {
194 if (!transfer(io, deadline, true, 0x0200, &status, 1, value)) break;
195 value->device_status = status;
196 if (status == 0) { complete = true; break; }
197 /* Non-zero but not busy (e.g. 0x02 alone) is unexpected and treated as an I/O error. */
198 if ((status & 0xfcU) || !(status & 1U)) {
199 const unsigned error = status & 0xfcU;
200 value->status = error == 0x08 || error == 0x10 ? LWIR_STATE_UNSUPPORTED :
202 break;
203 }
204 unsigned delay = remaining_ms(io, deadline);
205 if (!delay) { value->status = LWIR_STATE_TIMEOUT; break; }
206 if (delay > 10) delay = 10;
207 if (!io->pause(io->context, delay)) { value->status = LWIR_STATE_CANCELLED; break; }
208 }
209 if (!complete) {
210 /* The device rejected this item but answered cleanly, so the mailbox is usable for the next one. */
211 if (value->status == LWIR_STATE_UNSUPPORTED || value->status == LWIR_STATE_INVALID) continue;
212 /* Still SKIPPED means all 32 polls saw busy. */
213 if (value->status == LWIR_STATE_SKIPPED) value->status = LWIR_STATE_TIMEOUT;
214 break;
215 }
216 /* Step 4: the reply follows the header, so its address depends on the header form. */
217 if (!transfer(io, deadline, true, (uint16_t)(0x1d00U + header_length), reply, query->length, value)) break;
218 if (!valid_value((enum lwir_state_field)field, reply)) { value->status = LWIR_STATE_INVALID; continue; }
219 value->status = LWIR_STATE_OK;
220 value->length = query->length;
221 for (unsigned index = 0; index < query->length; ++index) value->data[index] = reply[index];
222 }
223finished:
224 state->finished_us = io->now_us(io->context);
225}
226
227/**
228 * @brief Range-check a control request (vendor-header limits).
229 * @return True for a known kind with an in-range value; FFC accepts only 0.
230 */
232{
233 if (!request) return false;
234 switch (request->kind) {
235 case LWIR_CONTROL_GAIN: case LWIR_CONTROL_AGC_ENABLE: return request->value <= 1;
236 case LWIR_CONTROL_EMISSIVITY: return request->value >= 1 && request->value <= 128;
237 case LWIR_CONTROL_AGC_MODE: return request->value <= 5;
238 case LWIR_CONTROL_FFC: return request->value == 0;
239 default: return false;
240 }
241}
242
243/**
244 * @brief Poll the mailbox status until idle, an error class, or the deadline.
245 * @param io Transport.
246 * @param deadline Absolute deadline in now_us() microseconds.
247 * @param reply Receives device_status and the failure status.
248 * @return True once status reads 0. False with #LWIR_STATE_UNSUPPORTED,
249 * #LWIR_STATE_INVALID or #LWIR_STATE_IO_ERROR for an error class,
250 * #LWIR_STATE_CANCELLED, or #LWIR_STATE_TIMEOUT when the deadline or the
251 * 512-poll cap is reached; transfer failures keep transfer()'s status.
252 * @details Pauses at most 10 ms between polls. The larger cap than the snapshot's
253 * 32 polls fits the 1-5 s control budgets.
254 */
255static bool control_idle(const struct lwir_state_io *io, uint64_t deadline, struct lwir_state_value *reply)
256{
257 for (unsigned attempt = 0; attempt < 512; ++attempt) {
258 uint8_t status = 0;
259 if (!transfer(io, deadline, true, 0x0200, &status, 1, reply)) return false;
260 reply->device_status = status;
261 if (!status) return true;
262 if ((status & 0xfcU) || !(status & 1U)) {
263 const unsigned error = status & 0xfcU;
264 reply->status = error == 0x08 || error == 0x10 ? LWIR_STATE_UNSUPPORTED :
266 return false;
267 }
268 unsigned delay = remaining_ms(io, deadline);
269 if (!delay) break;
270 if (delay > 10) delay = 10;
271 if (!io->pause(io->context, delay)) { reply->status = LWIR_STATE_CANCELLED; return false; }
272 }
273 reply->status = LWIR_STATE_TIMEOUT;
274 return false;
275}
276
277/**
278 * @brief Map a control to the getter row whose subcommand/parameter it writes.
279 * @param kind Control kind.
280 * @return Table row, or NULL for FFC/unknown kinds (no readable value).
281 * @note Reusing the snapshot table keeps getter, setter and range limits in one place.
282 */
283static const struct state_query *control_query(enum lwir_control_kind kind)
284{
285 switch (kind) {
290 default: return NULL;
291 }
292}
293
294/**
295 * @brief Read one extended two-byte setting back from the device.
296 * @param io Transport.
297 * @param deadline Absolute deadline in now_us() microseconds.
298 * @param query Getter row (extended command 0x14).
299 * @param result Receives reply bytes, length 2 and the decoded readback.
300 * @return True for an in-range value. False with the failing step's status, or
301 * #LWIR_STATE_INVALID when the value is outside the vendor range (readback is
302 * still stored for diagnostics).
303 * @details Writes the held half (0x9d00), triggers with the second half (0x1d08,
304 * byte 15 = reply length 2), waits idle, then reads the big-endian reply at 0x1d10.
305 * @pre The mailbox is idle.
306 */
307static bool control_readback(const struct lwir_state_io *io, uint64_t deadline, const struct state_query *query,
309{
310 uint8_t command[16] = {0x14, query->subcommand, 0, query->parameter, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2};
311 struct lwir_state_value *reply = &result->reply;
312 if (!transfer(io, deadline, false, 0x9d00, command, 8, reply)
313 || !transfer(io, deadline, false, 0x1d08, command + 8, 8, reply)
314 || !control_idle(io, deadline, reply)
315 || !transfer(io, deadline, true, 0x1d10, reply->data, 2, reply)) return false;
316 reply->length = 2;
317 result->readback = (uint16_t)((unsigned)reply->data[0] * 256U + reply->data[1]);
318 if (result->readback < query->minimum || result->readback > query->maximum) {
319 reply->status = LWIR_STATE_INVALID; return false;
320 }
321 return true;
322}
323
324/**
325 * @brief Targeted read of one controllable setting; performs no setting writes.
326 * @return True with verified and readback set; false on bad arguments or any
327 * failed step (see result->reply).
328 * @details Budget 1 s: wait idle, then control_readback(). Only the getter header
329 * is written, so submitted stays false.
330 */
333{
334 if (!result) return false;
335 *result = (struct lwir_control_result){.reply = {.status = LWIR_STATE_INVALID}};
336 const struct state_query *query = control_query(kind);
337 if (!query || !io || !io->transfer || !io->now_us || !io->pause) return false;
338 const uint64_t start = io->now_us(io->context);
339 if (start > UINT64_MAX - 1000000U) return false;
340 const uint64_t deadline = start + 1000000U;
341 if (!control_idle(io, deadline, &result->reply) || !control_readback(io, deadline, query, result)) return false;
342 result->verified = true;
343 result->reply.status = LWIR_STATE_OK;
344 return true;
345}
346
347/**
348 * @brief Apply one setting with read-back verification, or trigger FFC.
349 * @return True when the setter was verified or FFC was acknowledged. False on
350 * invalid input, budget overflow or any failed step; result->submitted tells
351 * whether the device may already have acted.
352 * @details
353 * - Budget: 1 s; gain and FFC 5 s (gain may involve internal correction).
354 * - Always wait for an idle mailbox first so a pending command is not overwritten.
355 * - FFC: standard command 0d c1 02 (OOC+B combined update, not shutter
356 * open/close) at 0x1d00, then a fixed 3 s wait (300 x 10 ms) mirroring the
357 * vendor's special 3000 ms poll delay, then an idle check. Result is an
358 * acknowledgement only; verified stays false.
359 * - Setters: SET subcommand = getter + 0x40 (0x83->0xc3 image, 0x85->0xc5 TPD),
360 * value big-endian in header bytes 6..7 (verified against vendor reference
361 * source). Held half to 0x9d00, trigger half to 0x1d08, wait idle, read back,
362 * and mark verified only on an exact match.
363 * @warning After a false return with submitted set, never replay the command;
364 * read the setting back to learn the device state.
365 */
368{
369 if (!result) return false;
370 *result = (struct lwir_control_result){.reply = {.status = LWIR_STATE_INVALID}};
371 if (!lwir_control_valid(request) || !io || !io->transfer || !io->now_us || !io->pause) return false;
372 const uint64_t start = io->now_us(io->context);
373 const uint64_t budget = request->kind == LWIR_CONTROL_FFC || request->kind == LWIR_CONTROL_GAIN ? 5000000U : 1000000U;
374 if (start > UINT64_MAX - budget) return false;
375 const uint64_t deadline = start + budget;
376 struct lwir_state_value *reply = &result->reply;
377 if (!control_idle(io, deadline, reply)) return false;
378 if (request->kind == LWIR_CONTROL_FFC) {
379 uint8_t command[8] = {0x0d, 0xc1, 2, 0, 0, 0, 0, 0};
380 /* Set before the write: a failed or short single-transfer trigger may still have executed. */
381 result->submitted = true;
382 if (!transfer(io, deadline, false, 0x1d00, command, sizeof(command), reply)) return false;
383 /* Fixed wait, not polling: mirrors the vendor's special 3000 ms poll delay for this command. */
384 for (unsigned pause = 0; pause < 300; ++pause) {
385 if (!remaining_ms(io, deadline)) { reply->status = LWIR_STATE_TIMEOUT; return false; }
386 if (!io->pause(io->context, 10)) { reply->status = LWIR_STATE_CANCELLED; return false; }
387 }
388 if (!control_idle(io, deadline, reply)) return false;
389 } else {
390 const struct state_query *query = control_query(request->kind);
391 /* Byte 15 (reply length) stays 0: a setter returns no payload. */
392 uint8_t command[16] = {0x14, (uint8_t)(query->subcommand + 0x40U), 0, query->parameter,
393 0, 0, (uint8_t)(request->value >> 8), (uint8_t)request->value};
394 /* The held half does not execute, so a failure here leaves submitted false. */
395 if (!transfer(io, deadline, false, 0x9d00, command, 8, reply)) return false;
396 /* From here the trigger may have executed even if the transfer reports failure. */
397 result->submitted = true;
398 if (!transfer(io, deadline, false, 0x1d08, command + 8, 8, reply)
399 || !control_idle(io, deadline, reply)) return false;
400 if (!control_readback(io, deadline, query, result)) return false;
401 if (result->readback != request->value) { reply->status = LWIR_STATE_INVALID; return false; }
402 result->verified = true;
403 }
404 reply->status = LWIR_STATE_OK;
405 return true;
406}
407
408/**
409 * @brief Decode a validated big-endian two-byte snapshot field.
410 * @return False for NULL arguments, invalid index, non-OK status or a string field.
411 */
412bool lwir_state_u16(const struct lwir_device_state *state, enum lwir_state_field field, uint16_t *value)
413{
414 if (!state || !value || (unsigned)field >= LWIR_STATE_FIELDS ||
415 state->values[field].status != LWIR_STATE_OK || state->values[field].length != 2) return false;
416 *value = (uint16_t)((unsigned)state->values[field].data[0] * 256U + state->values[field].data[1]);
417 return true;
418}
419
420/**
421 * @brief Render snapshot evidence as key=value lines for the JPEG APP14 segment.
422 * @return Bytes written excluding the NUL; 0 on NULL/zero-sized output, overflow,
423 * or a corrupt status/length (output may then hold a truncated prefix).
424 * @details A fixed header records provenance and two constant caveats:
425 * device_state_bench=unverified and device_state_frame_atomic=0. For a requested
426 * snapshot, each field adds three lines: status name, reply hex ("unknown"
427 * unless OK) and "transport_error,device_status" so failures stay diagnosable.
428 * @note Returning 0 rather than truncating lets the caller refuse incomplete evidence.
429 */
430size_t lwir_state_format(const struct lwir_device_state *state, char *output, size_t capacity)
431{
432 /* Indexed by enum lwir_state_status; keep both in the same order. */
433 static const char *const statuses[] = {"not_requested", "ok", "unsupported", "timeout", "io_error", "invalid", "busy", "skipped", "cancelled"};
434 if (!output || !capacity) return 0;
435 const int prefix = snprintf(output, capacity, "device_state=%s\ndevice_state_source=%s\ndevice_state_bench=unverified\n"
436 "device_state_frame_atomic=0\ndevice_state_started_us=%llu\ndevice_state_finished_us=%llu\n",
437 state && state->requested ? "requested" : "not_requested", state && state->requested ? "tiny1c_usb_i2c" : "none",
438 (unsigned long long)(state ? state->started_us : 0),
439 (unsigned long long)(state ? state->finished_us : 0));
440 if (prefix < 0 || (size_t)prefix >= capacity) return 0;
441 size_t used = (size_t)prefix;
442 if (!state || !state->requested) return used;
443 for (unsigned field = 0; field < LWIR_STATE_FIELDS; ++field) {
444 const struct lwir_state_value *value = &state->values[field];
445 char hex[129];
446 /* Guards both the table lookup and hex[] against a corrupted caller-supplied snapshot. */
447 if ((unsigned)value->status >= sizeof(statuses) / sizeof(statuses[0]) || value->length > 64) return 0;
448 for (unsigned index = 0; index < value->length; ++index) {
449 hex[index * 2] = "0123456789abcdef"[value->data[index] >> 4];
450 hex[index * 2 + 1] = "0123456789abcdef"[value->data[index] & 15];
451 }
452 hex[value->length * 2] = '\0';
453 const int added = snprintf(output + used, capacity - used, "device_%s_status=%s\ndevice_%s_hex=%s\n"
454 "device_%s_result=%d,%u\n", queries[field].name, statuses[value->status], queries[field].name,
455 value->status == LWIR_STATE_OK ? hex : "unknown", queries[field].name, value->transport_error, value->device_status);
456 if (added < 0 || (size_t)added >= capacity - used) return 0;
457 used += (size_t)added;
458 }
459 return used;
460}
static unsigned capacity[COVERAGE_CAMERAS]
static bool start(uint32_t session)
Admit a nonzero session and discard correlation from the previous one.
union dc_shot_union request
struct jpeg_error_mgr error
Definition lwir_image.c:60
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.
Definition lwir_state.c:412
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.
Definition lwir_state.c:255
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.
Definition lwir_state.c:159
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.
Definition lwir_state.c:331
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.
Definition lwir_state.c:366
static unsigned remaining_ms(const struct lwir_state_io *io, uint64_t deadline)
Time left before deadline, as a per-transfer timeout.
Definition lwir_state.c:81
static bool valid_value(enum lwir_state_field field, const uint8_t *data)
Plausibility check of one snapshot reply.
Definition lwir_state.c:127
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.
Definition lwir_state.c:430
bool lwir_control_valid(const struct lwir_control_request *request)
Range-check a control request (vendor-header limits).
Definition lwir_state.c:231
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.
Definition lwir_state.c:307
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.
Definition lwir_state.c:102
static const struct state_query * control_query(enum lwir_control_kind kind)
Map a control to the getter row whose subcommand/parameter it writes.
Definition lwir_state.c:283
static const struct state_query queries[LWIR_STATE_FIELDS]
Getter table indexed by enum lwir_state_field; names become evidence keys.
Definition lwir_state.c:51
Tiny1-C vendor mailbox: bounded device-state snapshots and verified setting controls.
lwir_state_field
Index of each queried device-state field; also the read order.
Definition lwir_state.h:87
@ LWIR_STATE_AGC_ENABLE
Definition lwir_state.h:93
@ LWIR_STATE_AGC_MODE
Definition lwir_state.h:92
@ LWIR_STATE_GAIN
Definition lwir_state.h:88
@ LWIR_STATE_EMISSIVITY
Definition lwir_state.h:90
@ LWIR_STATE_SHUTTER
Definition lwir_state.h:89
@ LWIR_STATE_FIELDS
Definition lwir_state.h:94
#define LWIR_STATE_BUDGET_MS
Wall-time budget for one whole lwir_state_read() snapshot, in milliseconds.
Definition lwir_state.h:58
lwir_control_kind
Settings that lwir_state_control() may change.
Definition lwir_state.h:175
@ LWIR_CONTROL_GAIN
Definition lwir_state.h:176
@ LWIR_CONTROL_FFC
Definition lwir_state.h:177
@ LWIR_CONTROL_AGC_MODE
Definition lwir_state.h:176
@ LWIR_CONTROL_EMISSIVITY
Definition lwir_state.h:176
@ LWIR_CONTROL_AGC_ENABLE
Definition lwir_state.h:177
@ LWIR_STATE_INVALID
Definition lwir_state.h:117
@ LWIR_STATE_OK
Definition lwir_state.h:116
@ LWIR_STATE_UNSUPPORTED
Definition lwir_state.h:116
@ LWIR_STATE_TIMEOUT
Definition lwir_state.h:117
@ LWIR_STATE_BUSY
Definition lwir_state.h:118
@ LWIR_STATE_SKIPPED
Definition lwir_state.h:118
@ LWIR_STATE_CANCELLED
Definition lwir_state.h:118
@ LWIR_STATE_IO_ERROR
Definition lwir_state.h:117
static const char header[]
Definition pose_log.c:87
static FILE * output
Definition pose_log.c:77
One requested setting change; validate with lwir_control_valid().
Definition lwir_state.h:181
Outcome of lwir_state_control() or lwir_state_control_read().
Definition lwir_state.h:195
One post-capture snapshot of all lwir_state_field values.
Definition lwir_state.h:135
bool requested
True once lwir_state_read() ran; false means no device state exists.
Definition lwir_state.h:139
uint64_t started_us
now_us() before the first transfer; clock domain is the io provider's.
Definition lwir_state.h:137
struct lwir_state_value values[LWIR_STATE_FIELDS]
Indexed by enum lwir_state_field.
Definition lwir_state.h:136
uint64_t finished_us
now_us() after the last attempt; 0 if the io table was unusable.
Definition lwir_state.h:138
Transport and clock callbacks driving the mailbox protocol.
Definition lwir_state.h:147
int(* transfer)(void *context, bool input, uint16_t address, uint8_t *data, unsigned length, unsigned timeout_ms)
Move length bytes between data and mailbox address.
Definition lwir_state.h:157
void * context
Opaque provider state (USBFS session, test fake).
Definition lwir_state.h:148
bool(* pause)(void *context, unsigned milliseconds)
Sleep about milliseconds; return false to cancel the whole operation.
Definition lwir_state.h:162
uint64_t(* now_us)(void *context)
Current time in microseconds; must be monotonic for budgets to hold.
Definition lwir_state.h:160
Raw result of one mailbox query, kept verbatim as evidence.
Definition lwir_state.h:122
enum lwir_state_status status
Outcome; data is meaningful only for LWIR_STATE_OK.
Definition lwir_state.h:123
uint8_t data[64]
Definition lwir_state.h:126
uint8_t length
Valid bytes in data (2 or 64); 0 unless a reply was accepted.
Definition lwir_state.h:127
uint8_t device_status
Last status byte read from 0x0200; 0 if none was read.
Definition lwir_state.h:128
One mailbox getter, shared by snapshot reads and control read-back.
Definition lwir_state.c:38
uint8_t command
Definition lwir_state.c:40
uint8_t parameter
Definition lwir_state.c:42
uint8_t subcommand
Definition lwir_state.c:41
uint8_t length
Definition lwir_state.c:43
uint16_t maximum
Definition lwir_state.c:45
uint16_t minimum
Definition lwir_state.c:44
const char * name
Definition lwir_state.c:39
struct usher_control_result result
Definition usher.c:377