From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1758072AbcEFOBn (ORCPT ); Fri, 6 May 2016 10:01:43 -0400 Received: from mail-wm0-f51.google.com ([74.125.82.51]:35638 "EHLO mail-wm0-f51.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757430AbcEFOBl (ORCPT ); Fri, 6 May 2016 10:01:41 -0400 Date: Fri, 6 May 2016 16:01:37 +0200 From: Thierry Reding To: Noralf =?utf-8?Q?Tr=C3=B8nnes?= Cc: dri-devel@lists.freedesktop.org, treding@nvidia.com, linux-kernel@vger.kernel.org Subject: Re: [PATCH 4/4] drm/panel: Add helper for simple panel connector Message-ID: <20160506140137.GA4641@ulmo.ba.sec> References: <1462454674-2246-1-git-send-email-noralf@tronnes.org> <1462454674-2246-5-git-send-email-noralf@tronnes.org> <20160505170321.GO1286@phenom.ffwll.local> <2a8224c5-d95e-273a-59ff-c6372b7c01a0@tronnes.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="GvXjxJ+pjyke8COw" Content-Disposition: inline In-Reply-To: <2a8224c5-d95e-273a-59ff-c6372b7c01a0@tronnes.org> User-Agent: Mutt/1.6.1 (2016-04-27) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org --GvXjxJ+pjyke8COw Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, May 06, 2016 at 03:39:53PM +0200, Noralf Tr=C3=B8nnes wrote: >=20 > Den 05.05.2016 19:03, skrev Daniel Vetter: > > On Thu, May 05, 2016 at 03:24:34PM +0200, Noralf Tr=C3=B8nnes wrote: > > > Add function to create a simple connector for a panel. > > >=20 > > > Signed-off-by: Noralf Tr=C3=B8nnes > > 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. >=20 > 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. >=20 > 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 --- =46rom 77057510413f8ca52d37da883afeabb13031ec63 Mon Sep 17 00:00:00 2001 =46rom: Thierry Reding 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 --- 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 - Bridges + Bridges - Overview + Overview !Pdrivers/gpu/drm/drm_bridge.c overview - Default bridge callback sequence + Default bridge callback sequence !Pdrivers/gpu/drm/drm_bridge.c bridge callbacks !Edrivers/gpu/drm/drm_bridge.c + + Panel Helper Reference +!Iinclude/drm/drm_panel.h +!Edrivers/gpu/drm/drm_panel.c +!Pdrivers/gpu/drm/drm_panel.c drm panel + =20 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); =20 +/** + * 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 disp= lay + * drivers. + */ + +/** + * drm_panel_init - initialize a panel + * @panel: DRM panel + * + * Sets up internal fields of the panel so that it can subsequently be add= ed + * to the registry. + */ void drm_panel_init(struct drm_panel *panel) { INIT_LIST_HEAD(&panel->list); } EXPORT_SYMBOL(drm_panel_init); =20 +/** + * 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 displ= ay + * 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); =20 +/** + * 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); =20 +/** + * 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 connec= tor. + * + * Return: 0 on success or a negative error code on failure. + */ int drm_panel_attach(struct drm_panel *panel, struct drm_connector *connec= tor) { if (panel->connector) @@ -66,6 +108,15 @@ int drm_panel_attach(struct drm_panel *panel, struct dr= m_connector *connector) } EXPORT_SYMBOL(drm_panel_attach); =20 +/** + * 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 =3D NULL; @@ -76,6 +127,16 @@ int drm_panel_detach(struct drm_panel *panel) EXPORT_SYMBOL(drm_panel_detach); =20 #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 de= vice + * 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); }; =20 +/** + * 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; }; =20 +/** + * drm_disable_unprepare - power off a panel + * @panel: DRM panel + * + * Calling this function will completely power off a panel (assert the pan= el's + * reset, turn off power supplies, ...). After this function has completed= , it + * is usually no longer possible to communicate with the panel until anoth= er + * 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; } =20 +/** + * drm_panel_disable - disable a panel + * @panel: DRM panel + * + * This will typically turn off the panel's backlight or disable the displ= ay + * drivers. For smart panels it should still be possible to communicate wi= th + * 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; } =20 +/** + * 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; } =20 +/** + * 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 *p= anel) return panel ? -ENOSYS : -EINVAL; } =20 +/** + * 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) --=20 2.8.2 --GvXjxJ+pjyke8COw Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAABCAAGBQJXLKO+AAoJEN0jrNd/PrOhvZsP/RUbAEo4sGfx/d4DkEzl47Mq xj5FoK6G7LZsNZQkZU+faSGbHWHCgo22X8NfVWCAa+cKFf5VBCEfGl0EFYMx2LAY 0FQbzYFlTOGr1rAvYXwz6CJ/zzzqbp9cfwN4Qux6WkQaD3ETXMMb+qM1A4EqvsiQ 6Tb+STu5kVF+HRI455UziKlYR4wkeNAqyV/YOF0mwTqMUxcg6ZYRAW37Kw/BUHDw tfAVZ90KjRgC283sG6SjMUf6OYbEi8B77LPR3cNqbWEWhgX1gwiivs7Ol4v1EIzD ejbwfBUcMwgJGoT/XaEDeLZQa2sbxlFnJ6LA8ZDNURqwWkq6aJGPNJI90la1kDtF pMD7pC1xjkA9ewDWpTtQYaLhle2polaxaNnGl07Zh5PzTCktbD+Yj99GxLcwx7Rm yvRX8IvDGIV7+meaduycPFbV6Vdz82RMVi7qkGPbF+Jnj3UibY8SvOGii5d+pdoc TaX6tohnN80H1+Tm/7Cm2MToLlpi6dyUkjF6twxN5jWVttrlKatKf4Di4VUugU3X 8Q7X7paFSeSDgPT7CdXHkgneOa2sbZ00t90AZLu/WFlr39A60r4TgxdMGXcnrJay syxdDe1KzfavHwYzaIpBr6IhQobeU/09fnRbD/xkQ0mZaimQ5idEtCwqghkLLbKf BOLe1wNpuowkM0eHSeZq =ff4B -----END PGP SIGNATURE----- --GvXjxJ+pjyke8COw--