Skip to contentSkip to conversation

Documentation: v4l: Document rotation and orientation for sensor drivers

PATCH Superseded Sakari Ailus 3 participants 6 messages Mar 28, 2023 – Apr 5, 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:

Use speclial double quotes around functions to use non-proportional font for them.

 Documentation/driver-api/media/camera-sensor.rst      | 11 +++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst      |  1 +
 2 files changed, 12 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +11 -0
index c7d4891bd24e..2618a91b0d85 100644
@@ -151,3 +151,14 @@ 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 been implemented so that the camera sensor has been mounted
+upside down compared to its natural mounting rotation. In such a case, the
+:ref:`V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation>` control
+shall indicate the mounting rotation.
+
+Use ``v4l2_fwnode_device_parse()`` to obtain this information and
+``v4l2_ctrl_new_fwnode_properties()`` to generate 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

Hi Sakari
sorry, I missed this one!

Quoted 20 lines · Sakari Ailus

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

---
since v1:

Use speclial double quotes around functions to use non-proportional font for them.

 Documentation/driver-api/media/camera-sensor.rst      | 11 +++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst      |  1 +
 2 files changed, 12 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index c7d4891bd24e..2618a91b0d85 100644
@@ -151,3 +151,14 @@ 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

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

Quoted 10 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have been implemented so that the camera sensor has been mounted
+upside down compared to its natural mounting rotation. In such a case, the
+:ref:`V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation>` control
+shall indicate the mounting rotation.

I would put it in imperative form for driver developers

"Some systems have been implemented so that the camera sensor has been mounted upside down compared to its natural mounting rotation. In such a case, drivers should register the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control to report the information to userspace."

I would also specify how drivers should initialize their flip controls

"Mode-based sensor driver implementations that have any vertical or horizontal flips embedded in the register programming sequences should initialize the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls with the values programmed by the register sequences.

Drivers which implement writable flip controls could automatically compensate for the sensor's mounting rotation and shall reflect that in the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls initial and default values."

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

Quoted 3 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+
+Use ``v4l2_fwnode_device_parse()`` to obtain this information and
+``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls.

I would also mention the orientation control before introducing v4l2_fwnode_device_parse.

"Sensor drivers should also report their mounting orientation with the :ref:V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>.

Both controls can be registered by using the ``v4l2_fwnode_device_parse()`` function to obtain this information from the firmware interface and ``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls."

How does this work for you ?

Quoted 15 lines
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

author maintainer
#2 lore raw

Hi Jacopo,

Quoted 2 lines · Jacopo Mondi

Hi Sakari
sorry, I missed this one!

No problem.

Quoted 35 lines · Sakari Ailus
Quoted 20 lines

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

---
since v1:

Use speclial double quotes around functions to use non-proportional font for them.

 Documentation/driver-api/media/camera-sensor.rst      | 11 +++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst      |  1 +
 2 files changed, 12 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index c7d4891bd24e..2618a91b0d85 100644
@@ -151,3 +151,14 @@ 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

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

Quoted 10 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have been implemented so that the camera sensor has been mounted
+upside down compared to its natural mounting rotation. In such a case, the
+:ref:`V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation>` control
+shall indicate the mounting rotation.

I would put it in imperative form for driver developers

Quoted 5 lines

"Some systems have been implemented so that the camera sensor has been mounted upside down compared to its natural mounting rotation. In such a case, drivers should register the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control to report the information to userspace."

That is in conditional, suggesting it isn't mandatory. Is that what you wanted to say?

Quoted 7 lines

I would also specify how drivers should initialize their flip controls

"Mode-based sensor driver implementations that have any vertical or horizontal flips embedded in the register programming sequences should initialize the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls with the values programmed by the register sequences.

I'd use "shall" also here. I can't think of a reasonable exception as it breaks how this is meant to work for user space.

Quoted 4 lines

Drivers which implement writable flip controls could automatically compensate for the sensor's mounting rotation and shall reflect that in the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls initial and default values."

Good point. For existing drivers (such as CCS or IMX258) this could help existing users but I'm not sure I'd do this for new drivers. Comments and opinions would be welcome from others, too. Cc Laurent, too.

Quoted 8 lines

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

Quoted 4 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+
+Use ``v4l2_fwnode_device_parse()`` to obtain this information and
+``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls.

I would also mention the orientation control before introducing v4l2_fwnode_device_parse.

Quoted 8 lines

"Sensor drivers should also report their mounting orientation with the :ref:V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>.

Both controls can be registered by using the ``v4l2_fwnode_device_parse()`` function to obtain this information from the firmware interface and ``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls."

How does this work for you ?

I'd just use "shall" here, too.

This applies of course to new drivers only, many existing ones are missing these bits.

Signature · 3 lines
Kind regards,

Sakari Ailus
#3 lore raw

Hello

Quoted 43 lines · Sakari Ailus

Hi Jacopo,

Quoted 2 lines · Jacopo Mondi

Hi Sakari
sorry, I missed this one!

No problem.

Quoted 35 lines · Sakari Ailus
Quoted 20 lines

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

---
since v1:

Use speclial double quotes around functions to use non-proportional font for them.

 Documentation/driver-api/media/camera-sensor.rst      | 11 +++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst      |  1 +
 2 files changed, 12 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index c7d4891bd24e..2618a91b0d85 100644
@@ -151,3 +151,14 @@ 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

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

Quoted 10 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have been implemented so that the camera sensor has been mounted
+upside down compared to its natural mounting rotation. In such a case, the
+:ref:`V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation>` control
+shall indicate the mounting rotation.

I would put it in imperative form for driver developers

Quoted 9 lines
Quoted 5 lines

"Some systems have been implemented so that the camera sensor has been mounted upside down compared to its natural mounting rotation. In such a case, drivers should register the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control to report the information to userspace."

That is in conditional, suggesting it isn't mandatory. Is that what you wanted to say?

"drivers shall register..." ?

Quoted 11 lines
Quoted 7 lines

I would also specify how drivers should initialize their flip controls

"Mode-based sensor driver implementations that have any vertical or horizontal flips embedded in the register programming sequences should initialize the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls with the values programmed by the register sequences.

I'd use "shall" also here. I can't think of a reasonable exception as it breaks how this is meant to work for user space.

Yes, I agree

Quoted 20 lines
Quoted 4 lines

Drivers which implement writable flip controls could automatically compensate for the sensor's mounting rotation and shall reflect that in the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls initial and default values."

Good point. For existing drivers (such as CCS or IMX258) this could help existing users but I'm not sure I'd do this for new drivers. Comments and opinions would be welcome from others, too. Cc Laurent, too.

Quoted 11 lines

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

Quoted 4 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+
+Use ``v4l2_fwnode_device_parse()`` to obtain this information and
+``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls.

I would also mention the orientation control before introducing v4l2_fwnode_device_parse.

"Sensor drivers should also report their mounting orientation with the :ref:V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>.

Quoted 8 lines
Quoted 5 lines

Both controls can be registered by using the ``v4l2_fwnode_device_parse()`` function to obtain this information from the firmware interface and ``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls."

How does this work for you ?

I'd just use "shall" here, too.

Agree on this as well

Quoted 3 lines

This applies of course to new drivers only, many existing ones are missing these bits.

I know :( It's however worth it to encourage new drivers to do that!

Quoted 4 lines

--
Kind regards,

Sakari Ailus

#4 lore raw

Hello,

Quoted 36 lines · Jacopo Mondi
Quoted 35 lines · Sakari Ailus
Quoted 34 lines · Jacopo Mondi
Quoted 20 lines · Sakari Ailus

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

---
since v1:

Use speclial double quotes around functions to use non-proportional font for them.

 Documentation/driver-api/media/camera-sensor.rst      | 11 +++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst      |  1 +
 2 files changed, 12 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index c7d4891bd24e..2618a91b0d85 100644
@@ -151,3 +151,14 @@ 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

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

Quoted 10 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have been implemented so that the camera sensor has been mounted
+upside down compared to its natural mounting rotation. In such a case, the
+:ref:`V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation>` control
+shall indicate the mounting rotation.

I would put it in imperative form for driver developers

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

"Some systems have been implemented so that the camera sensor has been mounted upside down compared to its natural mounting rotation. In such a case,

I'd simplify it further:

"Some systems have the camera sensor mounted upside down compared to its natural mounting rotation. In such cases, "

More words can add clarity, but when they don't, excess words should be removed :-)

Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

drivers should register the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control to report the information to userspace."

That is in conditional, suggesting it isn't mandatory. Is that what you wanted to say?

"drivers shall register..." ?

Sounds good, maybe with s/register/expose/. Or

"drivers shall expose the information to userspace with the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control."

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

I would also specify how drivers should initialize their flip controls

"Mode-based sensor driver implementations that have any vertical or

s/driver implementations/drivers/

(still chasing extraneous words)

Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

horizontal flips embedded in the register programming sequences should initialize the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls with the values programmed by the register sequences.

I'd use "shall" also here. I can't think of a reasonable exception as it breaks how this is meant to work for user space.

Yes, I agree

Agreed. I'd drop "Mode-based" though, I don't think that's relevant, other drivers may do something similar.

Quoted 7 lines
Quoted 7 lines
Quoted 3 lines

Drivers which implement writable flip controls could automatically compensate for the sensor's mounting rotation and shall reflect that in the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls initial and default values."

Good point. For existing drivers (such as CCS or IMX258) this could help existing users but I'm not sure I'd do this for new drivers. Comments and opinions would be welcome from others, too. Cc Laurent, too.

I wouldn't for new drivers, no, and even for IMX258 and CCS, I'm tempted to not keep that backward compatibility. We need to assess whether or not it would cause breakages in practice, if the risk is very low, I'd favour consistency. This is especially the case for CCS.

Quoted 24 lines
Quoted 10 lines
Quoted 10 lines

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

Quoted 3 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+
+Use ``v4l2_fwnode_device_parse()`` to obtain this information and
+``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls.

I would also mention the orientation control before introducing v4l2_fwnode_device_parse.

"Sensor drivers should also report their mounting orientation with the :ref:V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>.

Quoted 7 lines
Quoted 5 lines

Both controls can be registered by using the ``v4l2_fwnode_device_parse()`` function to obtain this information from the firmware interface and ``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls."

How does this work for you ?

I'd just use "shall" here, too.

Agree on this as well

Quoted 2 lines

This applies of course to new drivers only, many existing ones are missing these bits.

I know :( It's however worth it to encourage new drivers to do that!

Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#5 lore raw

Hi Laurent,

Quoted 42 lines · Laurent Pinchart

Hello,

Quoted 36 lines · Jacopo Mondi
Quoted 35 lines · Sakari Ailus
Quoted 34 lines · Jacopo Mondi
Quoted 20 lines · Sakari Ailus

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

---
since v1:

Use speclial double quotes around functions to use non-proportional font for them.

 Documentation/driver-api/media/camera-sensor.rst      | 11 +++++++++++
 .../userspace-api/media/v4l/ext-ctrls-camera.rst      |  1 +
 2 files changed, 12 insertions(+)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index c7d4891bd24e..2618a91b0d85 100644
@@ -151,3 +151,14 @@ 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

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

Quoted 10 lines
Documentation/driver-api/media/camera-sensor.rst +8 -0
 runtime PM was disabled, in either of which cases the driver may proceed to
 access the device.
+
+Rotation and orientation
+------------------------
+
+Some systems have been implemented so that the camera sensor has been mounted
+upside down compared to its natural mounting rotation. In such a case, the
+:ref:`V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation>` control
+shall indicate the mounting rotation.

I would put it in imperative form for driver developers

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

"Some systems have been implemented so that the camera sensor has been mounted upside down compared to its natural mounting rotation. In such a case,

Quoted 7 lines

I'd simplify it further:

"Some systems have the camera sensor mounted upside down compared to its natural mounting rotation. In such cases, "

More words can add clarity, but when they don't, excess words should be removed :-)

Works for me.

Quoted 28 lines
Quoted 9 lines
Quoted 7 lines
Quoted 4 lines

drivers should register the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control to report the information to userspace."

That is in conditional, suggesting it isn't mandatory. Is that what you wanted to say?

"drivers shall register..." ?

Sounds good, maybe with s/register/expose/. Or

"drivers shall expose the information to userspace with the :ref:V4L2_CID_CAMERA_SENSOR_ROTATION <v4l2-camera-sensor-rotation> control."

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

I would also specify how drivers should initialize their flip controls

"Mode-based sensor driver implementations that have any vertical or

s/driver implementations/drivers/

(still chasing extraneous words)

Quoted 4 lines
Quoted 4 lines
Quoted 3 lines

horizontal flips embedded in the register programming sequences should initialize the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls with the values programmed by the register sequences.

Quoted 7 lines
Quoted 4 lines
Quoted 2 lines

I'd use "shall" also here. I can't think of a reasonable exception as it breaks how this is meant to work for user space.

Yes, I agree

Agreed. I'd drop "Mode-based" though, I don't think that's relevant, other drivers may do something similar.

I'll change these for v3.

Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines

Drivers which implement writable flip controls could automatically compensate for the sensor's mounting rotation and shall reflect that in the V4L2_CID_HFLIP and V4L2_CID_VFLIP controls initial and default values."

Quoted 8 lines
Quoted 3 lines
Quoted 3 lines

Good point. For existing drivers (such as CCS or IMX258) this could help existing users but I'm not sure I'd do this for new drivers. Comments and opinions would be welcome from others, too. Cc Laurent, too.

I wouldn't for new drivers, no, and even for IMX258 and CCS, I'm tempted to not keep that backward compatibility. We need to assess whether or not it would cause breakages in practice, if the risk is very low, I'd favour consistency. This is especially the case for CCS.

I've actually already posted patches doing just this for CCS.

Quoted 26 lines
Quoted 25 lines
Quoted 11 lines
Quoted 11 lines

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

Quoted 4 lines
Documentation/driver-api/media/camera-sensor.rst +3 -0
+
+Use ``v4l2_fwnode_device_parse()`` to obtain this information and
+``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls.

I would also mention the orientation control before introducing v4l2_fwnode_device_parse.

"Sensor drivers should also report their mounting orientation with the :ref:V4L2_CID_CAMERA_SENSOR_ORIENTATION <v4l2-camera-sensor-orientation>.

Quoted 7 lines
Quoted 5 lines

Both controls can be registered by using the ``v4l2_fwnode_device_parse()`` function to obtain this information from the firmware interface and ``v4l2_ctrl_new_fwnode_properties()`` to generate the appropriate controls."

How does this work for you ?

I'd just use "shall" here, too.

Agree on this as well

Quoted 2 lines

This applies of course to new drivers only, many existing ones are missing these bits.

I know :( It's however worth it to encourage new drivers to do that!

Signature · 3 lines
Regards,

Sakari Ailus