Tiny1C/TDK acquisition and Tiny1C state, without image or mission logic. More...


Go to the source code of this file.
Data Structures | |
| struct | lwir_video_buffer |
| One kernel capture buffer mapped into this process. More... | |
| struct | lwir_device_options |
| Bounded camera policy; Tiny1C requires full 256x192 image and temperature planes. More... | |
| struct | lwir_device |
| Caller-owned session, initialized to zero before opening. More... | |
| struct | lwir_device_observation |
| Host observation plus optional kernel clock evidence, never automatic exposure qualification. More... | |
Macros | |
| #define | LWIR_VIDEO_BUFFERS 4U |
| Number of V4L2 MMAP buffers requested from uvcvideo. | |
Functions | |
| bool | lwir_device_open (struct lwir_device_options *options, struct lwir_device *device) |
| Open/start a bounded camera-specific combined or image-only YUY2 stream. | |
| bool | lwir_device_acquire (struct lwir_device *device, const struct lwir_device_options *options, uint8_t *destination, size_t capacity, struct lwir_device_observation *observation) |
| Copy a qualified, fresh camera-layout frame into caller-owned storage. | |
| bool | lwir_device_discard (struct lwir_device *device, bool *received) |
| Drain one pending frame without retaining the borrowed UVC buffer. | |
| void | lwir_device_read_state (struct lwir_device *device, struct lwir_device_state *state) |
| Read bounded optional state after acquisition, never writing device settings. | |
| bool | lwir_device_control (struct lwir_device *device, const struct lwir_control_request *request, struct lwir_control_result *result) |
| Submit one Tiny1-C vendor control write (or FFC action) as a standalone operation. | |
| bool | lwir_device_control_read (struct lwir_device *device, enum lwir_control_kind kind, struct lwir_control_result *result) |
| Read the current value of one Tiny1-C control without writing it. | |
| void | lwir_device_close (struct lwir_device *device) |
| Close an initialized session; safe repeatedly and preserves errno. | |
Detailed Description
Tiny1C/TDK acquisition and Tiny1C state, without image or mission logic.
This interface is the only boundary between LWIRcam and the camera hardware. It delivers raw camera-layout frames plus timing evidence; image conversion, calibration, geolocation and mission policy live elsewhere.
- Supported cameras
- Tiny1-C (USB 0bda:5840): combined YUYV transport of 256x384 pixels, i.e. a 256x192 image plane followed by a 256x192 temperature plane holding Kelvin*64 little-endian values; 196608 bytes per frame at about 25 fps. Its separate 256x192 image-only UVC mode is not combined data and is not used.
- TDK (USB 5474:5411): 640x512 image-only YUYV; no temperature plane.
- Backend
- Capture runs in lwir_device_v4l2.c directly on the Linux uvcvideo kernel driver with V4L2 MMAP buffers and usbfs control requests for Tiny1-C state.
- Ownership model
- Every object is caller-owned storage; the backend performs no heap allocation. A session owns one V4L2 descriptor (held under an exclusive flock) and up to LWIR_VIDEO_BUFFERS kernel buffers mapped into the process. Mapped buffers are only borrowed between dequeue and requeue; callers never see their addresses and receive copies instead.
- Threading
- A session is not thread-safe: one thread must own all calls on it. The only cross-context input is the borrowed sig_atomic_t cancellation flag, which may be set from a signal handler or another thread and is polled at least every 25 ms while waiting.
- Lifecycle invariants
- Zero-initialize, lwir_device_open(), acquire/discard/state calls, then lwir_device_close(). Close before reopening.
- A fatal kernel or protocol error poisons the session (EIO) until it is closed and reopened; no partial recovery is attempted.
- The eight-frame startup qualification runs once per USB power instance, remembered across reopen and process restart, and is never repeated for later requests, gaps, invalid frames or reconnection of the same instance.
Definition in file lwir_device.h.
Macro Definition Documentation
◆ LWIR_VIDEO_BUFFERS
| #define LWIR_VIDEO_BUFFERS 4U |
Number of V4L2 MMAP buffers requested from uvcvideo.
Four keeps one buffer in user space for inspection while the kernel still has spare buffers to fill, so a short inspection does not drop the next frame. The driver may grant fewer; at least two are required.
Definition at line 70 of file lwir_device.h.
Function Documentation
◆ lwir_device_acquire()
| bool lwir_device_acquire | ( | struct lwir_device * | device, |
| const struct lwir_device_options * | options, | ||
| uint8_t * | destination, | ||
| size_t | capacity, | ||
| struct lwir_device_observation * | observation ) |
Copy a qualified, fresh camera-layout frame into caller-owned storage.
- Parameters
-
device Open session with an optional borrowed cancellation flag. options Native geometry, warmup and qualification policy. destination Writable frame buffer, retained through the call. capacity Accessible bytes; at least lwir_frame_bytes(width, height). observation Sequence and host arrival, written only on success.
- Returns
- True on acceptance; ignore destination on failure and never auto-retry publication.
Native image/observation buffers must not alias each other, the session or mapped camera buffers. Fatal kernel ownership failures require close/reopen. Startup qualification is retained for the USB instance across reopen/restart; no subsequent request, gap or invalid frame imposes another eight-frame wait. Freshness: when the kernel timestamp is CLOCK_MONOTONIC, the accepted frame started at or after this call began, so it never predates the trigger.
- Errors
- EINVAL bad arguments or aliasing; EIO poisoned session; ETIMEDOUT deadline; EINTR cancellation; EPROTO/EOVERFLOW inconsistent kernel data or clock.
Copy a qualified, fresh camera-layout frame into caller-owned storage.
Loop structure, each iteration bounded by a 25 ms poll() slice so that cancellation and the deadline are noticed promptly:
- poll() for a filled buffer; POLLERR/POLLHUP/POLLNVAL (for example an unplugged camera) poison the session.
- Dequeue one buffer and read the host clock immediately.
- Grade the frame in increasing strictness:
usable:structurally valid, recent, correct sequence; feeds the startup qualification counter even when it predates the request.valid:additionally started at or after the request (freshness).scene_valid:additionally passes the optional scene check.
- For non-MONOTONIC clocks freshness is unknowable, so the first good frame triggers a one-time drain of all already-queued buffers; the next frame is then certainly produced after the request.
- Accept when the instance is qualified (eight good frames), optional settling holds, and on first startup only,
warmup_mshas elapsed. - Copy what is needed and snapshot sequence/timestamp/flags, then requeue. The order matters: after QBUF the kernel may overwrite both pixels and metadata.
- Persist the startup marker once qualification and warmup are complete.
Settling uses destination as the previous-image store: the image plane of each scene-valid frame is copied there and the next frame is compared against it, so no extra buffer is needed. The temperature plane is copied only for the accepted frame.
- Returns
- True with a fresh frame in
destination.
- Errors
- EINVAL arguments/aliasing; EIO poisoned session or poll error; ETIMEDOUT deadline, including completion that would land after it; EINTR cancelled; kernel errno from failed ioctls (session then poisoned).
- Warning
- On failure
destinationmay contain partial or settling data and must be ignored.
Definition at line 963 of file lwir_device_v4l2.c.
◆ lwir_device_close()
| void lwir_device_close | ( | struct lwir_device * | device | ) |
Close an initialized session; safe repeatedly and preserves errno.
Native failed unmaps remain owned for a subsequent close and prevent reopening. Linux descriptor-close errors are never retried on a reused number.
Close an initialized session; safe repeatedly and preserves errno.
- STREAMOFF returns all buffers from the driver queue to user space.
- munmap each mapping. A failed unmap keeps its entry marked as mapped and the session struct is not cleared, so a later close retries it and lwir_device_open() refuses with EBUSY rather than losing track of memory the process still maps.
- REQBUFS with count 0 frees the kernel buffers when the driver allows it.
- close() the descriptor exactly once. Its state is cleared first and a close error is only logged: Linux frees the number even on error, so retrying could close an unrelated descriptor opened by another thread.
Errors of STREAMOFF/REQBUFS are deliberately ignored; there is no better recovery than continuing teardown, and closing the descriptor ends the stream regardless.
- Parameters
-
device Session to release; NULL and already-closed sessions are accepted.
- Note
- errno is preserved so callers can close on an error path without losing the original cause.
Definition at line 525 of file lwir_device_v4l2.c.
◆ lwir_device_control()
| bool lwir_device_control | ( | struct lwir_device * | device, |
| const struct lwir_control_request * | request, | ||
| struct lwir_control_result * | result ) |
Submit one Tiny1-C vendor control write (or FFC action) as a standalone operation.
- Parameters
-
device Open combined-layout session; image-only cameras fail with ENOTSUP. request Validated control kind and value. result Caller-owned reply, always initialized.
- Returns
- True when the camera acknowledged the request.
Uses vendor control transfers through usbfs while uvcvideo keeps streaming. Normal capture never calls this.
- Warning
- The write is submitted once and never replayed automatically. A failure (including a close error after submission) does not prove the camera ignored it; read the value back rather than blindly retrying.
- Errors
- EINVAL invalid request; ENOTSUP image-only camera; ENODEV identity changed; EINTR cancelled; ETIMEDOUT camera did not answer; EIO other failures.
Submit one Tiny1-C vendor control write (or FFC action) as a standalone operation.
- Returns
- True when acknowledged.
Definition at line 1289 of file lwir_device_v4l2.c.
◆ lwir_device_control_read()
| bool lwir_device_control_read | ( | struct lwir_device * | device, |
| enum lwir_control_kind | kind, | ||
| struct lwir_control_result * | result ) |
Read the current value of one Tiny1-C control without writing it.
- Parameters
-
device Open combined-layout session. kind Control to read; LWIR_CONTROL_FFC is an action and is rejected (EINVAL). result Caller-owned reply, always initialized.
- Returns
- True when the value was read; errors as for lwir_device_control().
Read the current value of one Tiny1-C control without writing it.
Builds a request only so the shared validation path can be reused.
- Returns
- True when the value was read.
Definition at line 1300 of file lwir_device_v4l2.c.
◆ lwir_device_discard()
| bool lwir_device_discard | ( | struct lwir_device * | device, |
| bool * | received ) |
Drain one pending frame without retaining the borrowed UVC buffer.
- Parameters
-
device Open session. received Whether a frame was present, written on success.
- Returns
- True on successful polling, even when no frame is present.
Non-blocking. A drained frame still counts toward startup qualification, so idle draining can complete it before the first request.
Drain one pending frame without retaining the borrowed UVC buffer.
Used to empty the queue (for example the non-MONOTONIC drain in lwir_device_acquire()) and to keep the stream moving between requests. The frame still feeds startup qualification with the one-second recency window, and the marker is published as soon as eight good frames are seen; no warmup delay applies here because there is no request start to measure from.
- Returns
- True on success, including when no frame was pending.
- Errors
- EINVAL bad arguments or session; EIO poisoned; EINTR cancelled; kernel or clock errno (session then poisoned).
Definition at line 1090 of file lwir_device_v4l2.c.
◆ lwir_device_open()
| bool lwir_device_open | ( | struct lwir_device_options * | options, |
| struct lwir_device * | device ) |
Open/start a bounded camera-specific combined or image-only YUY2 stream.
- Parameters
-
options Requested policy; native dimensions are written on success. device Empty caller-owned session, closed on failure.
- Returns
- True on success; errno describes failure. Close before reopening.
- Errors
- EINVAL invalid options; EBUSY session still owns a descriptor or mapping; ENODEV no matching camera; EEXIST more than one matching camera during a scan; EWOULDBLOCK another process holds the camera; ENOTSUP unsupported format or image-only camera when thermal data is required; ETIMEDOUT or EINTR deadline or cancellation; other values come from the kernel.
Open/start a bounded camera-specific combined or image-only YUY2 stream.
- Validate options and refuse while the session still owns anything, including mappings kept after a failed munmap (EBUSY).
- Compute one absolute deadline covering discovery and setup.
- With an explicit device path, probe only that node. Otherwise probe /dev/video0..63. A second matching camera is an error (EEXIST) rather than "first wins": with two cameras attached the choice would depend on enumeration order, so the caller must disambiguate with a serial or path. Each match holds its own flock until the scan decides.
- Read the startup marker, then set up streaming.
Every failure after a successful probe closes the session, so the caller never has to clean up after a false return.
- Returns
- True when streaming; errno set otherwise (see lwir_device.h).
Definition at line 651 of file lwir_device_v4l2.c.
◆ lwir_device_read_state()
| void lwir_device_read_state | ( | struct lwir_device * | device, |
| struct lwir_device_state * | state ) |
Read bounded optional state after acquisition, never writing device settings.
- Parameters
-
device Open session with its cancellation flag. state Caller-owned result with per-field failure statuses.
The snapshot is not frame-atomic and cannot establish gain at exposure. Image-only TDK sessions return a not-requested snapshot without USB commands.
Read bounded optional state after acquisition, never writing device settings.
All fields start as skipped and the first as an I/O error, so a failure to open usbfs is reported on a field instead of looking like an empty but successful read. lwir_state_read() overwrites what it reaches. The usbfs close result is ignored because nothing was written. Image-only sessions (or NULL) return a zero, not-requested snapshot without any USB traffic.
- Note
- errno is preserved; outcomes are reported only through
state. - The snapshot is taken after the frame and is not frame-atomic.
Definition at line 1319 of file lwir_device_v4l2.c.