[PATCH] drm/doc: document recommended component helper usage

[PATCH] drm/doc: document recommended component helper usage

[Daniel Vetter]

Now that component has docs it's worth spending a few words and
hyperlinks on recommended best practices in drm.

v2: Add another item that component shouldn't be preferred over
drm_bridge/panel and similar subsystems already providing specialized
support for specific components (Laurent). Also convert to bullet
list.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Russell King - ARM Linux admin <linux@armlinux.org.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/driver-api/component.rst |  2 ++
 Documentation/gpu/drm-internals.rst    |  5 +++++
 drivers/gpu/drm/drm_drv.c              | 25 +++++++++++++++++++++++++
 3 files changed, 32 insertions(+)

diff --git a/Documentation/driver-api/component.rst b/Documentation/driver-api/component.rst
index 2da4a8f20607..57e37590733f 100644
--- a/Documentation/driver-api/component.rst
+++ b/Documentation/driver-api/component.rst
@@ -1,3 +1,5 @@
+.. _component:
+
 ======================================
 Component Helper for Aggregate Drivers
 ======================================
diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
index 3ae23a5454ac..966bd2d9f0cc 100644
--- a/Documentation/gpu/drm-internals.rst
+++ b/Documentation/gpu/drm-internals.rst
@@ -93,6 +93,11 @@ Device Instance and Driver Handling
 Driver Load
 -----------
 
+Component Helper Usage
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/gpu/drm/drm_drv.c
+   :doc: component helper usage recommendations
 
 IRQ Helper Library
 ~~~~~~~~~~~~~~~~~~
diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
index 4f70cf68112f..43825a888e67 100644
--- a/drivers/gpu/drm/drm_drv.c
+++ b/drivers/gpu/drm/drm_drv.c
@@ -456,6 +456,31 @@ static void drm_fs_inode_free(struct inode *inode)
 	}
 }
 
+/**
+ * DOC: component helper usage recommendations
+ *
+ * DRM drivers that drive hardware where a logical device consists of a pile of
+ * independent hardware blocks are recommended to use the :ref:`component helper
+ * library<component>`. For consistency and better options for code reuse the
+ * following guidelines apply:
+ *
+ *  - The entire device initialization procedure should be run from the
+ *    &component_master_ops.master_bind callback, starting with drm_dev_init(),
+ *    then binding all components with component_bind_all() and finishing with
+ *    drm_dev_register().
+ *
+ *  - The opaque pointer passed to all components through component_bind_all()
+ *    should point at &struct drm_device of the device instance, not some driver
+ *    specific private structure.
+ *
+ *  - The component helper fills the niche where further standardization of
+ *    interfaces is not practical. When there already is, or will be, a
+ *    standardized interface like &drm_bridge or &drm_panel, providing its own
+ *    functions to find such components at driver load time, like
+ *    drm_of_find_panel_or_bridge(), then the component helper should not be
+ *    used.
+ */
+
 /**
  * drm_dev_init - Initialise new DRM device
  * @dev: DRM device
-- 
2.20.1

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH] drm/doc: document recommended component helper usage

[Daniel Vetter]

On Tue, Feb 12, 2019 at 05:46:15PM +0100, Daniel Vetter wrote:
> Now that component has docs it's worth spending a few words and
> hyperlinks on recommended best practices in drm.
> 
> v2: Add another item that component shouldn't be preferred over
> drm_bridge/panel and similar subsystems already providing specialized
> support for specific components (Laurent). Also convert to bullet
> list.
> 
> Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Cc: Russell King - ARM Linux admin <linux@armlinux.org.uk>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>

Merged with Maxime's irc r-b.
-Daniel

> ---
>  Documentation/driver-api/component.rst |  2 ++
>  Documentation/gpu/drm-internals.rst    |  5 +++++
>  drivers/gpu/drm/drm_drv.c              | 25 +++++++++++++++++++++++++
>  3 files changed, 32 insertions(+)
> 
> diff --git a/Documentation/driver-api/component.rst b/Documentation/driver-api/component.rst
> index 2da4a8f20607..57e37590733f 100644
> --- a/Documentation/driver-api/component.rst
> +++ b/Documentation/driver-api/component.rst
> @@ -1,3 +1,5 @@
> +.. _component:
> +
>  ======================================
>  Component Helper for Aggregate Drivers
>  ======================================
> diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst
> index 3ae23a5454ac..966bd2d9f0cc 100644
> --- a/Documentation/gpu/drm-internals.rst
> +++ b/Documentation/gpu/drm-internals.rst
> @@ -93,6 +93,11 @@ Device Instance and Driver Handling
>  Driver Load
>  -----------
>  
> +Component Helper Usage
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_drv.c
> +   :doc: component helper usage recommendations
>  
>  IRQ Helper Library
>  ~~~~~~~~~~~~~~~~~~
> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
> index 4f70cf68112f..43825a888e67 100644
> --- a/drivers/gpu/drm/drm_drv.c
> +++ b/drivers/gpu/drm/drm_drv.c
> @@ -456,6 +456,31 @@ static void drm_fs_inode_free(struct inode *inode)
>  	}
>  }
>  
> +/**
> + * DOC: component helper usage recommendations
> + *
> + * DRM drivers that drive hardware where a logical device consists of a pile of
> + * independent hardware blocks are recommended to use the :ref:`component helper
> + * library<component>`. For consistency and better options for code reuse the
> + * following guidelines apply:
> + *
> + *  - The entire device initialization procedure should be run from the
> + *    &component_master_ops.master_bind callback, starting with drm_dev_init(),
> + *    then binding all components with component_bind_all() and finishing with
> + *    drm_dev_register().
> + *
> + *  - The opaque pointer passed to all components through component_bind_all()
> + *    should point at &struct drm_device of the device instance, not some driver
> + *    specific private structure.
> + *
> + *  - The component helper fills the niche where further standardization of
> + *    interfaces is not practical. When there already is, or will be, a
> + *    standardized interface like &drm_bridge or &drm_panel, providing its own
> + *    functions to find such components at driver load time, like
> + *    drm_of_find_panel_or_bridge(), then the component helper should not be
> + *    used.
> + */
> +
>  /**
>   * drm_dev_init - Initialise new DRM device
>   * @dev: DRM device
> -- 
> 2.20.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel