[PATCH 5/6] drm: Document deprecated load/unload hook

[Daniel Vetter]

On Wed, Dec 28, 2016 at 12:32:15PM -0200, Gabriel Krisman Bertazi wrote:
> Signed-off-by: Gabriel Krisman Bertazi <krisman at collabora.co.uk>
> ---
>  include/drm/drm_drv.h | 30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
> index c4fc49583dc0..0c8e4e979870 100644
> --- a/include/drm/drm_drv.h
> +++ b/include/drm/drm_drv.h
> @@ -64,12 +64,42 @@ struct drm_mode_create_dumb;
>   * structure for GEM drivers.
>   */
>  struct drm_driver {
> +
> +	/**
> +	 * @load:
> +	 *
> +	 * Backward-compatible driver callback to complete
> +	 * initialization steps after the driver is registered.  For
> +	 * this reason, may suffer from race conditions and its use is
> +	 * dicouraged for new drivers.  It is therefore only supported

s/discouraged/deprecated/ ... need some stronger wording here.

> +	 * for existing drivers not yet converted to the new scheme.

I think a link to the new scheme would be good, maybe:

"See drm_dev_init() and drm_dev_register() for proper and race-free way to
set up a &drm_device."

Unload is also deprecated, so similar comments apply for that.
-Daniel

> +	 *
> +	 * Returns:
> +	 * Zero on success, non-zero value on failure.
> +	 */
>  	int (*load) (struct drm_device *, unsigned long flags);
>  	int (*firstopen) (struct drm_device *);
>  	int (*open) (struct drm_device *, struct drm_file *);
>  	void (*preclose) (struct drm_device *, struct drm_file *file_priv);
>  	void (*postclose) (struct drm_device *, struct drm_file *);
>  	void (*lastclose) (struct drm_device *);
> +
> +	/**
> +	 * @unload:
> +	 *
> +	 * Reverse the effects of the driver load callback.  Ideally,
> +	 * the clean up performed by the driver should happen in the
> +	 * reverse order of the initialization.  Similarly to the load
> +	 * hook, this handler is deprecated and its usage should be
> +	 * dropped in favor of an open-coded teardown function at the
> +	 * driver layer.
> +	 *
> +	 * The unload() hook is called immediately after unregistering
> +	 * the device.
> +	 *
> +	 * Returns:
> +	 * The return value is ignored.
> +	 */
>  	int (*unload) (struct drm_device *);
>  	int (*dma_ioctl) (struct drm_device *dev, void *data, struct drm_file *file_priv);
>  	int (*dma_quiescent) (struct drm_device *);
> -- 
> 2.11.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch