Add Media Device Allocator API documentation. Signed-off-by: Shuah Khan <shuahkh@xxxxxxxxxxxxxxx> --- include/media/media-dev-allocator.h | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/include/media/media-dev-allocator.h b/include/media/media-dev-allocator.h index 2932c90..174840c 100644 --- a/include/media/media-dev-allocator.h +++ b/include/media/media-dev-allocator.h @@ -20,6 +20,38 @@ #ifdef CONFIG_MEDIA_CONTROLLER /** + * DOC: Media Controller Device Allocator API + * There are known problems with media device life time management. When media + * device is released while an media ioctl is in progress, ioctls fail with + * use-after-free errors and kernel hangs in some cases. + * + * Media Device can be in any the following states: + * + * - Allocated + * - Registered (could be tied to more than one driver) + * - Unregistered, not in use (media device file is not open) + * - Unregistered, in use (media device file is not open) + * - Released + * + * When media device belongs to more than one driver, registrations should be + * refcounted to avoid unregistering when one of the drivers does unregister. + * A refcount field in the struct media_device covers this case. Unregister on + * a Media Allocator media device is a kref_put() call. The media device should + * be unregistered only when the last unregister occurs. + * + * When a media device is in use when it is unregistered, it should not be + * released until the application exits when it detects the unregistered + * status. Media device that is in use when it is unregistered is moved to + * to_delete_list. When the last unregister occurs, media device is unregistered + * and becomes an unregistered, still allocated device. Unregister marks the + * device to be deleted. + * + * When media device belongs to more than one driver, as both drivers could be + * unbound/bound, driver should not end up getting stale media device that is + * on its way out. Moving the unregistered media device to to_delete_list helps + * this case as well. + */ +/** * media_device_get() - Allocate and return global media device * * @mdev -- 2.5.0 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
