Skip to contentSkip to conversation

Documentation: v4l: Document rotation and orientation for sensor drivers

PATCH Superseded Sakari Ailus 4 participants 5 messages Apr 5, 2023 – Apr 6, 2023

Subsystems (2)

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Sakari Ailus

author maintainer
#0 lore raw

PATCH v2 1/1 Documentation: v4l: Document rotation and orientation for sensor drivers

Document how rotation and orientation should be taken into account in writing camera sensor drivers.

---
since v1:

- Simplify language (Laurent's suggestion) and add note on flipping controls (Jacopo).

- Improve the last paragraph, say this is about rotation and orientation.

 Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst |  1 +
 2 files changed, 17 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +16 -0
index c7d4891bd24e..61caa7901c51 100644
@@ -151,3 +151,19 @@ used to obtain device's power state after the power state transition:
 The function returns a non-zero value if it succeeded getting the power count or
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have the camera sensor mounted upside down compared to its natural
+mounting rotation. In such cases, drivers shall expose the information to
+userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION
+<v4l2-camera-sensor-rotation>` control.
+
+Sensor drivers that have any vertical or horizontal flips embedded in the
+register programming sequences shall initialize the V4L2_CID_HFLIP and
+V4L2_CID_VFLIP controls with the values programmed by the register sequences.
+
+Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation
+information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
+register the appropriate controls.
Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +1 -0
index daa4f40869f8..29fe22da52a2 100644
@@ -536,6 +536,7 @@ enum v4l2_scene_mode -
       - The camera is not directly attached to the device and is freely movable.
 
 
+.. _v4l2-camera-sensor-rotation:
 
 ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
     This read-only control describes the rotation correction in degrees in the
Signature · 1 line
2.30.2
#1 lore raw
Quoted 11 lines · Sakari Ailus

Document how rotation and orientation should be taken into account in writing camera sensor drivers.

---
since v1:

- Simplify language (Laurent's suggestion) and add note on flipping controls (Jacopo).

- Improve the last paragraph, say this is about rotation and orientation.

This was meant to be v3, i.e. changes are since v2.

Signature · 1 line
Sakari Ailus
Reviewed-by on v2 1/1
#2 lore raw
In reply to Sakari Ailus

Hi Sakari

Quoted 27 lines · Sakari Ailus

Document how rotation and orientation should be taken into account in writing camera sensor drivers.

---
since v1:

- Simplify language (Laurent's suggestion) and add note on flipping controls (Jacopo).

- Improve the last paragraph, say this is about rotation and orientation.

 Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst |  1 +
 2 files changed, 17 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +3 -0
index c7d4891bd24e..61caa7901c51 100644
@@ -151,3 +151,19 @@ used to obtain device's power state after the power state transition:
 The function returns a non-zero value if it succeeded getting the power count or
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------

Documentation/driver-api/media/camera-sensor.rst used to obtain device's power state after the power state transition: · line 166

Quoted 10 lines
Documentation/driver-api/media/camera-sensor.rst +10 -0
+
+Some systems have the camera sensor mounted upside down compared to its natural
+mounting rotation. In such cases, drivers shall expose the information to
+userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION
+<v4l2-camera-sensor-rotation>` control.
+
+Sensor drivers that have any vertical or horizontal flips embedded in the
+register programming sequences shall initialize the V4L2_CID_HFLIP and
+V4L2_CID_VFLIP controls with the values programmed by the register sequences.
+

Just a note about the paragraph about ORIENTATION I suggested on the previous version. If it was left out intentionally:

Thanks
j

Quoted 18 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation
+information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
+register the appropriate controls.
Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +1 -1
index daa4f40869f8..29fe22da52a2 100644
@@ -536,6 +536,7 @@ enum v4l2_scene_mode -
       - The camera is not directly attached to the device and is freely movable.
 
 
+.. _v4l2-camera-sensor-rotation:
 
 ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
     This read-only control describes the rotation correction in degrees in the
--

2.30.2

#3 lore raw

Hello,

Quoted 30 lines · Jacopo Mondi
Quoted 29 lines · Sakari Ailus

Document how rotation and orientation should be taken into account in writing camera sensor drivers.

---
since v1:

- Simplify language (Laurent's suggestion) and add note on flipping controls (Jacopo).

- Improve the last paragraph, say this is about rotation and orientation.

 Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst |  1 +
 2 files changed, 17 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +5 -0
index c7d4891bd24e..61caa7901c51 100644
@@ -151,3 +151,19 @@ used to obtain device's power state after the power state transition:
 The function returns a non-zero value if it succeeded getting the power count or
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have the camera sensor mounted upside down compared to its natural
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst used to obtain device's power state after the power state transition: · line 166

Quoted 8 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
+mounting rotation. In such cases, drivers shall expose the information to
+userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION
+<v4l2-camera-sensor-rotation>` control.
+
+Sensor drivers that have any vertical or horizontal flips embedded in the
+register programming sequences shall initialize the V4L2_CID_HFLIP and
+V4L2_CID_VFLIP controls with the values programmed by the register sequences.
+

I would move this paragraph below the next one, to keep the two paragraphs related to the rotation and orientation together. You may also want to expand the section title to cover flipping, or add a new flipping section (although it's related to rotation).

Quoted 2 lines

Just a note about the paragraph about ORIENTATION I suggested on the previous version. If it was left out intentionally:

And didn't we discuss the fact that sensor drivers shouldn't flip the image internally to compensate for the rotation, but instead expose this to userspace ? That seems to be missing too.

Quoted 17 lines
Quoted 15 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation
+information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
+register the appropriate controls.
Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +1 -0
index daa4f40869f8..29fe22da52a2 100644
@@ -536,6 +536,7 @@ enum v4l2_scene_mode -
       - The camera is not directly attached to the device and is freely movable.
 
 
+.. _v4l2-camera-sensor-rotation:
 
 ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
     This read-only control describes the rotation correction in degrees in the
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#4 lore raw

Hi Laurent,

Quoted 47 lines · Laurent Pinchart

Hello,

Quoted 30 lines · Jacopo Mondi
Quoted 29 lines · Sakari Ailus

Document how rotation and orientation should be taken into account in writing camera sensor drivers.

---
since v1:

- Simplify language (Laurent's suggestion) and add note on flipping controls (Jacopo).

- Improve the last paragraph, say this is about rotation and orientation.

 Documentation/driver-api/media/camera-sensor.rst | 16 ++++++++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst |  1 +
 2 files changed, 17 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +5 -0
index c7d4891bd24e..61caa7901c51 100644
@@ -151,3 +151,19 @@ used to obtain device's power state after the power state transition:
 The function returns a non-zero value if it succeeded getting the power count or
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have the camera sensor mounted upside down compared to its natural
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst used to obtain device's power state after the power state transition: · line 166

Quoted 8 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
+mounting rotation. In such cases, drivers shall expose the information to
+userspace with the :ref:`V4L2_CID_CAMERA_SENSOR_ROTATION
+<v4l2-camera-sensor-rotation>` control.
+
+Sensor drivers that have any vertical or horizontal flips embedded in the
+register programming sequences shall initialize the V4L2_CID_HFLIP and
+V4L2_CID_VFLIP controls with the values programmed by the register sequences.
+

I would move this paragraph below the next one, to keep the two paragraphs related to the rotation and orientation together. You may also want to expand the section title to cover flipping, or add a new flipping section (although it's related to rotation).

Quoted 6 lines
Quoted 2 lines

Just a note about the paragraph about ORIENTATION I suggested on the previous version. If it was left out intentionally:

And didn't we discuss the fact that sensor drivers shouldn't flip the image internally to compensate for the rotation, but instead expose this to userspace ? That seems to be missing too.

I'll try to address these in v5.

Quoted 18 lines
Quoted 18 lines
Quoted 15 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+Use ``v4l2_fwnode_device_parse()`` to obtain rotation and orientation
+information from system firmware and ``v4l2_ctrl_new_fwnode_properties()`` to
+register the appropriate controls.
Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst +1 -0
index daa4f40869f8..29fe22da52a2 100644
@@ -536,6 +536,7 @@ enum v4l2_scene_mode -
       - The camera is not directly attached to the device and is freely movable.
 
 
+.. _v4l2-camera-sensor-rotation:
 
 ``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)``
     This read-only control describes the rotation correction in degrees in the
Signature · 3 lines
Regards,

Sakari Ailus