@@ -61,16 +61,28 @@
*
* * Media device:
*
- * A media device is represented by a struct &media_device instance, defined in
- * include/media/media-device.h. Allocation of the structure is handled by the
- * media device driver, usually by embedding the &media_device instance in a
- * larger driver-specific structure.
+ * A media device is represented by a struct &media_device instance,
+ * defined in include/media/media-device.h. The memory for a media
+ * device is allocated using media_device_alloc() function.
+ * media_device_alloc() may also be used to allocate extra memory for
+ * driver's purpose. media_device_priv() may be used to obtain a
+ * driver's private pointer related to a media device. The two are
+ * intended as alternatives, whichever serves the purpose better.
*
* Drivers register media device instances by calling
* __media_device_register() via the macro media_device_register()
* and unregistered by calling
* media_device_unregister().
*
+ * The media device structure itself is not reference counted, but it
+ * relies on the kref which is part of struct media_devnode which it
+ * embeds. Acquiring a reference to a media device requires calling
+ * media_device_get() on the media device, likewise releasing a
+ * reference is done using media_device_put(). Once the last reference
+ * is gone, the media device is released iff it was allocated using
+ * media_device_alloc(). The media device's release() callback is
+ * called once the last reference has been released.
+ *
* * Entities, pads and links:
*
* - Entities
@@ -419,6 +431,9 @@ static inline __must_check int media_entity_enum_init(
*
* @mdev: pointer to struct &media_device
*
+ * DEPRECATED --- use media_device_alloc() and rely on reference
+ * counts and the release callback instead.
+ *
* This function initializes the media device prior to its registration.
* The media device initialization and registration is split in two functions
* to avoid race conditions and make the media device available to user-space
@@ -489,6 +504,9 @@ static inline void *media_device_priv(struct media_device *mdev)
*
* @mdev: pointer to struct &media_device
*
+ * DEPRECATED --- use media_device_alloc() and rely on reference
+ * counts and the release callback instead.
+ *
* This function that will destroy the graph_mutex that is
* initialized in media_device_init().
*/
Document the addition of the media_device_alloc() function to allocate a media device. Also, document how reference counting and releasing a media device works. Deprecate API elements which are no longer needed with dynamically allocated media devices. Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> --- include/media/media-device.h | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-)