1/*
  2 * Copyright (C) 2013, NVIDIA Corporation.  All rights reserved.
  3 *
  4 * Permission is hereby granted, free of charge, to any person obtaining a
  5 * copy of this software and associated documentation files (the "Software"),
  6 * to deal in the Software without restriction, including without limitation
  7 * the rights to use, copy, modify, merge, publish, distribute, sub license,
  8 * and/or sell copies of the Software, and to permit persons to whom the
  9 * Software is furnished to do so, subject to the following conditions:
 10 *
 11 * The above copyright notice and this permission notice (including the
 12 * next paragraph) shall be included in all copies or substantial portions
 13 * of the Software.
 14 *
 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17 * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
 18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 21 * DEALINGS IN THE SOFTWARE.
 22 */
 23
 24#ifndef __DRM_PANEL_H__
 25#define __DRM_PANEL_H__
 26
 27#include <linux/err.h>
 28#include <linux/errno.h>
 29#include <linux/list.h>
 30
 31struct device_node;
 32struct drm_connector;
 33struct drm_device;
 34struct drm_panel;
 35struct display_timing;
 36
 37/**
 38 * struct drm_panel_funcs - perform operations on a given panel
 39 *
 40 * The .prepare() function is typically called before the display controller
 41 * starts to transmit video data. Panel drivers can use this to turn the panel
 42 * on and wait for it to become ready. If additional configuration is required
 43 * (via a control bus such as I2C, SPI or DSI for example) this is a good time
 44 * to do that.
 45 *
 46 * After the display controller has started transmitting video data, it's safe
 47 * to call the .enable() function. This will typically enable the backlight to
 48 * make the image on screen visible. Some panels require a certain amount of
 49 * time or frames before the image is displayed. This function is responsible
 50 * for taking this into account before enabling the backlight to avoid visual
 51 * glitches.
 52 *
 53 * Before stopping video transmission from the display controller it can be
 54 * necessary to turn off the panel to avoid visual glitches. This is done in
 55 * the .disable() function. Analogously to .enable() this typically involves
 56 * turning off the backlight and waiting for some time to make sure no image
 57 * is visible on the panel. It is then safe for the display controller to
 58 * cease transmission of video data.
 59 *
 60 * To save power when no video data is transmitted, a driver can power down
 61 * the panel. This is the job of the .unprepare() function.
 62 */
 63struct drm_panel_funcs {
 64	/**
 65	 * @prepare:
 66	 *
 67	 * Turn on panel and perform set up.
 68	 */
 69	int (*prepare)(struct drm_panel *panel);
 70
 71	/**
 72	 * @enable:
 73	 *
 74	 * Enable panel (turn on back light, etc.).
 75	 */
 76	int (*enable)(struct drm_panel *panel);
 77
 78	/**
 79	 * @disable:
 80	 *
 81	 * Disable panel (turn off back light, etc.).
 82	 */
 83	int (*disable)(struct drm_panel *panel);
 84
 85	/**
 86	 * @unprepare:
 87	 *
 88	 * Turn off panel.
 89	 */
 90	int (*unprepare)(struct drm_panel *panel);
 91
 92	/**
 93	 * @get_modes:
 94	 *
 95	 * Add modes to the connector that the panel is attached to and
 96	 * return the number of modes added.
 97	 */
 98	int (*get_modes)(struct drm_panel *panel);
 99
100	/**
101	 * @get_timings:
102	 *
103	 * Copy display timings into the provided array and return
104	 * the number of display timings available.
105	 */
106	int (*get_timings)(struct drm_panel *panel, unsigned int num_timings,
107			   struct display_timing *timings);
108};
109
110/**
111 * struct drm_panel - DRM panel object
112 */
113struct drm_panel {
114	/**
115	 * @drm:
116	 *
117	 * DRM device owning the panel.
118	 */
119	struct drm_device *drm;
120
121	/**
122	 * @connector:
123	 *
124	 * DRM connector that the panel is attached to.
125	 */
126	struct drm_connector *connector;
127
128	/**
129	 * @dev:
130	 *
131	 * Parent device of the panel.
132	 */
133	struct device *dev;
134
135	/**
136	 * @funcs:
137	 *
138	 * Operations that can be performed on the panel.
139	 */
140	const struct drm_panel_funcs *funcs;
141
142	/**
143	 * @list:
144	 *
145	 * Panel entry in registry.
146	 */
147	struct list_head list;
148};
149
150void drm_panel_init(struct drm_panel *panel);
151
152int drm_panel_add(struct drm_panel *panel);
153void drm_panel_remove(struct drm_panel *panel);
154
155int drm_panel_attach(struct drm_panel *panel, struct drm_connector *connector);
156void drm_panel_detach(struct drm_panel *panel);
157
158int drm_panel_prepare(struct drm_panel *panel);
159int drm_panel_unprepare(struct drm_panel *panel);
160
161int drm_panel_enable(struct drm_panel *panel);
162int drm_panel_disable(struct drm_panel *panel);
163
164int drm_panel_get_modes(struct drm_panel *panel);
165
166#if defined(CONFIG_OF) && defined(CONFIG_DRM_PANEL)
167struct drm_panel *of_drm_find_panel(const struct device_node *np);
168#else
169static inline struct drm_panel *of_drm_find_panel(const struct device_node *np)
170{
171	return ERR_PTR(-ENODEV);
172}
173#endif
174
175#endif