Re: [RFC PATCH 2/4] media: Add Media Device Allocator API documentation

[Mauro Carvalho Chehab]

Em Fri, 25 Mar 2016 22:38:43 -0600
Shuah Khan <shuahkh@xxxxxxxxxxxxxxx> escreveu:

> Add Media Device Allocator API documentation.

Please merge this with the previous patch.

> 
> 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


-- 
Thanks,
Mauro