1 /* $NetBSD: drm_bridge.h,v 1.2 2021/12/18 23:45:45 riastradh Exp $ */
2
3 /*
4 * Copyright (c) 2016 Intel Corporation
5 *
6 * Permission to use, copy, modify, distribute, and sell this software and its
7 * documentation for any purpose is hereby granted without fee, provided that
8 * the above copyright notice appear in all copies and that both that copyright
9 * notice and this permission notice appear in supporting documentation, and
10 * that the name of the copyright holders not be used in advertising or
11 * publicity pertaining to distribution of the software without specific,
12 * written prior permission. The copyright holders make no representations
13 * about the suitability of this software for any purpose. It is provided "as
14 * is" without express or implied warranty.
15 *
16 * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
17 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
18 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
19 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
20 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
21 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
22 * OF THIS SOFTWARE.
23 */
24
25 #ifndef __DRM_BRIDGE_H__
26 #define __DRM_BRIDGE_H__
27
28 #include <linux/list.h>
29 #include <linux/ctype.h>
30 #include <drm/drm_encoder.h>
31 #include <drm/drm_mode_object.h>
32 #include <drm/drm_modes.h>
33
34 struct drm_bridge;
35 struct drm_bridge_timings;
36 struct drm_panel;
37
38 /**
39 * struct drm_bridge_funcs - drm_bridge control functions
40 */
41 struct drm_bridge_funcs {
42 /**
43 * @attach:
44 *
45 * This callback is invoked whenever our bridge is being attached to a
46 * &drm_encoder.
47 *
48 * The @attach callback is optional.
49 *
50 * RETURNS:
51 *
52 * Zero on success, error code on failure.
53 */
54 int (*attach)(struct drm_bridge *bridge);
55
56 /**
57 * @detach:
58 *
59 * This callback is invoked whenever our bridge is being detached from a
60 * &drm_encoder.
61 *
62 * The @detach callback is optional.
63 */
64 void (*detach)(struct drm_bridge *bridge);
65
66 /**
67 * @mode_valid:
68 *
69 * This callback is used to check if a specific mode is valid in this
70 * bridge. This should be implemented if the bridge has some sort of
71 * restriction in the modes it can display. For example, a given bridge
72 * may be responsible to set a clock value. If the clock can not
73 * produce all the values for the available modes then this callback
74 * can be used to restrict the number of modes to only the ones that
75 * can be displayed.
76 *
77 * This hook is used by the probe helpers to filter the mode list in
78 * drm_helper_probe_single_connector_modes(), and it is used by the
79 * atomic helpers to validate modes supplied by userspace in
80 * drm_atomic_helper_check_modeset().
81 *
82 * The @mode_valid callback is optional.
83 *
84 * NOTE:
85 *
86 * Since this function is both called from the check phase of an atomic
87 * commit, and the mode validation in the probe paths it is not allowed
88 * to look at anything else but the passed-in mode, and validate it
89 * against configuration-invariant hardward constraints. Any further
90 * limits which depend upon the configuration can only be checked in
91 * @mode_fixup.
92 *
93 * RETURNS:
94 *
95 * drm_mode_status Enum
96 */
97 enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge,
98 const struct drm_display_mode *mode);
99
100 /**
101 * @mode_fixup:
102 *
103 * This callback is used to validate and adjust a mode. The parameter
104 * mode is the display mode that should be fed to the next element in
105 * the display chain, either the final &drm_connector or the next
106 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
107 * requires. It can be modified by this callback and does not need to
108 * match mode. See also &drm_crtc_state.adjusted_mode for more details.
109 *
110 * This is the only hook that allows a bridge to reject a modeset. If
111 * this function passes all other callbacks must succeed for this
112 * configuration.
113 *
114 * The @mode_fixup callback is optional.
115 *
116 * NOTE:
117 *
118 * This function is called in the check phase of atomic modesets, which
119 * can be aborted for any reason (including on userspace's request to
120 * just check whether a configuration would be possible). Drivers MUST
121 * NOT touch any persistent state (hardware or software) or data
122 * structures except the passed in @state parameter.
123 *
124 * Also beware that userspace can request its own custom modes, neither
125 * core nor helpers filter modes to the list of probe modes reported by
126 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
127 * that modes are filtered consistently put any bridge constraints and
128 * limits checks into @mode_valid.
129 *
130 * RETURNS:
131 *
132 * True if an acceptable configuration is possible, false if the modeset
133 * operation should be rejected.
134 */
135 bool (*mode_fixup)(struct drm_bridge *bridge,
136 const struct drm_display_mode *mode,
137 struct drm_display_mode *adjusted_mode);
138 /**
139 * @disable:
140 *
141 * This callback should disable the bridge. It is called right before
142 * the preceding element in the display pipe is disabled. If the
143 * preceding element is a bridge this means it's called before that
144 * bridge's @disable vfunc. If the preceding element is a &drm_encoder
145 * it's called right before the &drm_encoder_helper_funcs.disable,
146 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
147 * hook.
148 *
149 * The bridge can assume that the display pipe (i.e. clocks and timing
150 * signals) feeding it is still running when this callback is called.
151 *
152 * The @disable callback is optional.
153 */
154 void (*disable)(struct drm_bridge *bridge);
155
156 /**
157 * @post_disable:
158 *
159 * This callback should disable the bridge. It is called right after the
160 * preceding element in the display pipe is disabled. If the preceding
161 * element is a bridge this means it's called after that bridge's
162 * @post_disable function. If the preceding element is a &drm_encoder
163 * it's called right after the encoder's
164 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
165 * or &drm_encoder_helper_funcs.dpms hook.
166 *
167 * The bridge must assume that the display pipe (i.e. clocks and timing
168 * singals) feeding it is no longer running when this callback is
169 * called.
170 *
171 * The @post_disable callback is optional.
172 */
173 void (*post_disable)(struct drm_bridge *bridge);
174
175 /**
176 * @mode_set:
177 *
178 * This callback should set the given mode on the bridge. It is called
179 * after the @mode_set callback for the preceding element in the display
180 * pipeline has been called already. If the bridge is the first element
181 * then this would be &drm_encoder_helper_funcs.mode_set. The display
182 * pipe (i.e. clocks and timing signals) is off when this function is
183 * called.
184 *
185 * The adjusted_mode parameter is the mode output by the CRTC for the
186 * first bridge in the chain. It can be different from the mode
187 * parameter that contains the desired mode for the connector at the end
188 * of the bridges chain, for instance when the first bridge in the chain
189 * performs scaling. The adjusted mode is mostly useful for the first
190 * bridge in the chain and is likely irrelevant for the other bridges.
191 *
192 * For atomic drivers the adjusted_mode is the mode stored in
193 * &drm_crtc_state.adjusted_mode.
194 *
195 * NOTE:
196 *
197 * If a need arises to store and access modes adjusted for other
198 * locations than the connection between the CRTC and the first bridge,
199 * the DRM framework will have to be extended with DRM bridge states.
200 */
201 void (*mode_set)(struct drm_bridge *bridge,
202 const struct drm_display_mode *mode,
203 const struct drm_display_mode *adjusted_mode);
204 /**
205 * @pre_enable:
206 *
207 * This callback should enable the bridge. It is called right before
208 * the preceding element in the display pipe is enabled. If the
209 * preceding element is a bridge this means it's called before that
210 * bridge's @pre_enable function. If the preceding element is a
211 * &drm_encoder it's called right before the encoder's
212 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
213 * &drm_encoder_helper_funcs.dpms hook.
214 *
215 * The display pipe (i.e. clocks and timing signals) feeding this bridge
216 * will not yet be running when this callback is called. The bridge must
217 * not enable the display link feeding the next bridge in the chain (if
218 * there is one) when this callback is called.
219 *
220 * The @pre_enable callback is optional.
221 */
222 void (*pre_enable)(struct drm_bridge *bridge);
223
224 /**
225 * @enable:
226 *
227 * This callback should enable the bridge. It is called right after
228 * the preceding element in the display pipe is enabled. If the
229 * preceding element is a bridge this means it's called after that
230 * bridge's @enable function. If the preceding element is a
231 * &drm_encoder it's called right after the encoder's
232 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
233 * &drm_encoder_helper_funcs.dpms hook.
234 *
235 * The bridge can assume that the display pipe (i.e. clocks and timing
236 * signals) feeding it is running when this callback is called. This
237 * callback must enable the display link feeding the next bridge in the
238 * chain if there is one.
239 *
240 * The @enable callback is optional.
241 */
242 void (*enable)(struct drm_bridge *bridge);
243
244 /**
245 * @atomic_pre_enable:
246 *
247 * This callback should enable the bridge. It is called right before
248 * the preceding element in the display pipe is enabled. If the
249 * preceding element is a bridge this means it's called before that
250 * bridge's @atomic_pre_enable or @pre_enable function. If the preceding
251 * element is a &drm_encoder it's called right before the encoder's
252 * &drm_encoder_helper_funcs.atomic_enable hook.
253 *
254 * The display pipe (i.e. clocks and timing signals) feeding this bridge
255 * will not yet be running when this callback is called. The bridge must
256 * not enable the display link feeding the next bridge in the chain (if
257 * there is one) when this callback is called.
258 *
259 * Note that this function will only be invoked in the context of an
260 * atomic commit. It will not be invoked from
261 * &drm_bridge_chain_pre_enable. It would be prudent to also provide an
262 * implementation of @pre_enable if you are expecting driver calls into
263 * &drm_bridge_chain_pre_enable.
264 *
265 * The @atomic_pre_enable callback is optional.
266 */
267 void (*atomic_pre_enable)(struct drm_bridge *bridge,
268 struct drm_atomic_state *old_state);
269
270 /**
271 * @atomic_enable:
272 *
273 * This callback should enable the bridge. It is called right after
274 * the preceding element in the display pipe is enabled. If the
275 * preceding element is a bridge this means it's called after that
276 * bridge's @atomic_enable or @enable function. If the preceding element
277 * is a &drm_encoder it's called right after the encoder's
278 * &drm_encoder_helper_funcs.atomic_enable hook.
279 *
280 * The bridge can assume that the display pipe (i.e. clocks and timing
281 * signals) feeding it is running when this callback is called. This
282 * callback must enable the display link feeding the next bridge in the
283 * chain if there is one.
284 *
285 * Note that this function will only be invoked in the context of an
286 * atomic commit. It will not be invoked from &drm_bridge_chain_enable.
287 * It would be prudent to also provide an implementation of @enable if
288 * you are expecting driver calls into &drm_bridge_chain_enable.
289 *
290 * The @atomic_enable callback is optional.
291 */
292 void (*atomic_enable)(struct drm_bridge *bridge,
293 struct drm_atomic_state *old_state);
294 /**
295 * @atomic_disable:
296 *
297 * This callback should disable the bridge. It is called right before
298 * the preceding element in the display pipe is disabled. If the
299 * preceding element is a bridge this means it's called before that
300 * bridge's @atomic_disable or @disable vfunc. If the preceding element
301 * is a &drm_encoder it's called right before the
302 * &drm_encoder_helper_funcs.atomic_disable hook.
303 *
304 * The bridge can assume that the display pipe (i.e. clocks and timing
305 * signals) feeding it is still running when this callback is called.
306 *
307 * Note that this function will only be invoked in the context of an
308 * atomic commit. It will not be invoked from
309 * &drm_bridge_chain_disable. It would be prudent to also provide an
310 * implementation of @disable if you are expecting driver calls into
311 * &drm_bridge_chain_disable.
312 *
313 * The @atomic_disable callback is optional.
314 */
315 void (*atomic_disable)(struct drm_bridge *bridge,
316 struct drm_atomic_state *old_state);
317
318 /**
319 * @atomic_post_disable:
320 *
321 * This callback should disable the bridge. It is called right after the
322 * preceding element in the display pipe is disabled. If the preceding
323 * element is a bridge this means it's called after that bridge's
324 * @atomic_post_disable or @post_disable function. If the preceding
325 * element is a &drm_encoder it's called right after the encoder's
326 * &drm_encoder_helper_funcs.atomic_disable hook.
327 *
328 * The bridge must assume that the display pipe (i.e. clocks and timing
329 * signals) feeding it is no longer running when this callback is
330 * called.
331 *
332 * Note that this function will only be invoked in the context of an
333 * atomic commit. It will not be invoked from
334 * &drm_bridge_chain_post_disable.
335 * It would be prudent to also provide an implementation of
336 * @post_disable if you are expecting driver calls into
337 * &drm_bridge_chain_post_disable.
338 *
339 * The @atomic_post_disable callback is optional.
340 */
341 void (*atomic_post_disable)(struct drm_bridge *bridge,
342 struct drm_atomic_state *old_state);
343 };
344
345 /**
346 * struct drm_bridge_timings - timing information for the bridge
347 */
348 struct drm_bridge_timings {
349 /**
350 * @input_bus_flags:
351 *
352 * Tells what additional settings for the pixel data on the bus
353 * this bridge requires (like pixel signal polarity). See also
354 * &drm_display_info->bus_flags.
355 */
356 u32 input_bus_flags;
357 /**
358 * @setup_time_ps:
359 *
360 * Defines the time in picoseconds the input data lines must be
361 * stable before the clock edge.
362 */
363 u32 setup_time_ps;
364 /**
365 * @hold_time_ps:
366 *
367 * Defines the time in picoseconds taken for the bridge to sample the
368 * input signal after the clock edge.
369 */
370 u32 hold_time_ps;
371 /**
372 * @dual_link:
373 *
374 * True if the bus operates in dual-link mode. The exact meaning is
375 * dependent on the bus type. For LVDS buses, this indicates that even-
376 * and odd-numbered pixels are received on separate links.
377 */
378 bool dual_link;
379 };
380
381 /**
382 * struct drm_bridge - central DRM bridge control structure
383 */
384 struct drm_bridge {
385 /** @dev: DRM device this bridge belongs to */
386 struct drm_device *dev;
387 /** @encoder: encoder to which this bridge is connected */
388 struct drm_encoder *encoder;
389 /** @chain_node: used to form a bridge chain */
390 struct list_head chain_node;
391 #ifdef CONFIG_OF
392 /** @of_node: device node pointer to the bridge */
393 struct device_node *of_node;
394 #endif
395 /** @list: to keep track of all added bridges */
396 struct list_head list;
397 /**
398 * @timings:
399 *
400 * the timing specification for the bridge, if any (may be NULL)
401 */
402 const struct drm_bridge_timings *timings;
403 /** @funcs: control functions */
404 const struct drm_bridge_funcs *funcs;
405 /** @driver_private: pointer to the bridge driver's internal context */
406 void *driver_private;
407 };
408
409 void drm_bridge_add(struct drm_bridge *bridge);
410 void drm_bridge_remove(struct drm_bridge *bridge);
411 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
412 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
413 struct drm_bridge *previous);
414
415 /**
416 * drm_bridge_get_next_bridge() - Get the next bridge in the chain
417 * @bridge: bridge object
418 *
419 * RETURNS:
420 * the next bridge in the chain after @bridge, or NULL if @bridge is the last.
421 */
422 static inline struct drm_bridge *
drm_bridge_get_next_bridge(struct drm_bridge * bridge)423 drm_bridge_get_next_bridge(struct drm_bridge *bridge)
424 {
425 if (list_is_last(&bridge->chain_node, &bridge->encoder->bridge_chain))
426 return NULL;
427
428 return list_next_entry(bridge, chain_node);
429 }
430
431 /**
432 * drm_bridge_get_prev_bridge() - Get the previous bridge in the chain
433 * @bridge: bridge object
434 *
435 * RETURNS:
436 * the previous bridge in the chain, or NULL if @bridge is the first.
437 */
438 static inline struct drm_bridge *
drm_bridge_get_prev_bridge(struct drm_bridge * bridge)439 drm_bridge_get_prev_bridge(struct drm_bridge *bridge)
440 {
441 if (list_is_first(&bridge->chain_node, &bridge->encoder->bridge_chain))
442 return NULL;
443
444 return list_prev_entry(bridge, chain_node);
445 }
446
447 /**
448 * drm_bridge_chain_get_first_bridge() - Get the first bridge in the chain
449 * @encoder: encoder object
450 *
451 * RETURNS:
452 * the first bridge in the chain, or NULL if @encoder has no bridge attached
453 * to it.
454 */
455 static inline struct drm_bridge *
drm_bridge_chain_get_first_bridge(struct drm_encoder * encoder)456 drm_bridge_chain_get_first_bridge(struct drm_encoder *encoder)
457 {
458 return list_first_entry_or_null(&encoder->bridge_chain,
459 struct drm_bridge, chain_node);
460 }
461
462 /**
463 * drm_for_each_bridge_in_chain() - Iterate over all bridges present in a chain
464 * @encoder: the encoder to iterate bridges on
465 * @bridge: a bridge pointer updated to point to the current bridge at each
466 * iteration
467 *
468 * Iterate over all bridges present in the bridge chain attached to @encoder.
469 */
470 #define drm_for_each_bridge_in_chain(encoder, bridge) \
471 list_for_each_entry(bridge, &(encoder)->bridge_chain, chain_node)
472
473 bool drm_bridge_chain_mode_fixup(struct drm_bridge *bridge,
474 const struct drm_display_mode *mode,
475 struct drm_display_mode *adjusted_mode);
476 enum drm_mode_status
477 drm_bridge_chain_mode_valid(struct drm_bridge *bridge,
478 const struct drm_display_mode *mode);
479 void drm_bridge_chain_disable(struct drm_bridge *bridge);
480 void drm_bridge_chain_post_disable(struct drm_bridge *bridge);
481 void drm_bridge_chain_mode_set(struct drm_bridge *bridge,
482 const struct drm_display_mode *mode,
483 const struct drm_display_mode *adjusted_mode);
484 void drm_bridge_chain_pre_enable(struct drm_bridge *bridge);
485 void drm_bridge_chain_enable(struct drm_bridge *bridge);
486
487 void drm_atomic_bridge_chain_disable(struct drm_bridge *bridge,
488 struct drm_atomic_state *state);
489 void drm_atomic_bridge_chain_post_disable(struct drm_bridge *bridge,
490 struct drm_atomic_state *state);
491 void drm_atomic_bridge_chain_pre_enable(struct drm_bridge *bridge,
492 struct drm_atomic_state *state);
493 void drm_atomic_bridge_chain_enable(struct drm_bridge *bridge,
494 struct drm_atomic_state *state);
495
496 #ifdef CONFIG_DRM_PANEL_BRIDGE
497 struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel);
498 struct drm_bridge *drm_panel_bridge_add_typed(struct drm_panel *panel,
499 u32 connector_type);
500 void drm_panel_bridge_remove(struct drm_bridge *bridge);
501 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev,
502 struct drm_panel *panel);
503 struct drm_bridge *devm_drm_panel_bridge_add_typed(struct device *dev,
504 struct drm_panel *panel,
505 u32 connector_type);
506 struct drm_connector *drm_panel_bridge_connector(struct drm_bridge *bridge);
507 #endif
508
509 #ifdef __NetBSD__
510 extern void drm_bridge_init_lock(void);
511 extern void drm_bridge_fini_lock(void);
512 #endif
513
514 #endif
515