Skip to content

Commit

Permalink
drm/panel: Flesh out kerneldoc
Browse files Browse the repository at this point in the history 
Write more complete kerneldoc comments for the DRM panel API and
integrate the helpers in the DRM DocBook reference.

Signed-off-by: Thierry Reding <treding@nvidia.com>drm/panel: Add helper for simple panel connector
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20160506140137.GA4641@ulmo.ba.sec
  • Loading branch information
Thierry Reding authored and Daniel Vetter committed May 6, 2016
1 parent 445d84a commit 83127f6
Show file tree
Hide file tree
Showing 3 changed files with 129 additions and 3 deletions.
12 changes: 9 additions & 3 deletions Documentation/DocBook/gpu.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1671,17 +1671,23 @@ void intel_crt_init(struct drm_device *dev)
!Pdrivers/gpu/drm/drm_crtc.c Tile group
</sect2>
<sect2>
<title>Bridges</title>
<title>Bridges</title>
<sect3>
<title>Overview</title>
<title>Overview</title>
!Pdrivers/gpu/drm/drm_bridge.c overview
</sect3>
<sect3>
<title>Default bridge callback sequence</title>
<title>Default bridge callback sequence</title>
!Pdrivers/gpu/drm/drm_bridge.c bridge callbacks
</sect3>
!Edrivers/gpu/drm/drm_bridge.c
</sect2>
<sect2>
<title>Panel Helper Reference</title>
!Iinclude/drm/drm_panel.h
!Edrivers/gpu/drm/drm_panel.c
!Pdrivers/gpu/drm/drm_panel.c drm panel
</sect2>
</sect1>

<!-- Internals: kms properties -->
Expand Down
61 changes: 61 additions & 0 deletions drivers/gpu/drm/drm_panel.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,36 @@
static DEFINE_MUTEX(panel_lock);
static LIST_HEAD(panel_list);

/**
* DOC: drm panel
*
* The DRM panel helpers allow drivers to register panel objects with a
* central registry and provide functions to retrieve those panels in display
* drivers.
*/

/**
* drm_panel_init - initialize a panel
* @panel: DRM panel
*
* Sets up internal fields of the panel so that it can subsequently be added
* to the registry.
*/
void drm_panel_init(struct drm_panel *panel)
{
INIT_LIST_HEAD(&panel->list);
}
EXPORT_SYMBOL(drm_panel_init);

/**
* drm_panel_add - add a panel to the global registry
* @panel: panel to add
*
* Add a panel to the global registry so that it can be looked up by display
* drivers.
*
* Return: 0 on success or a negative error code on failure.
*/
int drm_panel_add(struct drm_panel *panel)
{
mutex_lock(&panel_lock);
Expand All @@ -46,6 +70,12 @@ int drm_panel_add(struct drm_panel *panel)
}
EXPORT_SYMBOL(drm_panel_add);

/**
* drm_panel_remove - remove a panel from the global registry
* @panel: DRM panel
*
* Removes a panel from the global registry.
*/
void drm_panel_remove(struct drm_panel *panel)
{
mutex_lock(&panel_lock);
Expand All @@ -54,6 +84,18 @@ void drm_panel_remove(struct drm_panel *panel)
}
EXPORT_SYMBOL(drm_panel_remove);

/**
* drm_panel_attach - attach a panel to a connector
* @panel: DRM panel
* @connector: DRM connector
*
* After obtaining a pointer to a DRM panel a display driver calls this
* function to attach a panel to a connector.
*
* An error is returned if the panel is already attached to another connector.
*
* Return: 0 on success or a negative error code on failure.
*/
int drm_panel_attach(struct drm_panel *panel, struct drm_connector *connector)
{
if (panel->connector)
Expand All @@ -66,6 +108,15 @@ int drm_panel_attach(struct drm_panel *panel, struct drm_connector *connector)
}
EXPORT_SYMBOL(drm_panel_attach);

/**
* drm_panel_detach - detach a panel from a connector
* @panel: DRM panel
*
* Detaches a panel from the connector it is attached to. If a panel is not
* attached to any connector this is effectively a no-op.
*
* Return: 0 on success or a negative error code on failure.
*/
int drm_panel_detach(struct drm_panel *panel)
{
panel->connector = NULL;
Expand All @@ -76,6 +127,16 @@ int drm_panel_detach(struct drm_panel *panel)
EXPORT_SYMBOL(drm_panel_detach);

#ifdef CONFIG_OF
/**
* of_drm_find_panel - look up a panel using a device tree node
* @np: device tree node of the panel
*
* Searches the set of registered panels for one that matches the given device
* tree node. If a matching panel is found, return a pointer to it.
*
* Return: A pointer to the panel registered for the specified device tree
* node or NULL if no panel matching the device tree node can be found.
*/
struct drm_panel *of_drm_find_panel(struct device_node *np)
{
struct drm_panel *panel;
Expand Down
59 changes: 59 additions & 0 deletions include/drm/drm_panel.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,14 @@ struct drm_panel_funcs {
struct display_timing *timings);
};

/**
* struct drm_panel - DRM panel object
* @drm: DRM device owning the panel
* @connector: DRM connector that the panel is attached to
* @dev: parent device of the panel
* @funcs: operations that can be performed on the panel
* @list: panel entry in registry
*/
struct drm_panel {
struct drm_device *drm;
struct drm_connector *connector;
Expand All @@ -85,6 +93,17 @@ struct drm_panel {
struct list_head list;
};

/**
* drm_disable_unprepare - power off a panel
* @panel: DRM panel
*
* Calling this function will completely power off a panel (assert the panel's
* reset, turn off power supplies, ...). After this function has completed, it
* is usually no longer possible to communicate with the panel until another
* call to drm_panel_prepare().
*
* Return: 0 on success or a negative error code on failure.
*/
static inline int drm_panel_unprepare(struct drm_panel *panel)
{
if (panel && panel->funcs && panel->funcs->unprepare)
Expand All @@ -93,6 +112,16 @@ static inline int drm_panel_unprepare(struct drm_panel *panel)
return panel ? -ENOSYS : -EINVAL;
}

/**
* drm_panel_disable - disable a panel
* @panel: DRM panel
*
* This will typically turn off the panel's backlight or disable the display
* drivers. For smart panels it should still be possible to communicate with
* the integrated circuitry via any command bus after this call.
*
* Return: 0 on success or a negative error code on failure.
*/
static inline int drm_panel_disable(struct drm_panel *panel)
{
if (panel && panel->funcs && panel->funcs->disable)
Expand All @@ -101,6 +130,16 @@ static inline int drm_panel_disable(struct drm_panel *panel)
return panel ? -ENOSYS : -EINVAL;
}

/**
* drm_panel_prepare - power on a panel
* @panel: DRM panel
*
* Calling this function will enable power and deassert any reset signals to
* the panel. After this has completed it is possible to communicate with any
* integrated circuitry via a command bus.
*
* Return: 0 on success or a negative error code on failure.
*/
static inline int drm_panel_prepare(struct drm_panel *panel)
{
if (panel && panel->funcs && panel->funcs->prepare)
Expand All @@ -109,6 +148,16 @@ static inline int drm_panel_prepare(struct drm_panel *panel)
return panel ? -ENOSYS : -EINVAL;
}

/**
* drm_panel_enable - enable a panel
* @panel: DRM panel
*
* Calling this function will cause the panel display drivers to be turned on
* and the backlight to be enabled. Content will be visible on screen after
* this call completes.
*
* Return: 0 on success or a negative error code on failure.
*/
static inline int drm_panel_enable(struct drm_panel *panel)
{
if (panel && panel->funcs && panel->funcs->enable)
Expand All @@ -117,6 +166,16 @@ static inline int drm_panel_enable(struct drm_panel *panel)
return panel ? -ENOSYS : -EINVAL;
}

/**
* drm_panel_get_modes - probe the available display modes of a panel
* @panel: DRM panel
*
* The modes probed from the panel are automatically added to the connector
* that the panel is attached to.
*
* Return: The number of modes available from the panel on success or a
* negative error code on failure.
*/
static inline int drm_panel_get_modes(struct drm_panel *panel)
{
if (panel && panel->funcs && panel->funcs->get_modes)
Expand Down

0 comments on commit 83127f6

Please sign in to comment.