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 #include <linux/backlight.h>
25 #include <linux/err.h>
26 #include <linux/module.h>
27
28 #include <drm/drm_crtc.h>
29 #include <drm/drm_panel.h>
30 #include <drm/drm_print.h>
31
32 static DEFINE_MUTEX(panel_lock);
33 static LIST_HEAD(panel_list);
34
35 /**
36 * DOC: drm panel
37 *
38 * The DRM panel helpers allow drivers to register panel objects with a
39 * central registry and provide functions to retrieve those panels in display
40 * drivers.
41 *
42 * For easy integration into drivers using the &drm_bridge infrastructure please
43 * take look at drm_panel_bridge_add() and devm_drm_panel_bridge_add().
44 */
45
46 /**
47 * drm_panel_init - initialize a panel
48 * @panel: DRM panel
49 * @dev: parent device of the panel
50 * @funcs: panel operations
51 * @connector_type: the connector type (DRM_MODE_CONNECTOR_*) corresponding to
52 * the panel interface (must NOT be DRM_MODE_CONNECTOR_Unknown)
53 *
54 * Initialize the panel structure for subsequent registration with
55 * drm_panel_add().
56 */
drm_panel_init(struct drm_panel * panel,struct device * dev,const struct drm_panel_funcs * funcs,int connector_type)57 void drm_panel_init(struct drm_panel *panel, struct device *dev,
58 const struct drm_panel_funcs *funcs, int connector_type)
59 {
60 if (connector_type == DRM_MODE_CONNECTOR_Unknown)
61 DRM_WARN("%s: %s: a valid connector type is required!\n", __func__, dev_name(dev));
62
63 INIT_LIST_HEAD(&panel->list);
64 INIT_LIST_HEAD(&panel->followers);
65 mutex_init(&panel->follower_lock);
66 panel->dev = dev;
67 panel->funcs = funcs;
68 panel->connector_type = connector_type;
69 }
70 EXPORT_SYMBOL(drm_panel_init);
71
72 /**
73 * drm_panel_add - add a panel to the global registry
74 * @panel: panel to add
75 *
76 * Add a panel to the global registry so that it can be looked up by display
77 * drivers.
78 */
drm_panel_add(struct drm_panel * panel)79 void drm_panel_add(struct drm_panel *panel)
80 {
81 mutex_lock(&panel_lock);
82 list_add_tail(&panel->list, &panel_list);
83 mutex_unlock(&panel_lock);
84 }
85 EXPORT_SYMBOL(drm_panel_add);
86
87 /**
88 * drm_panel_remove - remove a panel from the global registry
89 * @panel: DRM panel
90 *
91 * Removes a panel from the global registry.
92 */
drm_panel_remove(struct drm_panel * panel)93 void drm_panel_remove(struct drm_panel *panel)
94 {
95 mutex_lock(&panel_lock);
96 list_del_init(&panel->list);
97 mutex_unlock(&panel_lock);
98 }
99 EXPORT_SYMBOL(drm_panel_remove);
100
101 /**
102 * drm_panel_prepare - power on a panel
103 * @panel: DRM panel
104 *
105 * Calling this function will enable power and deassert any reset signals to
106 * the panel. After this has completed it is possible to communicate with any
107 * integrated circuitry via a command bus.
108 *
109 * Return: 0 on success or a negative error code on failure.
110 */
drm_panel_prepare(struct drm_panel * panel)111 int drm_panel_prepare(struct drm_panel *panel)
112 {
113 struct drm_panel_follower *follower;
114 int ret;
115
116 if (!panel)
117 return -EINVAL;
118
119 if (panel->prepared) {
120 dev_warn(panel->dev, "Skipping prepare of already prepared panel\n");
121 return 0;
122 }
123
124 mutex_lock(&panel->follower_lock);
125
126 if (panel->funcs && panel->funcs->prepare) {
127 ret = panel->funcs->prepare(panel);
128 if (ret < 0)
129 goto exit;
130 }
131 panel->prepared = true;
132
133 list_for_each_entry(follower, &panel->followers, list) {
134 ret = follower->funcs->panel_prepared(follower);
135 if (ret < 0)
136 dev_info(panel->dev, "%ps failed: %d\n",
137 follower->funcs->panel_prepared, ret);
138 }
139
140 ret = 0;
141 exit:
142 mutex_unlock(&panel->follower_lock);
143
144 return ret;
145 }
146 EXPORT_SYMBOL(drm_panel_prepare);
147
148 /**
149 * drm_panel_unprepare - power off a panel
150 * @panel: DRM panel
151 *
152 * Calling this function will completely power off a panel (assert the panel's
153 * reset, turn off power supplies, ...). After this function has completed, it
154 * is usually no longer possible to communicate with the panel until another
155 * call to drm_panel_prepare().
156 *
157 * Return: 0 on success or a negative error code on failure.
158 */
drm_panel_unprepare(struct drm_panel * panel)159 int drm_panel_unprepare(struct drm_panel *panel)
160 {
161 struct drm_panel_follower *follower;
162 int ret;
163
164 if (!panel)
165 return -EINVAL;
166
167 /*
168 * If you are seeing the warning below it likely means one of two things:
169 * - Your panel driver incorrectly calls drm_panel_unprepare() in its
170 * shutdown routine. You should delete this.
171 * - You are using panel-edp or panel-simple and your DRM modeset
172 * driver's shutdown() callback happened after the panel's shutdown().
173 * In this case the warning is harmless though ideally you should
174 * figure out how to reverse the order of the shutdown() callbacks.
175 */
176 if (!panel->prepared) {
177 dev_warn(panel->dev, "Skipping unprepare of already unprepared panel\n");
178 return 0;
179 }
180
181 mutex_lock(&panel->follower_lock);
182
183 list_for_each_entry(follower, &panel->followers, list) {
184 ret = follower->funcs->panel_unpreparing(follower);
185 if (ret < 0)
186 dev_info(panel->dev, "%ps failed: %d\n",
187 follower->funcs->panel_unpreparing, ret);
188 }
189
190 if (panel->funcs && panel->funcs->unprepare) {
191 ret = panel->funcs->unprepare(panel);
192 if (ret < 0)
193 goto exit;
194 }
195 panel->prepared = false;
196
197 ret = 0;
198 exit:
199 mutex_unlock(&panel->follower_lock);
200
201 return ret;
202 }
203 EXPORT_SYMBOL(drm_panel_unprepare);
204
205 /**
206 * drm_panel_enable - enable a panel
207 * @panel: DRM panel
208 *
209 * Calling this function will cause the panel display drivers to be turned on
210 * and the backlight to be enabled. Content will be visible on screen after
211 * this call completes.
212 *
213 * Return: 0 on success or a negative error code on failure.
214 */
drm_panel_enable(struct drm_panel * panel)215 int drm_panel_enable(struct drm_panel *panel)
216 {
217 int ret;
218
219 if (!panel)
220 return -EINVAL;
221
222 if (panel->enabled) {
223 dev_warn(panel->dev, "Skipping enable of already enabled panel\n");
224 return 0;
225 }
226
227 if (panel->funcs && panel->funcs->enable) {
228 ret = panel->funcs->enable(panel);
229 if (ret < 0)
230 return ret;
231 }
232 panel->enabled = true;
233
234 ret = backlight_enable(panel->backlight);
235 if (ret < 0)
236 DRM_DEV_INFO(panel->dev, "failed to enable backlight: %d\n",
237 ret);
238
239 return 0;
240 }
241 EXPORT_SYMBOL(drm_panel_enable);
242
243 /**
244 * drm_panel_disable - disable a panel
245 * @panel: DRM panel
246 *
247 * This will typically turn off the panel's backlight or disable the display
248 * drivers. For smart panels it should still be possible to communicate with
249 * the integrated circuitry via any command bus after this call.
250 *
251 * Return: 0 on success or a negative error code on failure.
252 */
drm_panel_disable(struct drm_panel * panel)253 int drm_panel_disable(struct drm_panel *panel)
254 {
255 int ret;
256
257 if (!panel)
258 return -EINVAL;
259
260 /*
261 * If you are seeing the warning below it likely means one of two things:
262 * - Your panel driver incorrectly calls drm_panel_disable() in its
263 * shutdown routine. You should delete this.
264 * - You are using panel-edp or panel-simple and your DRM modeset
265 * driver's shutdown() callback happened after the panel's shutdown().
266 * In this case the warning is harmless though ideally you should
267 * figure out how to reverse the order of the shutdown() callbacks.
268 */
269 if (!panel->enabled) {
270 dev_warn(panel->dev, "Skipping disable of already disabled panel\n");
271 return 0;
272 }
273
274 ret = backlight_disable(panel->backlight);
275 if (ret < 0)
276 DRM_DEV_INFO(panel->dev, "failed to disable backlight: %d\n",
277 ret);
278
279 if (panel->funcs && panel->funcs->disable) {
280 ret = panel->funcs->disable(panel);
281 if (ret < 0)
282 return ret;
283 }
284 panel->enabled = false;
285
286 return 0;
287 }
288 EXPORT_SYMBOL(drm_panel_disable);
289
290 /**
291 * drm_panel_get_modes - probe the available display modes of a panel
292 * @panel: DRM panel
293 * @connector: DRM connector
294 *
295 * The modes probed from the panel are automatically added to the connector
296 * that the panel is attached to.
297 *
298 * Return: The number of modes available from the panel on success, or 0 on
299 * failure (no modes).
300 */
drm_panel_get_modes(struct drm_panel * panel,struct drm_connector * connector)301 int drm_panel_get_modes(struct drm_panel *panel,
302 struct drm_connector *connector)
303 {
304 if (!panel)
305 return 0;
306
307 if (panel->funcs && panel->funcs->get_modes) {
308 int num;
309
310 num = panel->funcs->get_modes(panel, connector);
311 if (num > 0)
312 return num;
313 }
314
315 return 0;
316 }
317 EXPORT_SYMBOL(drm_panel_get_modes);
318
319 #ifdef CONFIG_OF
320 /**
321 * of_drm_find_panel - look up a panel using a device tree node
322 * @np: device tree node of the panel
323 *
324 * Searches the set of registered panels for one that matches the given device
325 * tree node. If a matching panel is found, return a pointer to it.
326 *
327 * Return: A pointer to the panel registered for the specified device tree
328 * node or an ERR_PTR() if no panel matching the device tree node can be found.
329 *
330 * Possible error codes returned by this function:
331 *
332 * - EPROBE_DEFER: the panel device has not been probed yet, and the caller
333 * should retry later
334 * - ENODEV: the device is not available (status != "okay" or "ok")
335 */
of_drm_find_panel(const struct device_node * np)336 struct drm_panel *of_drm_find_panel(const struct device_node *np)
337 {
338 struct drm_panel *panel;
339
340 if (!of_device_is_available(np))
341 return ERR_PTR(-ENODEV);
342
343 mutex_lock(&panel_lock);
344
345 list_for_each_entry(panel, &panel_list, list) {
346 if (panel->dev->of_node == np) {
347 mutex_unlock(&panel_lock);
348 return panel;
349 }
350 }
351
352 mutex_unlock(&panel_lock);
353 return ERR_PTR(-EPROBE_DEFER);
354 }
355 EXPORT_SYMBOL(of_drm_find_panel);
356
357 /**
358 * of_drm_get_panel_orientation - look up the orientation of the panel through
359 * the "rotation" binding from a device tree node
360 * @np: device tree node of the panel
361 * @orientation: orientation enum to be filled in
362 *
363 * Looks up the rotation of a panel in the device tree. The orientation of the
364 * panel is expressed as a property name "rotation" in the device tree. The
365 * rotation in the device tree is counter clockwise.
366 *
367 * Return: 0 when a valid rotation value (0, 90, 180, or 270) is read or the
368 * rotation property doesn't exist. Return a negative error code on failure.
369 */
of_drm_get_panel_orientation(const struct device_node * np,enum drm_panel_orientation * orientation)370 int of_drm_get_panel_orientation(const struct device_node *np,
371 enum drm_panel_orientation *orientation)
372 {
373 int rotation, ret;
374
375 ret = of_property_read_u32(np, "rotation", &rotation);
376 if (ret == -EINVAL) {
377 /* Don't return an error if there's no rotation property. */
378 *orientation = DRM_MODE_PANEL_ORIENTATION_UNKNOWN;
379 return 0;
380 }
381
382 if (ret < 0)
383 return ret;
384
385 if (rotation == 0)
386 *orientation = DRM_MODE_PANEL_ORIENTATION_NORMAL;
387 else if (rotation == 90)
388 *orientation = DRM_MODE_PANEL_ORIENTATION_RIGHT_UP;
389 else if (rotation == 180)
390 *orientation = DRM_MODE_PANEL_ORIENTATION_BOTTOM_UP;
391 else if (rotation == 270)
392 *orientation = DRM_MODE_PANEL_ORIENTATION_LEFT_UP;
393 else
394 return -EINVAL;
395
396 return 0;
397 }
398 EXPORT_SYMBOL(of_drm_get_panel_orientation);
399 #endif
400
401 /**
402 * drm_is_panel_follower() - Check if the device is a panel follower
403 * @dev: The 'struct device' to check
404 *
405 * This checks to see if a device needs to be power sequenced together with
406 * a panel using the panel follower API.
407 * At the moment panels can only be followed on device tree enabled systems.
408 * The "panel" property of the follower points to the panel to be followed.
409 *
410 * Return: true if we should be power sequenced with a panel; false otherwise.
411 */
drm_is_panel_follower(struct device * dev)412 bool drm_is_panel_follower(struct device *dev)
413 {
414 /*
415 * The "panel" property is actually a phandle, but for simplicity we
416 * don't bother trying to parse it here. We just need to know if the
417 * property is there.
418 */
419 return of_property_read_bool(dev->of_node, "panel");
420 }
421 EXPORT_SYMBOL(drm_is_panel_follower);
422
423 /**
424 * drm_panel_add_follower() - Register something to follow panel state.
425 * @follower_dev: The 'struct device' for the follower.
426 * @follower: The panel follower descriptor for the follower.
427 *
428 * A panel follower is called right after preparing the panel and right before
429 * unpreparing the panel. It's primary intention is to power on an associated
430 * touchscreen, though it could be used for any similar devices. Multiple
431 * devices are allowed the follow the same panel.
432 *
433 * If a follower is added to a panel that's already been turned on, the
434 * follower's prepare callback is called right away.
435 *
436 * At the moment panels can only be followed on device tree enabled systems.
437 * The "panel" property of the follower points to the panel to be followed.
438 *
439 * Return: 0 or an error code. Note that -ENODEV means that we detected that
440 * follower_dev is not actually following a panel. The caller may
441 * choose to ignore this return value if following a panel is optional.
442 */
drm_panel_add_follower(struct device * follower_dev,struct drm_panel_follower * follower)443 int drm_panel_add_follower(struct device *follower_dev,
444 struct drm_panel_follower *follower)
445 {
446 struct device_node *panel_np;
447 struct drm_panel *panel;
448 int ret;
449
450 panel_np = of_parse_phandle(follower_dev->of_node, "panel", 0);
451 if (!panel_np)
452 return -ENODEV;
453
454 panel = of_drm_find_panel(panel_np);
455 of_node_put(panel_np);
456 if (IS_ERR(panel))
457 return PTR_ERR(panel);
458
459 get_device(panel->dev);
460 follower->panel = panel;
461
462 mutex_lock(&panel->follower_lock);
463
464 list_add_tail(&follower->list, &panel->followers);
465 if (panel->prepared) {
466 ret = follower->funcs->panel_prepared(follower);
467 if (ret < 0)
468 dev_info(panel->dev, "%ps failed: %d\n",
469 follower->funcs->panel_prepared, ret);
470 }
471
472 mutex_unlock(&panel->follower_lock);
473
474 return 0;
475 }
476 EXPORT_SYMBOL(drm_panel_add_follower);
477
478 /**
479 * drm_panel_remove_follower() - Reverse drm_panel_add_follower().
480 * @follower: The panel follower descriptor for the follower.
481 *
482 * Undo drm_panel_add_follower(). This includes calling the follower's
483 * unprepare function if we're removed from a panel that's currently prepared.
484 *
485 * Return: 0 or an error code.
486 */
drm_panel_remove_follower(struct drm_panel_follower * follower)487 void drm_panel_remove_follower(struct drm_panel_follower *follower)
488 {
489 struct drm_panel *panel = follower->panel;
490 int ret;
491
492 mutex_lock(&panel->follower_lock);
493
494 if (panel->prepared) {
495 ret = follower->funcs->panel_unpreparing(follower);
496 if (ret < 0)
497 dev_info(panel->dev, "%ps failed: %d\n",
498 follower->funcs->panel_unpreparing, ret);
499 }
500 list_del_init(&follower->list);
501
502 mutex_unlock(&panel->follower_lock);
503
504 put_device(panel->dev);
505 }
506 EXPORT_SYMBOL(drm_panel_remove_follower);
507
drm_panel_remove_follower_void(void * follower)508 static void drm_panel_remove_follower_void(void *follower)
509 {
510 drm_panel_remove_follower(follower);
511 }
512
513 /**
514 * devm_drm_panel_add_follower() - devm version of drm_panel_add_follower()
515 * @follower_dev: The 'struct device' for the follower.
516 * @follower: The panel follower descriptor for the follower.
517 *
518 * Handles calling drm_panel_remove_follower() using devm on the follower_dev.
519 *
520 * Return: 0 or an error code.
521 */
devm_drm_panel_add_follower(struct device * follower_dev,struct drm_panel_follower * follower)522 int devm_drm_panel_add_follower(struct device *follower_dev,
523 struct drm_panel_follower *follower)
524 {
525 int ret;
526
527 ret = drm_panel_add_follower(follower_dev, follower);
528 if (ret)
529 return ret;
530
531 return devm_add_action_or_reset(follower_dev,
532 drm_panel_remove_follower_void, follower);
533 }
534 EXPORT_SYMBOL(devm_drm_panel_add_follower);
535
536 #if IS_REACHABLE(CONFIG_BACKLIGHT_CLASS_DEVICE)
537 /**
538 * drm_panel_of_backlight - use backlight device node for backlight
539 * @panel: DRM panel
540 *
541 * Use this function to enable backlight handling if your panel
542 * uses device tree and has a backlight phandle.
543 *
544 * When the panel is enabled backlight will be enabled after a
545 * successful call to &drm_panel_funcs.enable()
546 *
547 * When the panel is disabled backlight will be disabled before the
548 * call to &drm_panel_funcs.disable().
549 *
550 * A typical implementation for a panel driver supporting device tree
551 * will call this function at probe time. Backlight will then be handled
552 * transparently without requiring any intervention from the driver.
553 * drm_panel_of_backlight() must be called after the call to drm_panel_init().
554 *
555 * Return: 0 on success or a negative error code on failure.
556 */
drm_panel_of_backlight(struct drm_panel * panel)557 int drm_panel_of_backlight(struct drm_panel *panel)
558 {
559 struct backlight_device *backlight;
560
561 if (!panel || !panel->dev)
562 return -EINVAL;
563
564 backlight = devm_of_find_backlight(panel->dev);
565
566 if (IS_ERR(backlight))
567 return PTR_ERR(backlight);
568
569 panel->backlight = backlight;
570 return 0;
571 }
572 EXPORT_SYMBOL(drm_panel_of_backlight);
573 #endif
574
575 MODULE_AUTHOR("Thierry Reding <treding@nvidia.com>");
576 MODULE_DESCRIPTION("DRM panel infrastructure");
577 MODULE_LICENSE("GPL and additional rights");
578