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@xxxxxxxxxxxxxxxx> Cc: Russell King - ARM Linux admin <linux@xxxxxxxxxxxxxxx> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> --- 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@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel
