Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector

From: Thierry Reding
Date: Fri May 06 2016 - 10:01:46 EST

Next message: Thierry Reding: "Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector"
Previous message: Kevin Hilman: "[PATCH] MAINTAINERS: ARM/Amlogic: add co-maintainer, misc. updates"
In reply to: Noralf TrÃnnes: "Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector"
Next in thread: Daniel Vetter: "Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

On Fri, May 06, 2016 at 03:39:53PM +0200, Noralf TrÃnnes wrote:
>
> Den 05.05.2016 19:03, skrev Daniel Vetter:
> > On Thu, May 05, 2016 at 03:24:34PM +0200, Noralf TrÃnnes wrote:
> > > Add function to create a simple connector for a panel.
> > >
> > > Signed-off-by: Noralf TrÃnnes <noralf@xxxxxxxxxxx>
> > Like in the previous patch please also add a new section for the panel
> > helpers to gpu.tmpl. I don't think this needs an overview section, it's so
> > simple. But adding some cross references from the drm_panel.c kerneldoc to
> > this and back would be real good.
>
> drm_panel.c doesn't have any documentation and the header file has only
> the drm_panel_funcs struct documented, not hooked up to gpu.tmpl.
>
> I can make a patch documenting the functions, it looks fairly straight
> forward, but I have no idea what to put in the DOC: section, except an
> xref to this helper :-)

Maybe now is a good time for me to post the below. I really should've
sent this out ages ago, sorry.

Thierry
--- >8 ---
From 77057510413f8ca52d37da883afeabb13031ec63 Mon Sep 17 00:00:00 2001
From: Thierry Reding <treding@xxxxxxxxxx>
Date: Tue, 4 Nov 2014 15:23:10 +0100
Subject: [PATCH] drm/panel: Flesh out kerneldoc

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@xxxxxxxxxx>
---
Documentation/DocBook/gpu.tmpl | 12 ++++++---
drivers/gpu/drm/drm_panel.c | 61 ++++++++++++++++++++++++++++++++++++++++++
include/drm/drm_panel.h | 59 ++++++++++++++++++++++++++++++++++++++++
3 files changed, 129 insertions(+), 3 deletions(-)

diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index 1464fb2f3c46..fb4ad6945a97 100644
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -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>


diff --git a/drivers/gpu/drm/drm_panel.c b/drivers/gpu/drm/drm_panel.c
index 2ef988e037b7..3dfe3c886502 100644
--- a/drivers/gpu/drm/drm_panel.c
+++ b/drivers/gpu/drm/drm_panel.c
@@ -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);
@@ -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);
@@ -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)
@@ -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;
@@ -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;
diff --git a/include/drm/drm_panel.h b/include/drm/drm_panel.h
index 13ff44b28893..220d1e2b3db1 100644
--- a/include/drm/drm_panel.h
+++ b/include/drm/drm_panel.h
@@ -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;
@@ -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)
@@ -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)
@@ -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)
@@ -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)
@@ -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)
--
2.8.2

Attachment: signature.asc
Description: PGP signature

Next message: Thierry Reding: "Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector"
Previous message: Kevin Hilman: "[PATCH] MAINTAINERS: ARM/Amlogic: add co-maintainer, misc. updates"
In reply to: Noralf TrÃnnes: "Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector"
Next in thread: Daniel Vetter: "Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]