Skip to contentSkip to conversation

media: uapi: v4l: Intel metadata format update

PATCH Superseded Dmitry Perchanov 4 participants 9 messages May 14, 2023 – Jun 2, 2023 Media (V4L/DVB)

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 media: uapi: v4l: Intel metadata format update

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

---
 .../media/v4l/pixfmt-meta-d4xx.rst            | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +17 -3
index 4e437ba97a0e..01f7e624ab6f 100644
@@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata
 Description
 ===========
 
-Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
 means, that the private D4XX metadata, following the standard UVC header, is
 organised in blocks. D4XX cameras implement several standard block types,
@@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
 payload header data. D4xx cameras use bulk transfers and only send one payload
 per frame, therefore their headers cannot be larger than 255 bytes.
 
+This document implements Intel Configuration version 3.
+
 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
 where all fields are in little endian order:
 
@@ -43,7 +45,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000000
     * - __u32 Size
-      - Size in bytes (currently 56)
+      - Size in bytes (currently 60)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -72,8 +74,12 @@ where all fields are in little endian order:
       - Bottom border of the AE Region of Interest
     * - __u32 Preset
       - Preset selector value, default: 0, unless changed by the user
-    * - __u32 Laser mode
+    * - __u8 Emitter mode
       - 0: off, 1: on
+    * - __u8 RFU byte
+      - Spare byte for future use
+    * - __u16 LED Power
+      - Led power value 0-360 (F416 SKU)
     * - :cspan:`1` *Capture Timing*
     * - __u32 ID
       - 0x80000001
@@ -124,6 +130,14 @@ where all fields are in little endian order:
       - Requested frame rate per second
     * - __u16 Trigger
       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+    * - __u16 Calibration count
+      - Calibration counter
+    * - __u8 GPIO input data
+      - GPIO readout (Supported from FW 5.12.7.0)
+    * - __u32 Sub-preset info
+      - Sub-preset choice information
+    * - __u8 reserved
+      - RFU byte.
 
 .. _1:
 
Signature · 10 lines
2.25.1


---------------------------------------------------------------------
Intel Israel (74) Limited

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.
#1 lore raw

Hi Dmitry,

Quoted 4 lines · Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

Could you reply my comments on v2 and use my @intel.com address going forward?

Thanks.

Signature · 3 lines
Kind regards,

Sakari Ailus
#2 lore raw
Quoted 10 lines · Sakari Ailus

Hi Dmitry,

Quoted 4 lines · Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

Could you reply my comments on v2 and use my @intel.com address going forward?

It's done.
Thanks.

Quoted 3 lines

Thanks.

---------------------------------------------------------------------
Intel Israel (74) Limited

This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.

#3 lore raw

PATCH v4 1/1 media: uapi: v4l: Intel metadata format update

In reply to Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

---
 .../media/v4l/pixfmt-meta-d4xx.rst            | 52 ++++++++++++++++---
 1 file changed, 46 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +46 -6
index 4e437ba97a0e..7482f298d0cc 100644
@@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata
 Description
 ===========
 
-Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
 means, that the private D4XX metadata, following the standard UVC header, is
 organised in blocks. D4XX cameras implement several standard block types,
@@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
 payload header data. D4xx cameras use bulk transfers and only send one payload
 per frame, therefore their headers cannot be larger than 255 bytes.
 
+This document implements Intel Configuration version 3 [9_].
+
 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
 where all fields are in little endian order:
 
@@ -43,7 +45,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000000
     * - __u32 Size
-      - Size in bytes (currently 56)
+      - Size in bytes, include ID (all protocol versions: 60)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -72,13 +74,17 @@ where all fields are in little endian order:
       - Bottom border of the AE Region of Interest
     * - __u32 Preset
       - Preset selector value, default: 0, unless changed by the user
-    * - __u32 Laser mode
-      - 0: off, 1: on
+    * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
+      - 0: off, 1: on, same as __u32 Laser mode for v1
+    * - __u8 RFU byte (v3 only)
+      - Spare byte for future use
+    * - __u16 LED Power (v3 only)
+      - Led power value 0-360 (F416 SKU)
     * - :cspan:`1` *Capture Timing*
     * - __u32 ID
       - 0x80000001
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (all protocol versions: 40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -101,7 +107,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000002
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (v1:36, v3:40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -124,6 +130,14 @@ where all fields are in little endian order:
       - Requested frame rate per second
     * - __u16 Trigger
       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+    * - __u16 Calibration count (v3 only)
+      - Calibration counter, see [4_] below
+    * - __u8 GPIO input data (v3 only)
+      - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
+    * - __u32 Sub-preset info (v3 only)
+      - Sub-preset choice information, see [4_] below
+    * - __u8 reserved (v3 only)
+      - RFU byte.
 
 .. _1:
 
@@ -140,6 +154,8 @@ where all fields are in little endian order:
   0x00000010 Exposure priority
   0x00000020 AE ROI
   0x00000040 Preset
+  0x00000080 Emitter mode
+  0x00000100 LED Power
 
 .. _3:
 
@@ -165,6 +181,8 @@ where all fields are in little endian order:
   0x00000040 Framerate
   0x00000080 Trigger
   0x00000100 Cal count
+  0x00000200 GPIO Input Data
+  0x00000400 Sub-preset Info
 
 .. _5:
 
@@ -211,3 +229,25 @@ Left sensor: ::
 Fish Eye sensor: ::
 
   1 RAW8
+
+.. _8:
+
+[8] The "Laser mode" is replaced by three different fields.
+"Laser" renamed to "Emitter" as there multiple technologies
+for camera projectors. As we have another field for "Laser Power"
+we introduced "LED Power" for extra emitter.
+
+The __u32 "Laser mode" integer is divided by two bytes and short: ::
+   1 __u8 Emitter mode
+   2 __u8 RFU byte
+   3 __u16 LED Power
+
+This is a change between versions 1 and 3. All versions 1,2 and 3
+are backward compatible with same data format and they are supported.
+See [2_] for which attributes are valid.
+
+.. _9:
+
+[9]
+LibRealSense SDK metadata source:
+https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h
Signature · 10 lines
2.25.1


---------------------------------------------------------------------
Intel Israel (74) Limited

This e-mail and any attachments may contain confidential material for
the sole use of the intended recipient(s). Any review or distribution
by others is strictly prohibited. If you are not the intended
recipient, please contact the sender and delete all copies.
Reviewed-by on v4 1/1
#5 lore raw
In reply to Dmitry Perchanov

Hi Dmitry,

Thank you for the patch.

Quoted 31 lines · Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

---
 .../media/v4l/pixfmt-meta-d4xx.rst            | 52 ++++++++++++++++---
 1 file changed, 46 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +3 -1
index 4e437ba97a0e..7482f298d0cc 100644
@@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata
 Description
 ===========
 
-Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
 means, that the private D4XX metadata, following the standard UVC header, is
 organised in blocks. D4XX cameras implement several standard block types,
@@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
 payload header data. D4xx cameras use bulk transfers and only send one payload
 per frame, therefore their headers cannot be larger than 255 bytes.
 
+This document implements Intel Configuration version 3 [9_].
+
 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
 where all fields are in little endian order:
 

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 51

Quoted 8 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -1
@@ -43,7 +45,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000000
     * - __u32 Size
-      - Size in bytes (currently 56)
+      - Size in bytes, include ID (all protocol versions: 60)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are

Should this read "version 3" instead of "version xxx" ?

Quoted 64 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +20 -4
@@ -72,13 +74,17 @@ where all fields are in little endian order:
       - Bottom border of the AE Region of Interest
     * - __u32 Preset
       - Preset selector value, default: 0, unless changed by the user
-    * - __u32 Laser mode
-      - 0: off, 1: on
+    * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
+      - 0: off, 1: on, same as __u32 Laser mode for v1
+    * - __u8 RFU byte (v3 only)
+      - Spare byte for future use
+    * - __u16 LED Power (v3 only)
+      - Led power value 0-360 (F416 SKU)
     * - :cspan:`1` *Capture Timing*
     * - __u32 ID
       - 0x80000001
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (all protocol versions: 40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -101,7 +107,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000002
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (v1:36, v3:40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -124,6 +130,14 @@ where all fields are in little endian order:
       - Requested frame rate per second
     * - __u16 Trigger
       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+    * - __u16 Calibration count (v3 only)
+      - Calibration counter, see [4_] below
+    * - __u8 GPIO input data (v3 only)
+      - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
+    * - __u32 Sub-preset info (v3 only)
+      - Sub-preset choice information, see [4_] below
+    * - __u8 reserved (v3 only)
+      - RFU byte.
 
 .. _1:
 
@@ -140,6 +154,8 @@ where all fields are in little endian order:
   0x00000010 Exposure priority
   0x00000020 AE ROI
   0x00000040 Preset
+  0x00000080 Emitter mode
+  0x00000100 LED Power
 
 .. _3:
 
@@ -165,6 +181,8 @@ where all fields are in little endian order:
   0x00000040 Framerate
   0x00000080 Trigger
   0x00000100 Cal count
+  0x00000200 GPIO Input Data
+  0x00000400 Sub-preset Info
 
 .. _5:
 

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 235

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
@@ -211,3 +229,25 @@ Left sensor: ::
 Fish Eye sensor: ::
 
   1 RAW8
+
+.. _8:
+
+[8] The "Laser mode" is replaced by three different fields.

"... has been replaced in version 3 by ..."

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 236

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+"Laser" renamed to "Emitter" as there multiple technologies

s/there/there are/

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 240

Quoted 4 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
+for camera projectors. As we have another field for "Laser Power"
+we introduced "LED Power" for extra emitter.
+
+The __u32 "Laser mode" integer is divided by two bytes and short: ::

The "Laser mode" __u32 field has been split into: ::

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 245

Quoted 5 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +5 -0
+   1 __u8 Emitter mode
+   2 __u8 RFU byte
+   3 __u16 LED Power
+
+This is a change between versions 1 and 3. All versions 1,2 and 3

s/1,2/1, 2/

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 252

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +7 -0
+are backward compatible with same data format and they are supported.
+See [2_] for which attributes are valid.
+
+.. _9:
+
+[9]
+LibRealSense SDK metadata source:

I'll remove the blank line after '[9]', that is

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 253

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+[9] LibRealSense SDK metadata source:

I can fix all this when applying if you're fine with the changes.

Quoted 1 line

+https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h

Signature · 3 lines
Regards,

Laurent Pinchart
#6 lore raw

Hi Laurent,

Thanks for review!
I will gladly accept your proposed changes.

Comments inline.

Quoted 35 lines · Laurent Pinchart

Hi Dmitry,

Thank you for the patch.

Quoted 30 lines · Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

---
 .../media/v4l/pixfmt-meta-d4xx.rst            | 52 ++++++++++++++++---
 1 file changed, 46 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +3 -1
index 4e437ba97a0e..7482f298d0cc 100644
@@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata
 Description
 ===========
 
-Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
 means, that the private D4XX metadata, following the standard UVC header, is
 organised in blocks. D4XX cameras implement several standard block types,
@@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
 payload header data. D4xx cameras use bulk transfers and only send one payload
 per frame, therefore their headers cannot be larger than 255 bytes.
 
+This document implements Intel Configuration version 3 [9_].
+
 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
 where all fields are in little endian order:
 
Quoted 11 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 51

Quoted 9 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -1
@@ -43,7 +45,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000000
     * - __u32 Size
-      - Size in bytes (currently 56)
+      - Size in bytes, include ID (all protocol versions: 60)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are

Should this read "version 3" instead of "version xxx" ?

This can read 1, 2 or 3, depends on firmware version. All cameras have same firmware. The latest will report 3.

Quoted 77 lines
Quoted 67 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +20 -4
@@ -72,13 +74,17 @@ where all fields are in little endian order:
       - Bottom border of the AE Region of Interest
     * - __u32 Preset
       - Preset selector value, default: 0, unless changed by the user
-    * - __u32 Laser mode
-      - 0: off, 1: on
+    * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
+      - 0: off, 1: on, same as __u32 Laser mode for v1
+    * - __u8 RFU byte (v3 only)
+      - Spare byte for future use
+    * - __u16 LED Power (v3 only)
+      - Led power value 0-360 (F416 SKU)
     * - :cspan:`1` *Capture Timing*
     * - __u32 ID
       - 0x80000001
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (all protocol versions: 40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -101,7 +107,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000002
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (v1:36, v3:40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -124,6 +130,14 @@ where all fields are in little endian order:
       - Requested frame rate per second
     * - __u16 Trigger
       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+    * - __u16 Calibration count (v3 only)
+      - Calibration counter, see [4_] below
+    * - __u8 GPIO input data (v3 only)
+      - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
+    * - __u32 Sub-preset info (v3 only)
+      - Sub-preset choice information, see [4_] below
+    * - __u8 reserved (v3 only)
+      - RFU byte.
 
 .. _1:
 
@@ -140,6 +154,8 @@ where all fields are in little endian order:
   0x00000010 Exposure priority
   0x00000020 AE ROI
   0x00000040 Preset
+  0x00000080 Emitter mode
+  0x00000100 LED Power
 
 .. _3:
 
@@ -165,6 +181,8 @@ where all fields are in little endian order:
   0x00000040 Framerate
   0x00000080 Trigger
   0x00000100 Cal count
+  0x00000200 GPIO Input Data
+  0x00000400 Sub-preset Info
 
 .. _5:
 

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 235

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
@@ -211,3 +229,25 @@ Left sensor: ::
 Fish Eye sensor: ::
 
   1 RAW8
+
+.. _8:
+
+[8] The "Laser mode" is replaced by three different fields.

"... has been replaced in version 3 by ..."

Quoted 3 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 236

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+"Laser" renamed to "Emitter" as there multiple technologies

s/there/there are/

Accepted. Thanks!

Quoted 9 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 240

Quoted 5 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
+for camera projectors. As we have another field for "Laser Power"
+we introduced "LED Power" for extra emitter.
+
+The __u32 "Laser mode" integer is divided by two bytes and short: ::

The "Laser mode" __u32 field has been split into: ::

Accepted. Thanks!

Quoted 8 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 245

Quoted 5 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +5 -0
+   1 __u8 Emitter mode
+   2 __u8 RFU byte
+   3 __u16 LED Power
+
+This is a change between versions 1 and 3. All versions 1,2 and 3

s/1,2/1, 2/

Accepted. Thanks!

Quoted 12 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 252

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +7 -0
+are backward compatible with same data format and they are supported.
+See [2_] for which attributes are valid.
+
+.. _9:
+
+[9]
+LibRealSense SDK metadata source:

I'll remove the blank line after '[9]', that is

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+[9] LibRealSense SDK metadata source:

Accepted. Thanks!

Quoted 2 lines

I can fix all this when applying if you're fine with the changes.

Yes, I agree. Thank You for your effort!

Quoted 3 lines
Quoted 1 line

+https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h

---------------------------------------------------------------------
Intel Israel (74) Limited

This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.

#7 lore raw

Hi Dmitry,

Quoted 51 lines · Dmitry Perchanov

Hi Laurent,

Thanks for review!
I will gladly accept your proposed changes.

Comments inline.

Quoted 31 lines · Laurent Pinchart
Quoted 30 lines · Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

---
 .../media/v4l/pixfmt-meta-d4xx.rst            | 52 ++++++++++++++++---
 1 file changed, 46 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +3 -1
index 4e437ba97a0e..7482f298d0cc 100644
@@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata
 Description
 ===========
 
-Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
 means, that the private D4XX metadata, following the standard UVC header, is
 organised in blocks. D4XX cameras implement several standard block types,
@@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
 payload header data. D4xx cameras use bulk transfers and only send one payload
 per frame, therefore their headers cannot be larger than 255 bytes.
 
+This document implements Intel Configuration version 3 [9_].
+
 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
 where all fields are in little endian order:
 
Quoted 11 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 51

Quoted 9 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -1
@@ -43,7 +45,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000000
     * - __u32 Size
-      - Size in bytes (currently 56)
+      - Size in bytes, include ID (all protocol versions: 60)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are

Should this read "version 3" instead of "version xxx" ?

Quoted 2 lines

This can read 1, 2 or 3, depends on firmware version. All cameras have same firmware. The latest will report 3.

The sentence reads

"The documentation herein corresponds to version xxx."

As you're updating the documentation to correspond to version 3, I thought it would be best to make that explicit. Another option would be

"The documentation herein covers versions 1, 2 and 3."

I think I like that better. What do you think ?

Quoted 120 lines
Quoted 74 lines
Quoted 64 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +20 -4
@@ -72,13 +74,17 @@ where all fields are in little endian order:
       - Bottom border of the AE Region of Interest
     * - __u32 Preset
       - Preset selector value, default: 0, unless changed by the user
-    * - __u32 Laser mode
-      - 0: off, 1: on
+    * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
+      - 0: off, 1: on, same as __u32 Laser mode for v1
+    * - __u8 RFU byte (v3 only)
+      - Spare byte for future use
+    * - __u16 LED Power (v3 only)
+      - Led power value 0-360 (F416 SKU)
     * - :cspan:`1` *Capture Timing*
     * - __u32 ID
       - 0x80000001
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (all protocol versions: 40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -101,7 +107,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000002
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (v1:36, v3:40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -124,6 +130,14 @@ where all fields are in little endian order:
       - Requested frame rate per second
     * - __u16 Trigger
       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+    * - __u16 Calibration count (v3 only)
+      - Calibration counter, see [4_] below
+    * - __u8 GPIO input data (v3 only)
+      - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
+    * - __u32 Sub-preset info (v3 only)
+      - Sub-preset choice information, see [4_] below
+    * - __u8 reserved (v3 only)
+      - RFU byte.
 
 .. _1:
 
@@ -140,6 +154,8 @@ where all fields are in little endian order:
   0x00000010 Exposure priority
   0x00000020 AE ROI
   0x00000040 Preset
+  0x00000080 Emitter mode
+  0x00000100 LED Power
 
 .. _3:
 
@@ -165,6 +181,8 @@ where all fields are in little endian order:
   0x00000040 Framerate
   0x00000080 Trigger
   0x00000100 Cal count
+  0x00000200 GPIO Input Data
+  0x00000400 Sub-preset Info
 
 .. _5:
 

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 235

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
@@ -211,3 +229,25 @@ Left sensor: ::
 Fish Eye sensor: ::
 
   1 RAW8
+
+.. _8:
+
+[8] The "Laser mode" is replaced by three different fields.

"... has been replaced in version 3 by ..."

Quoted 3 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 236

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+"Laser" renamed to "Emitter" as there multiple technologies

s/there/there are/

Accepted. Thanks!

Quoted 6 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 240

Quoted 4 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
+for camera projectors. As we have another field for "Laser Power"
+we introduced "LED Power" for extra emitter.
+
+The __u32 "Laser mode" integer is divided by two bytes and short: ::

The "Laser mode" __u32 field has been split into: ::

Accepted. Thanks!

Quoted 7 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 245

Quoted 5 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +5 -0
+   1 __u8 Emitter mode
+   2 __u8 RFU byte
+   3 __u16 LED Power
+
+This is a change between versions 1 and 3. All versions 1,2 and 3

s/1,2/1, 2/

Accepted. Thanks!

Quoted 11 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 252

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +7 -0
+are backward compatible with same data format and they are supported.
+See [2_] for which attributes are valid.
+
+.. _9:
+
+[9]
+LibRealSense SDK metadata source:

I'll remove the blank line after '[9]', that is

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+[9] LibRealSense SDK metadata source:

Accepted. Thanks!

Quoted 1 line

I can fix all this when applying if you're fine with the changes.

Yes, I agree. Thank You for your effort!

Quoted 3 lines
Quoted 1 line

+https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h

Signature · 3 lines
Regards,

Laurent Pinchart
#8 lore raw

Hi Laurent,

Quoted 59 lines · Laurent Pinchart

Hi Dmitry,

Quoted 51 lines · Dmitry Perchanov

Hi Laurent,

Thanks for review!
I will gladly accept your proposed changes.

Comments inline.

Quoted 31 lines · Laurent Pinchart
Quoted 30 lines · Dmitry Perchanov

Update metadata structure for Intel RealSense UVC/MIPI cameras. Compliant to Intel Configuration version 3.

---
 .../media/v4l/pixfmt-meta-d4xx.rst            | 52 ++++++++++++++++---
 1 file changed, 46 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +3 -1
index 4e437ba97a0e..7482f298d0cc 100644
@@ -12,7 +12,7 @@ Intel D4xx UVC Cameras Metadata
 Description
 ===========
 
-Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC
+Intel D4xx (D435, D455 and others) cameras include per-frame metadata in their UVC
 payload headers, following the Microsoft(R) UVC extension proposal [1_]. That
 means, that the private D4XX metadata, following the standard UVC header, is
 organised in blocks. D4XX cameras implement several standard block types,
@@ -26,6 +26,8 @@ V4L2_META_FMT_UVC with the only difference, that it also includes proprietary
 payload header data. D4xx cameras use bulk transfers and only send one payload
 per frame, therefore their headers cannot be larger than 255 bytes.
 
+This document implements Intel Configuration version 3 [9_].
+
 Below are proprietary Microsoft style metadata types, used by D4xx cameras,
 where all fields are in little endian order:
 
Quoted 11 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 51

Quoted 9 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -1
@@ -43,7 +45,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000000
     * - __u32 Size
-      - Size in bytes (currently 56)
+      - Size in bytes, include ID (all protocol versions: 60)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are

Should this read "version 3" instead of "version xxx" ?

Quoted 2 lines

This can read 1, 2 or 3, depends on firmware version. All cameras have same firmware. The latest will report 3.

The sentence reads

Quoted 8 lines

"The documentation herein corresponds to version xxx."

As you're updating the documentation to correspond to version 3, I thought it would be best to make that explicit. Another option would be

"The documentation herein covers versions 1, 2 and 3."

I think I like that better. What do you think ?

That is correct, my bad.
Let's change:
"This document implements Intel Configuration version 3" To:
"The documentation herein covers versions 1, 2 and 3."

Quoted 30 lines
Quoted 30 lines
Quoted 30 lines
Quoted 30 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +8 -4
@@ -72,13 +74,17 @@ where all fields are in little endian order:
       - Bottom border of the AE Region of Interest
     * - __u32 Preset
       - Preset selector value, default: 0, unless changed by the user
-    * - __u32 Laser mode
-      - 0: off, 1: on
+    * - __u8 Emitter mode (v3 only) (__u32 Laser mode for v1) [8_]
+      - 0: off, 1: on, same as __u32 Laser mode for v1
+    * - __u8 RFU byte (v3 only)
+      - Spare byte for future use
+    * - __u16 LED Power (v3 only)
+      - Led power value 0-360 (F416 SKU)
     * - :cspan:`1` *Capture Timing*
     * - __u32 ID
       - 0x80000001
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (all protocol versions: 40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
         version xxx. The version number will be incremented when new fields are
@@ -101,7 +107,7 @@ where all fields are in little endian order:
     * - __u32 ID
       - 0x80000002
     * - __u32 Size
-      - Size in bytes (currently 40)
+      - Size in bytes, include ID (v1:36, v3:40)
     * - __u32 Version
       - Version of this structure. The documentation herein corresponds to
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 135

Quoted 8 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +3 -0
         version xxx. The version number will be incremented when new fields are
@@ -124,6 +130,14 @@ where all fields are in little endian order:
       - Requested frame rate per second
     * - __u16 Trigger
       - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger
+    * - __u16 Calibration count (v3 only)
+      - Calibration counter, see [4_] below
+    * - __u8 GPIO input data (v3 only)

As i see from the source, the GPIO input data supported from v2, so this can be modified from "v3 only: to "v2, v3" Here is data from source:
=== CUT ===
Intel Configuration:
version 2: gpioInputData added to md_configuration (with its flag)
version 3: sub_preset_info added to md_configuration (with its flag)
=== CUT ===
Unfortunately there is no information when "Calibration counter" introduced but i can extrapolate it was from version 2.

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 139

Quoted 4 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
+      - GPIO readout, see [4_] below (Supported from FW 5.12.7.0)
+    * - __u32 Sub-preset info (v3 only)
+      - Sub-preset choice information, see [4_] below
+    * - __u8 reserved (v3 only)

"Sub-preset info" from version 3.

Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +3 -0
+      - RFU byte.
 
 .. _1:
 
@@ -140,6 +154,8 @@ where all fields are in little endian order:
   0x00000010 Exposure priority
   0x00000020 AE ROI
   0x00000040 Preset
+  0x00000080 Emitter mode
+  0x00000100 LED Power
 
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst where all fields are in little endian order: · line 185

Quoted 8 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +2 -0
 .. _3:
 
@@ -165,6 +181,8 @@ where all fields are in little endian order:
   0x00000040 Framerate
   0x00000080 Trigger
   0x00000100 Cal count
+  0x00000200 GPIO Input Data
+  0x00000400 Sub-preset Info

Here we mark which fields are relevant, there cannot be confusion from version 1, 2 or 3.

Quoted 53 lines
Quoted 53 lines
Quoted 14 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 235

Quoted 11 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
 .. _5:
 
@@ -211,3 +229,25 @@ Left sensor: ::
 Fish Eye sensor: ::
 
   1 RAW8
+
+.. _8:
+
+[8] The "Laser mode" is replaced by three different fields.

"... has been replaced in version 3 by ..."

Quoted 3 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 236

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+"Laser" renamed to "Emitter" as there multiple technologies

s/there/there are/

Accepted. Thanks!

Quoted 6 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 240

Quoted 4 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +4 -0
+for camera projectors. As we have another field for "Laser Power"
+we introduced "LED Power" for extra emitter.
+
+The __u32 "Laser mode" integer is divided by two bytes and short: ::

The "Laser mode" __u32 field has been split into: ::

Accepted. Thanks!

Quoted 7 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 245

Quoted 5 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +5 -0
+   1 __u8 Emitter mode
+   2 __u8 RFU byte
+   3 __u16 LED Power
+
+This is a change between versions 1 and 3. All versions 1,2 and 3

s/1,2/1, 2/

Accepted. Thanks!

Quoted 11 lines

Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst Left sensor: :: · line 252

Quoted 7 lines
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +7 -0
+are backward compatible with same data format and they are supported.
+See [2_] for which attributes are valid.
+
+.. _9:
+
+[9]
+LibRealSense SDK metadata source:

I'll remove the blank line after '[9]', that is

Quoted 1 line
Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst +1 -0
+[9] LibRealSense SDK metadata source:

Accepted. Thanks!

Quoted 7 lines
Quoted 7 lines
Quoted 1 line

I can fix all this when applying if you're fine with the changes.

Yes, I agree. Thank You for your effort!

Quoted 3 lines
Quoted 1 line

+https://github.com/IntelRealSense/librealsense/blob/master/src/metadata.h

---------------------------------------------------------------------
Intel Israel (74) Limited

This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies.