Skip to contentSkip to conversation

media: Documentation: mc: Add media_device_{init,cleanup}

PATCH In review Sakari Ailus 2 participants 3 messages Mar 9, 2022 – Apr 29, 2022 Media (V4L/DVB)

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 media: Documentation: mc: Add media_device_{init,cleanup}

Document that drivers must first initialise a media device before registering it, and clean up once the media device is unregistered.

---
 Documentation/driver-api/media/mc-core.rst | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)
Documentation/driver-api/media/mc-core.rst +10 -3
index 57b5bbba944e..02481a2513b9 100644
@@ -42,9 +42,16 @@ Allocation of the structure is handled by the media device driver, usually by
 embedding the :c:type:`media_device` instance in a larger driver-specific
 structure.
 
-Drivers register media device instances by calling
-:c:func:`__media_device_register()` via the macro ``media_device_register()``
-and unregistered by calling :c:func:`media_device_unregister()`.
+Drivers initialise media device instances by calling
+:c:func:`media_device_init()`. After initialising a media device instance, it is
+registered by calling :c:func:`__media_device_register()` via the macro
+``media_device_register()`` and unregistered by calling
+:c:func:`media_device_unregister()`. An initialised media device must be
+eventually cleaned up by calling :c:func:`media_device_cleanup()`.
+
+Note that it is not allowed to unregister a media device instance that was not
+previously registered, or clean up a media device instance that was not
+previously initialised.
 
 Entities
 ^^^^^^^^
Signature · 1 line
2.30.2
Reviewed-by on v1 1/1
#1 lore raw

Hi Sakari,

Thank you for the patch.

Quoted 19 lines · Sakari Ailus

Document that drivers must first initialise a media device before registering it, and clean up once the media device is unregistered.

---
 Documentation/driver-api/media/mc-core.rst | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)
Documentation/driver-api/media/mc-core.rst +0 -3
index 57b5bbba944e..02481a2513b9 100644
@@ -42,9 +42,16 @@ Allocation of the structure is handled by the media device driver, usually by
 embedding the :c:type:`media_device` instance in a larger driver-specific
 structure.
 
-Drivers register media device instances by calling
-:c:func:`__media_device_register()` via the macro ``media_device_register()``
-and unregistered by calling :c:func:`media_device_unregister()`.

Documentation/driver-api/media/mc-core.rst Allocation of the structure is handled by the media device driver, usually by · line 54

Quoted 10 lines
Documentation/driver-api/media/mc-core.rst +10 -0
+Drivers initialise media device instances by calling
+:c:func:`media_device_init()`. After initialising a media device instance, it is
+registered by calling :c:func:`__media_device_register()` via the macro
+``media_device_register()`` and unregistered by calling
+:c:func:`media_device_unregister()`. An initialised media device must be
+eventually cleaned up by calling :c:func:`media_device_cleanup()`.
+
+Note that it is not allowed to unregister a media device instance that was not
+previously registered, or clean up a media device instance that was not
+previously initialised.

Could we fix this, to simplify drivers ? This patch is fine as it documents the current behaviour, so

but it will need to be updated. Bonus points if the update can go in a v2 ;-)

Quoted 2 lines
Documentation/driver-api/media/mc-core.rst +0 -0
 Entities
 ^^^^^^^^
Signature · 3 lines
Regards,

Laurent Pinchart
#2 lore raw

Hi Laurent,

Quoted 21 lines · Laurent Pinchart

Hi Sakari,

Thank you for the patch.

Quoted 16 lines · Sakari Ailus

Document that drivers must first initialise a media device before registering it, and clean up once the media device is unregistered.

---
 Documentation/driver-api/media/mc-core.rst | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)
Documentation/driver-api/media/mc-core.rst +0 -0
index 57b5bbba944e..02481a2513b9 100644
@@ -42,9 +42,16 @@ Allocation of the structure is handled by the media device driver, usually by
 embedding the :c:type:`media_device` instance in a larger driver-specific
 structure.
 
Quoted 15 lines

Documentation/driver-api/media/mc-core.rst Allocation of the structure is handled by the media device driver, usually by · line 54

Quoted 13 lines
Documentation/driver-api/media/mc-core.rst +10 -3
-Drivers register media device instances by calling
-:c:func:`__media_device_register()` via the macro ``media_device_register()``
-and unregistered by calling :c:func:`media_device_unregister()`.
+Drivers initialise media device instances by calling
+:c:func:`media_device_init()`. After initialising a media device instance, it is
+registered by calling :c:func:`__media_device_register()` via the macro
+``media_device_register()`` and unregistered by calling
+:c:func:`media_device_unregister()`. An initialised media device must be
+eventually cleaned up by calling :c:func:`media_device_cleanup()`.
+
+Note that it is not allowed to unregister a media device instance that was not
+previously registered, or clean up a media device instance that was not
+previously initialised.

Could we fix this, to simplify drivers ? This patch is fine as it

I think this could be thought with object lifetime.

Quoted 3 lines

documents the current behaviour, so

Thanks!

Signature · 1 line
Sakari Ailus