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.pinch...@ideasonboard.com> > Cc: Russell King - ARM Linux admin <li...@armlinux.org.uk> > Signed-off-by: Daniel Vetter <daniel.vet...@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
