|
| 1 | +//! Thin FFI wrapper around NVIDIA Argus/libargus for MIPI CSI camera capture. |
| 2 | +//! |
| 3 | +//! This module provides DMA-buffer frame acquisition from MIPI cameras on Jetson |
| 4 | +//! platforms. Frames are blitted from Argus' EGLStream frame into NvBufSurface |
| 5 | +//! DMA file descriptors that can be passed to the hardware encoder without |
| 6 | +//! CPU-side pixel copies. |
| 7 | +//! |
| 8 | +//! The Argus API is C++, so we use a small C shim (linked via build.rs on |
| 9 | +//! Jetson) to expose the capture session lifecycle. |
| 10 | +
|
| 11 | +use std::ffi::c_int; |
| 12 | +use std::io; |
| 13 | + |
| 14 | +/// Opaque handle to an Argus capture session. |
| 15 | +pub struct ArgusCaptureSession { |
| 16 | + handle: *mut std::ffi::c_void, |
| 17 | + width: u32, |
| 18 | + height: u32, |
| 19 | +} |
| 20 | + |
| 21 | +/// A captured Argus frame backed by a DMA buffer. |
| 22 | +pub struct ArgusFrame { |
| 23 | + /// DMA buffer file descriptor containing an NV12 frame. |
| 24 | + pub dmabuf_fd: i32, |
| 25 | + /// Argus sensor start timestamp in nanoseconds, when available. |
| 26 | + pub sensor_timestamp_ns: Option<u64>, |
| 27 | + /// Time spent waiting for `FrameConsumer::acquireFrame` to return. |
| 28 | + pub acquire_wait_ns: u64, |
| 29 | + /// Time spent copying the acquired EGLStream frame into the DMA buffer. |
| 30 | + pub blit_ns: u64, |
| 31 | +} |
| 32 | + |
| 33 | +// The C++ session is single-threaded but we move it across the tokio runtime. |
| 34 | +unsafe impl Send for ArgusCaptureSession {} |
| 35 | + |
| 36 | +extern "C" { |
| 37 | + fn lk_argus_create_session( |
| 38 | + sensor_index: c_int, |
| 39 | + width: c_int, |
| 40 | + height: c_int, |
| 41 | + fps: c_int, |
| 42 | + ) -> *mut std::ffi::c_void; |
| 43 | + |
| 44 | + fn lk_argus_destroy_session(session: *mut std::ffi::c_void); |
| 45 | + |
| 46 | + /// Acquire the next frame and optionally return the Argus sensor timestamp. |
| 47 | + /// Returns the NvBufSurface DMA fd, or -1 on error. |
| 48 | + /// The fd is valid until the next acquire call or `lk_argus_release_frame`. |
| 49 | + fn lk_argus_acquire_frame_with_metadata( |
| 50 | + session: *mut std::ffi::c_void, |
| 51 | + sensor_timestamp_ns: *mut u64, |
| 52 | + acquire_wait_ns: *mut u64, |
| 53 | + blit_ns: *mut u64, |
| 54 | + ) -> c_int; |
| 55 | + |
| 56 | + /// Release the most recently acquired frame back to the Argus buffer pool. |
| 57 | + fn lk_argus_release_frame(session: *mut std::ffi::c_void); |
| 58 | +} |
| 59 | + |
| 60 | +impl ArgusCaptureSession { |
| 61 | + /// Open an Argus capture session on the given MIPI CSI sensor. |
| 62 | + /// |
| 63 | + /// `sensor_index` selects the camera (0 for the first CSI camera). |
| 64 | + /// The session negotiates the given resolution and framerate with the ISP. |
| 65 | + pub fn new(sensor_index: u32, width: u32, height: u32, fps: u32) -> io::Result<Self> { |
| 66 | + let handle = unsafe { |
| 67 | + lk_argus_create_session( |
| 68 | + sensor_index as c_int, |
| 69 | + width as c_int, |
| 70 | + height as c_int, |
| 71 | + fps as c_int, |
| 72 | + ) |
| 73 | + }; |
| 74 | + if handle.is_null() { |
| 75 | + return Err(io::Error::new( |
| 76 | + io::ErrorKind::Other, |
| 77 | + "Failed to create Argus capture session", |
| 78 | + )); |
| 79 | + } |
| 80 | + Ok(Self { handle, width, height }) |
| 81 | + } |
| 82 | + |
| 83 | + /// Acquire the next captured frame as a DMA buffer. |
| 84 | + /// |
| 85 | + /// The returned fd refers to an NvBufSurface in NV12 format. It remains |
| 86 | + /// valid until [`release_frame`](Self::release_frame) is called or the |
| 87 | + /// next `acquire_frame` implicitly releases the previous one. |
| 88 | + pub fn acquire_frame(&mut self) -> io::Result<ArgusFrame> { |
| 89 | + let mut sensor_timestamp_ns = 0; |
| 90 | + let mut acquire_wait_ns = 0; |
| 91 | + let mut blit_ns = 0; |
| 92 | + let fd = unsafe { |
| 93 | + lk_argus_acquire_frame_with_metadata( |
| 94 | + self.handle, |
| 95 | + &mut sensor_timestamp_ns, |
| 96 | + &mut acquire_wait_ns, |
| 97 | + &mut blit_ns, |
| 98 | + ) |
| 99 | + }; |
| 100 | + if fd < 0 { |
| 101 | + return Err(io::Error::new(io::ErrorKind::Other, "Argus frame acquisition failed")); |
| 102 | + } |
| 103 | + Ok(ArgusFrame { |
| 104 | + dmabuf_fd: fd, |
| 105 | + sensor_timestamp_ns: (sensor_timestamp_ns > 0).then_some(sensor_timestamp_ns), |
| 106 | + acquire_wait_ns, |
| 107 | + blit_ns, |
| 108 | + }) |
| 109 | + } |
| 110 | + |
| 111 | + /// Release the most recently acquired frame back to the buffer pool. |
| 112 | + pub fn release_frame(&mut self) { |
| 113 | + unsafe { lk_argus_release_frame(self.handle) }; |
| 114 | + } |
| 115 | + |
| 116 | + pub fn width(&self) -> u32 { |
| 117 | + self.width |
| 118 | + } |
| 119 | + |
| 120 | + pub fn height(&self) -> u32 { |
| 121 | + self.height |
| 122 | + } |
| 123 | +} |
| 124 | + |
| 125 | +impl Drop for ArgusCaptureSession { |
| 126 | + fn drop(&mut self) { |
| 127 | + if !self.handle.is_null() { |
| 128 | + unsafe { lk_argus_destroy_session(self.handle) }; |
| 129 | + self.handle = std::ptr::null_mut(); |
| 130 | + } |
| 131 | + } |
| 132 | +} |
| 133 | + |
| 134 | +/// Convert an Argus `CLOCK_MONOTONIC` sensor timestamp into a UNIX-epoch microsecond value |
| 135 | +/// by computing the offset between the current monotonic clock and the supplied wall time. |
| 136 | +pub fn sensor_monotonic_ns_to_unix_us(sensor_timestamp_ns: u64, wall_time_us: u64) -> Option<u64> { |
| 137 | + let monotonic_now_ns = monotonic_time_ns_now()?; |
| 138 | + let monotonic_delta_us = monotonic_now_ns.abs_diff(sensor_timestamp_ns) / 1_000; |
| 139 | + if sensor_timestamp_ns <= monotonic_now_ns { |
| 140 | + Some(wall_time_us.saturating_sub(monotonic_delta_us)) |
| 141 | + } else { |
| 142 | + Some(wall_time_us.saturating_add(monotonic_delta_us)) |
| 143 | + } |
| 144 | +} |
| 145 | + |
| 146 | +/// Current `CLOCK_MONOTONIC` value in nanoseconds, used to translate Argus sensor |
| 147 | +/// timestamps into wall time. |
| 148 | +fn monotonic_time_ns_now() -> Option<u64> { |
| 149 | + #[repr(C)] |
| 150 | + struct Timespec { |
| 151 | + tv_sec: i64, |
| 152 | + tv_nsec: i64, |
| 153 | + } |
| 154 | + |
| 155 | + extern "C" { |
| 156 | + fn clock_gettime(clk_id: i32, tp: *mut Timespec) -> i32; |
| 157 | + } |
| 158 | + |
| 159 | + const CLOCK_MONOTONIC: i32 = 1; |
| 160 | + let mut ts = Timespec { tv_sec: 0, tv_nsec: 0 }; |
| 161 | + let ret = unsafe { |
| 162 | + // SAFETY: `ts` is a valid, writable `Timespec` for the duration of the call. |
| 163 | + clock_gettime(CLOCK_MONOTONIC, &mut ts) |
| 164 | + }; |
| 165 | + if ret != 0 || ts.tv_sec < 0 || ts.tv_nsec < 0 { |
| 166 | + return None; |
| 167 | + } |
| 168 | + Some(ts.tv_sec as u64 * 1_000_000_000 + ts.tv_nsec as u64) |
| 169 | +} |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments