Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) .. _v4l2-meta-fmt-d4xx:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) *******************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) V4L2_META_FMT_D4XX ('D4XX')
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) *******************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) Intel D4xx UVC Cameras Metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) means, that the private D4XX metadata, following the standard UVC header, is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) organised in blocks. D4XX cameras implement several standard block types,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) proposed by Microsoft, and several proprietary ones. Supported standard metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) document describes proprietary metadata types, used by D4xx cameras.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) payload header data. D4xx cameras use bulk transfers and only send one payload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) per frame, therefore their headers cannot be larger than 255 bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) Below are proprietary Microsoft style metadata types, used by D4xx cameras,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) where all fields are in little endian order:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) .. tabularcolumns:: |p{5.0cm}|p{12.5cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) .. flat-table:: D4xx metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36)     :widths: 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37)     :header-rows:  1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38)     :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40)     * - **Field**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41)       - **Description**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42)     * - :cspan:`1` *Depth Control*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43)     * - __u32 ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44)       - 0x80000000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45)     * - __u32 Size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46)       - Size in bytes (currently 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47)     * - __u32 Version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48)       - Version of this structure. The documentation herein corresponds to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49)         version xxx. The version number will be incremented when new fields are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50)         added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51)     * - __u32 Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52)       - A bitmask of flags: see [2_] below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53)     * - __u32 Gain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54)       - Gain value in internal units, same as the V4L2_CID_GAIN control, used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 	capture the frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56)     * - __u32 Exposure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57)       - Exposure time (in microseconds) used to capture the frame
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58)     * - __u32 Laser power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59)       - Power of the laser LED 0-360, used for depth measurement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60)     * - __u32 AE mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61)       - 0: manual; 1: automatic exposure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62)     * - __u32 Exposure priority
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63)       - Exposure priority value: 0 - constant frame rate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64)     * - __u32 AE ROI left
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65)       - Left border of the AE Region of Interest (all ROI values are in pixels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) 	and lie between 0 and maximum width or height respectively)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67)     * - __u32 AE ROI right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68)       - Right border of the AE Region of Interest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69)     * - __u32 AE ROI top
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70)       - Top border of the AE Region of Interest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71)     * - __u32 AE ROI bottom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72)       - Bottom border of the AE Region of Interest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73)     * - __u32 Preset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74)       - Preset selector value, default: 0, unless changed by the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75)     * - __u32 Laser mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76)       - 0: off, 1: on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77)     * - :cspan:`1` *Capture Timing*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78)     * - __u32 ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79)       - 0x80000001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80)     * - __u32 Size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81)       - Size in bytes (currently 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82)     * - __u32 Version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)       - Version of this structure. The documentation herein corresponds to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84)         version xxx. The version number will be incremented when new fields are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85)         added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86)     * - __u32 Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87)       - A bitmask of flags: see [3_] below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88)     * - __u32 Frame counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89)       - Monotonically increasing counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90)     * - __u32 Optical time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91)       - Time in microseconds from the beginning of a frame till its middle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92)     * - __u32 Readout time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93)       - Time, used to read out a frame in microseconds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94)     * - __u32 Exposure time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)       - Frame exposure time in microseconds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)     * - __u32 Frame interval
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97)       - In microseconds = 1000000 / framerate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)     * - __u32 Pipe latency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)       - Time in microseconds from start of frame to data in USB buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)     * - :cspan:`1` *Configuration*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)     * - __u32 ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)       - 0x80000002
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)     * - __u32 Size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)       - Size in bytes (currently 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)     * - __u32 Version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)       - Version of this structure. The documentation herein corresponds to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)         version xxx. The version number will be incremented when new fields are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)         added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)     * - __u32 Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)       - A bitmask of flags: see [4_] below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)     * - __u8 Hardware type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)       - Camera hardware version [5_]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)     * - __u8 SKU ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)       - Camera hardware configuration [6_]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)     * - __u32 Cookie
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)       - Internal synchronisation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)     * - __u16 Format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)       - Image format code [7_]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)     * - __u16 Width
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)       - Width in pixels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)     * - __u16 Height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)       - Height in pixels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)     * - __u16 Framerate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)       - Requested frame rate per second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)     * - __u16 Trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) .. _1:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) [1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) .. _2:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) [2] Depth Control flags specify which fields are valid: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)   0x00000001 Gain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)   0x00000002 Exposure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)   0x00000004 Laser power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)   0x00000008 AE mode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)   0x00000010 Exposure priority
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)   0x00000020 AE ROI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)   0x00000040 Preset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) .. _3:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) [3] Capture Timing flags specify which fields are valid: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)   0x00000001 Frame counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)   0x00000002 Optical time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)   0x00000004 Readout time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)   0x00000008 Exposure time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)   0x00000010 Frame interval
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)   0x00000020 Pipe latency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) .. _4:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) [4] Configuration flags specify which fields are valid: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)   0x00000001 Hardware type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)   0x00000002 SKU ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)   0x00000004 Cookie
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)   0x00000008 Format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)   0x00000010 Width
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)   0x00000020 Height
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)   0x00000040 Framerate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)   0x00000080 Trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)   0x00000100 Cal count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) .. _5:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) [5] Camera model: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)   0 DS5
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)   1 IVCAM2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) .. _6:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) [6] 8-bit camera hardware configuration bitfield: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)   [1:0] depthCamera
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 	00: no depth
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 	01: standard depth
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 	10: wide depth
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) 	11: reserved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)   [2]   depthIsActive - has a laser projector
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)   [3]   RGB presence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)   [4]   Inertial Measurement Unit (IMU) presence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)   [5]   projectorType
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) 	0: HPTG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 	1: Princeton
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)   [6]   0: a projector, 1: an LED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)   [7]   reserved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) .. _7:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) [7] Image format codes per video streaming interface:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Depth: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)   1 Z16
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)   2 Z
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Left sensor: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)   1 Y8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)   2 UYVY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)   3 R8L8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)   4 Calibration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)   5 W10
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) Fish Eye sensor: ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)   1 RAW8