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