Commit 86ab67df authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: document recommended component helper usage 



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>
Reviewed-by: default avatarMaxime Ripard <maxime.ripard@bootlin.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190212164615.13370-1-daniel.vetter@ffwll.ch
parent 58db7022

Documentation/driver-api/component.rst

+2 −0
Original line number Diff line number Diff line 
.. _component:



======================================

Component Helper for Aggregate Drivers

======================================

Documentation/gpu/drm-internals.rst

+5 −0
Original line number Diff line number Diff line
@@ -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

~~~~~~~~~~~~~~~~~~

drivers/gpu/drm/drm_drv.c

+25 −0
Original line number Diff line number Diff line
@@ -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

CRA Git | Maintained and supported by SUSTech CRA and CCSE