Skip to contentSkip to conversation

media: Documentation: Initialisation finishes before subdev registration

PATCH Superseded Sakari Ailus 2 participants 7 messages Nov 1, 2023 – Nov 2, 2023

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Sakari Ailus

author maintainer
#0 lore raw

PATCH 1/1 media: Documentation: Initialisation finishes before subdev registration

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +2 -1
index 6456145f96ed..c675ce77c4d6 100644
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
+be enabled before registering the sensor's async sub-device.
 
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +4 -0
index e56b50b3f203..b22d1b075fd6 100644
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.
+
 Asynchronous sub-device notifiers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Signature · 1 line
2.39.2
#1 lore raw

Hi Sakari,

Thank you for the patch.

Quoted 15 lines · Sakari Ailus

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index 6456145f96ed..c675ce77c4d6 100644

Documentation/driver-api/media/camera-sensor.rst management over the pipeline. · line 64

Quoted 6 lines
Documentation/driver-api/media/camera-sensor.rst +2 -1
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
+be enabled before registering the sensor's async sub-device.

I wouldn't single out runtime PM initialization here, and neither would I talk about registration, as that's not in scope for this file. I think it would be better to instead reference v4l2-subdev.rst at the beginning of this file. Something generic like stating that camera sensor must be implemented as subdevs, and comply with the generic rules for subdevs, as explaiend in v4l2-subdev.rst.

Quoted 8 lines
Documentation/driver-api/media/camera-sensor.rst +0 -0
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +0 -0
index e56b50b3f203..b22d1b075fd6 100644

Documentation/driver-api/media/v4l2-subdev.rst performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices · line 200

Quoted 6 lines
Documentation/driver-api/media/v4l2-subdev.rst +3 -0
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.

It's not just the UAPI, but also in-kernel users.

The passive form is heavier and thus harder to read. Maybe something like the following ? Feel free to rework it.

----
Drivers must complete all initialization of the sensor before registering the async sub-device. This includes enabling runtime PM. This is because the sensor becomes accessible and may be used as soon as it gets registered.
----

Also, wouldn't this be better placed in the "Registering asynchronous sub-devices" section ? This isn't specific to sensors.

Quoted 4 lines
Documentation/driver-api/media/v4l2-subdev.rst +1 -0
+
 Asynchronous sub-device notifiers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#2 lore raw

Hi Laurent,

Quoted 3 lines · Laurent Pinchart

Hi Sakari,

Thank you for the patch.

Thank you for the review.

Quoted 22 lines · Sakari Ailus
Quoted 20 lines

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +1 -1
index 6456145f96ed..c675ce77c4d6 100644
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst management over the pipeline. · line 64

Quoted 1 line
Documentation/driver-api/media/camera-sensor.rst +1 -0
+be enabled before registering the sensor's async sub-device.

I wouldn't single out runtime PM initialization here, and neither would I talk about registration, as that's not in scope for this file. I think it would be better to instead reference v4l2-subdev.rst at the beginning of this file. Something generic like stating that camera sensor must be implemented as subdevs, and comply with the generic rules for subdevs, as explaiend in v4l2-subdev.rst.

I added this text here as this appears to be a very common problem in sensor drivers. Tost likely the reason is that some drivers have had this issue and it has gotten copied elsewhere.

Quoted 18 lines
Quoted 9 lines
Documentation/driver-api/media/camera-sensor.rst +0 -0
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +0 -0
index e56b50b3f203..b22d1b075fd6 100644

Documentation/driver-api/media/v4l2-subdev.rst performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices · line 200

Quoted 6 lines
Documentation/driver-api/media/v4l2-subdev.rst +3 -0
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.

It's not just the UAPI, but also in-kernel users.

Quoted 7 lines

The passive form is heavier and thus harder to read. Maybe something like the following ? Feel free to rework it.

----
Drivers must complete all initialization of the sensor before registering the async sub-device. This includes enabling runtime PM. This is because the sensor becomes accessible and may be used as soon as it gets registered.

s/used/accessed/ maybe? Or remove "and maybe used"?

Quoted 4 lines

----

Also, wouldn't this be better placed in the "Registering asynchronous sub-devices" section ? This isn't specific to sensors.

Ah, yes, I meant sub-devices there. This actually applies to all of UAPI, in general, but it's the async sub-device drivers that tend to have the problem as people tend to think it's "just" registering the async sub-device but in fact the related sub-device may be immediately registered as well.

Quoted 6 lines
Quoted 5 lines
Documentation/driver-api/media/v4l2-subdev.rst +1 -0
+
 Asynchronous sub-device notifiers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Signature · 3 lines
Regards,

Sakari Ailus
#3 lore raw

Hi Sakari,

Quoted 31 lines · Sakari Ailus
Quoted 21 lines · Laurent Pinchart
Quoted 20 lines · Sakari Ailus

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +1 -1
index 6456145f96ed..c675ce77c4d6 100644
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst management over the pipeline. · line 64

Quoted 1 line
Documentation/driver-api/media/camera-sensor.rst +1 -0
+be enabled before registering the sensor's async sub-device.

I wouldn't single out runtime PM initialization here, and neither would I talk about registration, as that's not in scope for this file. I think it would be better to instead reference v4l2-subdev.rst at the beginning of this file. Something generic like stating that camera sensor must be implemented as subdevs, and comply with the generic rules for subdevs, as explaiend in v4l2-subdev.rst.

Quoted 3 lines

I added this text here as this appears to be a very common problem in sensor drivers. Tost likely the reason is that some drivers have had this issue and it has gotten copied elsewhere.

Yes, I think there's lots of cargo cult there. Documentation is good, fixing drivers so that the next person to copy code will copy good code is better, but the best solution is to move most of the problem to helper functions provided by the core.

I still prefer linking to v4l2-subdev.rst. Duplicating documentation in multiple places increases the chances it will get stale.

Quoted 19 lines
Quoted 19 lines

Documentation/driver-api/media/v4l2-subdev.rst performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices · line 200

Quoted 13 lines
Documentation/driver-api/media/camera-sensor.rst +0 -0
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +3 -0
index e56b50b3f203..b22d1b075fd6 100644
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.

It's not just the UAPI, but also in-kernel users.

The passive form is heavier and thus harder to read. Maybe something like the following ? Feel free to rework it.

Quoted 6 lines
Quoted 4 lines

----
Drivers must complete all initialization of the sensor before registering the async sub-device. This includes enabling runtime PM. This is because the sensor becomes accessible and may be used as soon as it gets registered.

s/used/accessed/ maybe? Or remove "and maybe used"?

I'm fine with that.

Quoted 10 lines
Quoted 4 lines

----

Also, wouldn't this be better placed in the "Registering asynchronous sub-devices" section ? This isn't specific to sensors.

Ah, yes, I meant sub-devices there. This actually applies to all of UAPI, in general, but it's the async sub-device drivers that tend to have the problem as people tend to think it's "just" registering the async sub-device but in fact the related sub-device may be immediately registered as well.

Note there are two sections, one about subdev registration, one about camera sensor registration. You've added the text to the latter.

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/driver-api/media/v4l2-subdev.rst +1 -0
+
 Asynchronous sub-device notifiers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#4 lore raw

Hi Laurent,

Quoted 34 lines · Laurent Pinchart

Hi Sakari,

Quoted 31 lines · Sakari Ailus
Quoted 29 lines · Laurent Pinchart
Quoted 15 lines · Sakari Ailus

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +0 -0
index 6456145f96ed..c675ce77c4d6 100644

Documentation/driver-api/media/camera-sensor.rst management over the pipeline. · line 64

Quoted 6 lines
Documentation/driver-api/media/camera-sensor.rst +2 -1
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
+be enabled before registering the sensor's async sub-device.

I wouldn't single out runtime PM initialization here, and neither would I talk about registration, as that's not in scope for this file. I think it would be better to instead reference v4l2-subdev.rst at the beginning of this file. Something generic like stating that camera sensor must be implemented as subdevs, and comply with the generic rules for subdevs, as explaiend in v4l2-subdev.rst.

Quoted 8 lines
Quoted 3 lines

I added this text here as this appears to be a very common problem in sensor drivers. Tost likely the reason is that some drivers have had this issue and it has gotten copied elsewhere.

Yes, I think there's lots of cargo cult there. Documentation is good, fixing drivers so that the next person to copy code will copy good code is better, but the best solution is to move most of the problem to helper functions provided by the core.

I wouldn't call it "cargo cult" if a sensor driver needs to deal with multiple unrelated matters. Of course it's possible to have helper functions performing multiple unrelated things but at some point it is easy to notice some drivers need things to be done differently. Admittedly, most of such differences are due to historical reasons, not something you want in new drivers anymore.

Quoted 3 lines

I still prefer linking to v4l2-subdev.rst. Duplicating documentation in multiple places increases the chances it will get stale.

I'm fine with dropping this part of the patch. Although what is being said there is very unlikely to change in the foreseeable future.

Quoted 34 lines
Quoted 20 lines
Quoted 20 lines
Quoted 8 lines
Documentation/driver-api/media/camera-sensor.rst +0 -0
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +0 -0
index e56b50b3f203..b22d1b075fd6 100644

Documentation/driver-api/media/v4l2-subdev.rst performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices · line 200

Quoted 6 lines
Documentation/driver-api/media/v4l2-subdev.rst +3 -0
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.

It's not just the UAPI, but also in-kernel users.

The passive form is heavier and thus harder to read. Maybe something like the following ? Feel free to rework it.

Quoted 6 lines
Quoted 4 lines

----
Drivers must complete all initialization of the sensor before registering the async sub-device. This includes enabling runtime PM. This is because the sensor becomes accessible and may be used as soon as it gets registered.

s/used/accessed/ maybe? Or remove "and maybe used"?

I'm fine with that.

Quoted 5 lines
Quoted 4 lines

----

Also, wouldn't this be better placed in the "Registering asynchronous sub-devices" section ? This isn't specific to sensors.

Quoted 8 lines
Quoted 5 lines

Ah, yes, I meant sub-devices there. This actually applies to all of UAPI, in general, but it's the async sub-device drivers that tend to have the problem as people tend to think it's "just" registering the async sub-device but in fact the related sub-device may be immediately registered as well.

Note there are two sections, one about subdev registration, one about camera sensor registration. You've added the text to the latter.

The section I added the text to does not mention camera sensors separately, the section title is "Registering asynchronous sub-devices".

Quoted 6 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Documentation/driver-api/media/v4l2-subdev.rst +1 -0
+
 Asynchronous sub-device notifiers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Signature · 3 lines
Regards,

Sakari Ailus
#5 lore raw
Quoted 37 lines · Sakari Ailus
Quoted 36 lines · Laurent Pinchart
Quoted 34 lines · Sakari Ailus
Quoted 21 lines · Laurent Pinchart
Quoted 20 lines · Sakari Ailus

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +1 -1
index 6456145f96ed..c675ce77c4d6 100644
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst management over the pipeline. · line 64

Quoted 1 line
Documentation/driver-api/media/camera-sensor.rst +1 -0
+be enabled before registering the sensor's async sub-device.

I wouldn't single out runtime PM initialization here, and neither would I talk about registration, as that's not in scope for this file. I think it would be better to instead reference v4l2-subdev.rst at the beginning of this file. Something generic like stating that camera sensor must be implemented as subdevs, and comply with the generic rules for subdevs, as explaiend in v4l2-subdev.rst.

I added this text here as this appears to be a very common problem in sensor drivers. Tost likely the reason is that some drivers have had this issue and it has gotten copied elsewhere.

Quoted 7 lines
Quoted 4 lines

Yes, I think there's lots of cargo cult there. Documentation is good, fixing drivers so that the next person to copy code will copy good code is better, but the best solution is to move most of the problem to helper functions provided by the core.

I wouldn't call it "cargo cult" if a sensor driver needs to deal with multiple unrelated matters.

I meant that most sensor drivers are written by copying code from other drivers without understanding what that code does exactly, and why.

Quoted 5 lines

Of course it's possible to have helper
functions performing multiple unrelated things but at some point it is easy to notice some drivers need things to be done differently. Admittedly, most of such differences are due to historical reasons, not something you want in new drivers anymore.

It's time to relegate historical code to the git history :-)

Quoted 5 lines
Quoted 2 lines

I still prefer linking to v4l2-subdev.rst. Duplicating documentation in multiple places increases the chances it will get stale.

I'm fine with dropping this part of the patch. Although what is being said there is very unlikely to change in the foreseeable future.

Would you add a link to v4l2-subdev.rst at the top of the file ? It can be done in a separate patch.

Quoted 39 lines
Quoted 39 lines
Quoted 19 lines
Quoted 19 lines

Documentation/driver-api/media/v4l2-subdev.rst performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices · line 200

Quoted 13 lines
Documentation/driver-api/media/camera-sensor.rst +0 -0
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +3 -0
index e56b50b3f203..b22d1b075fd6 100644
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.

It's not just the UAPI, but also in-kernel users.

The passive form is heavier and thus harder to read. Maybe something like the following ? Feel free to rework it.

Quoted 6 lines
Quoted 4 lines

----
Drivers must complete all initialization of the sensor before registering the async sub-device. This includes enabling runtime PM. This is because the sensor becomes accessible and may be used as soon as it gets registered.

s/used/accessed/ maybe? Or remove "and maybe used"?

I'm fine with that.

Quoted 10 lines
Quoted 4 lines

----

Also, wouldn't this be better placed in the "Registering asynchronous sub-devices" section ? This isn't specific to sensors.

Ah, yes, I meant sub-devices there. This actually applies to all of UAPI, in general, but it's the async sub-device drivers that tend to have the problem as people tend to think it's "just" registering the async sub-device but in fact the related sub-device may be immediately registered as well.

Quoted 5 lines
Quoted 2 lines

Note there are two sections, one about subdev registration, one about camera sensor registration. You've added the text to the latter.

The section I added the text to does not mention camera sensors separately, the section title is "Registering asynchronous sub-devices".

My bad, I was looking at the wrong location. Replacing the reference to sensor with subdev should be good enough then.

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Documentation/driver-api/media/v4l2-subdev.rst +1 -0
+
 Asynchronous sub-device notifiers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#6 lore raw
Quoted 43 lines · Laurent Pinchart
Quoted 42 lines · Sakari Ailus
Quoted 40 lines · Laurent Pinchart
Quoted 31 lines · Sakari Ailus
Quoted 21 lines · Laurent Pinchart
Quoted 20 lines · Sakari Ailus

Document that sub-device initialisation needs to complete before the async sub-device is registered as there is no further driver action needed before the sensor becomes accessible via the UAPI.

---
 Documentation/driver-api/media/camera-sensor.rst | 3 ++-
 Documentation/driver-api/media/v4l2-subdev.rst   | 4 ++++
 2 files changed, 6 insertions(+), 1 deletion(-)
Documentation/driver-api/media/camera-sensor.rst +1 -1
index 6456145f96ed..c675ce77c4d6 100644
@@ -60,7 +60,8 @@ management over the pipeline.
 Camera sensor drivers are responsible for controlling the power state of the
 device they otherwise control as well. They shall use runtime PM to manage
 power states. Runtime PM shall be enabled at probe time and disabled at remove
-time. Drivers should enable runtime PM autosuspend.
+time. Drivers should enable runtime PM autosuspend. Note that runtime PM has to
Quoted 8 lines

Documentation/driver-api/media/camera-sensor.rst management over the pipeline. · line 64

Quoted 1 line
Documentation/driver-api/media/camera-sensor.rst +1 -0
+be enabled before registering the sensor's async sub-device.

I wouldn't single out runtime PM initialization here, and neither would I talk about registration, as that's not in scope for this file. I think it would be better to instead reference v4l2-subdev.rst at the beginning of this file. Something generic like stating that camera sensor must be implemented as subdevs, and comply with the generic rules for subdevs, as explaiend in v4l2-subdev.rst.

Quoted 3 lines

I added this text here as this appears to be a very common problem in sensor drivers. Tost likely the reason is that some drivers have had this issue and it has gotten copied elsewhere.

Yes, I think there's lots of cargo cult there. Documentation is good, fixing drivers so that the next person to copy code will copy good code is better, but the best solution is to move most of the problem to helper functions provided by the core.

Quoted 5 lines
Quoted 2 lines

I wouldn't call it "cargo cult" if a sensor driver needs to deal with multiple unrelated matters.

I meant that most sensor drivers are written by copying code from other drivers without understanding what that code does exactly, and why.

That certainly does happen, too...

Quoted 9 lines
Quoted 6 lines

Of course it's possible to have helper
functions performing multiple unrelated things but at some point it is easy to notice some drivers need things to be done differently. Admittedly, most of such differences are due to historical reasons, not something you want in new drivers anymore.

It's time to relegate historical code to the git history :-)

Quoted 8 lines
Quoted 5 lines
Quoted 2 lines

I still prefer linking to v4l2-subdev.rst. Duplicating documentation in multiple places increases the chances it will get stale.

I'm fine with dropping this part of the patch. Although what is being said there is very unlikely to change in the foreseeable future.

Would you add a link to v4l2-subdev.rst at the top of the file ? It can be done in a separate patch.

I'll add that in v2.

Quoted 40 lines
Quoted 40 lines
Quoted 40 lines
Quoted 20 lines
Quoted 20 lines
Quoted 8 lines
Documentation/driver-api/media/camera-sensor.rst +0 -0
 The runtime PM handlers shall handle clocks, regulators, GPIOs, and other
 system resources required to power the sensor up and down. For drivers that
Documentation/driver-api/media/v4l2-subdev.rst +0 -0
index e56b50b3f203..b22d1b075fd6 100644

Documentation/driver-api/media/v4l2-subdev.rst performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices · line 200

Quoted 6 lines
Documentation/driver-api/media/v4l2-subdev.rst +3 -0
@@ -195,6 +195,10 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
 registered this way are stored in a global list of subdevices, ready to be
 picked up by bridge drivers.
 
+Note that all sensor initialisation has to complete before registering the async
+sub-device, including enabling runtime PM. This is because the sensor becomes
+accessible via the UAPI without further action by the sensor driver.

It's not just the UAPI, but also in-kernel users.

The passive form is heavier and thus harder to read. Maybe something like the following ? Feel free to rework it.

Quoted 6 lines
Quoted 4 lines

----
Drivers must complete all initialization of the sensor before registering the async sub-device. This includes enabling runtime PM. This is because the sensor becomes accessible and may be used as soon as it gets registered.

s/used/accessed/ maybe? Or remove "and maybe used"?

I'm fine with that.

Quoted 10 lines
Quoted 4 lines

----

Also, wouldn't this be better placed in the "Registering asynchronous sub-devices" section ? This isn't specific to sensors.

Ah, yes, I meant sub-devices there. This actually applies to all of UAPI, in general, but it's the async sub-device drivers that tend to have the problem as people tend to think it's "just" registering the async sub-device but in fact the related sub-device may be immediately registered as well.

Quoted 8 lines
Quoted 5 lines
Quoted 2 lines

Note there are two sections, one about subdev registration, one about camera sensor registration. You've added the text to the latter.

The section I added the text to does not mention camera sensors separately, the section title is "Registering asynchronous sub-devices".

My bad, I was looking at the wrong location. Replacing the reference to sensor with subdev should be good enough then.

Good that we agree. :-)

I'll use this as the original sentence, after replacing sensor with sub-device, made an unintended difference between the sub-device and teh async sub-device:

Drivers must complete all initialization of the sub-device before registering it using :c:func:v4l2_async_register_subdev, including enabling runtime PM. This is because the sub-device becomes accessible as soon as it gets registered.

Signature · 3 lines
Regards,

Sakari Ailus