2 * Copyright (c) 2016 Intel Corporation
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.
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
23 #ifndef __DRM_BRIDGE_H__
24 #define __DRM_BRIDGE_H__
26 #include <linux/list.h>
27 #include <linux/ctype.h>
29 #include <drm/drm_atomic.h>
30 #include <drm/drm_encoder.h>
31 #include <drm/drm_mode_object.h>
32 #include <drm/drm_modes.h>
35 struct drm_bridge_timings;
39 * struct drm_bridge_state - Atomic bridge state object
40 * @base: inherit from &drm_private_state
41 * @bridge: the bridge this state refers to
43 struct drm_bridge_state {
44 struct drm_private_state base;
46 struct drm_bridge *bridge;
49 static inline struct drm_bridge_state *
50 drm_priv_to_bridge_state(struct drm_private_state *priv)
52 return container_of(priv, struct drm_bridge_state, base);
56 * struct drm_bridge_funcs - drm_bridge control functions
58 struct drm_bridge_funcs {
62 * This callback is invoked whenever our bridge is being attached to a
65 * The @attach callback is optional.
69 * Zero on success, error code on failure.
71 int (*attach)(struct drm_bridge *bridge);
76 * This callback is invoked whenever our bridge is being detached from a
79 * The @detach callback is optional.
81 void (*detach)(struct drm_bridge *bridge);
86 * This callback is used to check if a specific mode is valid in this
87 * bridge. This should be implemented if the bridge has some sort of
88 * restriction in the modes it can display. For example, a given bridge
89 * may be responsible to set a clock value. If the clock can not
90 * produce all the values for the available modes then this callback
91 * can be used to restrict the number of modes to only the ones that
94 * This hook is used by the probe helpers to filter the mode list in
95 * drm_helper_probe_single_connector_modes(), and it is used by the
96 * atomic helpers to validate modes supplied by userspace in
97 * drm_atomic_helper_check_modeset().
99 * The @mode_valid callback is optional.
103 * Since this function is both called from the check phase of an atomic
104 * commit, and the mode validation in the probe paths it is not allowed
105 * to look at anything else but the passed-in mode, and validate it
106 * against configuration-invariant hardward constraints. Any further
107 * limits which depend upon the configuration can only be checked in
112 * drm_mode_status Enum
114 enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge,
115 const struct drm_display_mode *mode);
120 * This callback is used to validate and adjust a mode. The parameter
121 * mode is the display mode that should be fed to the next element in
122 * the display chain, either the final &drm_connector or the next
123 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
124 * requires. It can be modified by this callback and does not need to
125 * match mode. See also &drm_crtc_state.adjusted_mode for more details.
127 * This is the only hook that allows a bridge to reject a modeset. If
128 * this function passes all other callbacks must succeed for this
131 * The mode_fixup callback is optional. &drm_bridge_funcs.mode_fixup()
132 * is not called when &drm_bridge_funcs.atomic_check() is implemented,
133 * so only one of them should be provided.
137 * This function is called in the check phase of atomic modesets, which
138 * can be aborted for any reason (including on userspace's request to
139 * just check whether a configuration would be possible). Drivers MUST
140 * NOT touch any persistent state (hardware or software) or data
141 * structures except the passed in @state parameter.
143 * Also beware that userspace can request its own custom modes, neither
144 * core nor helpers filter modes to the list of probe modes reported by
145 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
146 * that modes are filtered consistently put any bridge constraints and
147 * limits checks into @mode_valid.
151 * True if an acceptable configuration is possible, false if the modeset
152 * operation should be rejected.
154 bool (*mode_fixup)(struct drm_bridge *bridge,
155 const struct drm_display_mode *mode,
156 struct drm_display_mode *adjusted_mode);
160 * This callback should disable the bridge. It is called right before
161 * the preceding element in the display pipe is disabled. If the
162 * preceding element is a bridge this means it's called before that
163 * bridge's @disable vfunc. If the preceding element is a &drm_encoder
164 * it's called right before the &drm_encoder_helper_funcs.disable,
165 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
168 * The bridge can assume that the display pipe (i.e. clocks and timing
169 * signals) feeding it is still running when this callback is called.
171 * The @disable callback is optional.
173 void (*disable)(struct drm_bridge *bridge);
178 * This callback should disable the bridge. It is called right after the
179 * preceding element in the display pipe is disabled. If the preceding
180 * element is a bridge this means it's called after that bridge's
181 * @post_disable function. If the preceding element is a &drm_encoder
182 * it's called right after the encoder's
183 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
184 * or &drm_encoder_helper_funcs.dpms hook.
186 * The bridge must assume that the display pipe (i.e. clocks and timing
187 * singals) feeding it is no longer running when this callback is
190 * The @post_disable callback is optional.
192 void (*post_disable)(struct drm_bridge *bridge);
197 * This callback should set the given mode on the bridge. It is called
198 * after the @mode_set callback for the preceding element in the display
199 * pipeline has been called already. If the bridge is the first element
200 * then this would be &drm_encoder_helper_funcs.mode_set. The display
201 * pipe (i.e. clocks and timing signals) is off when this function is
204 * The adjusted_mode parameter is the mode output by the CRTC for the
205 * first bridge in the chain. It can be different from the mode
206 * parameter that contains the desired mode for the connector at the end
207 * of the bridges chain, for instance when the first bridge in the chain
208 * performs scaling. The adjusted mode is mostly useful for the first
209 * bridge in the chain and is likely irrelevant for the other bridges.
211 * For atomic drivers the adjusted_mode is the mode stored in
212 * &drm_crtc_state.adjusted_mode.
216 * If a need arises to store and access modes adjusted for other
217 * locations than the connection between the CRTC and the first bridge,
218 * the DRM framework will have to be extended with DRM bridge states.
220 void (*mode_set)(struct drm_bridge *bridge,
221 const struct drm_display_mode *mode,
222 const struct drm_display_mode *adjusted_mode);
226 * This callback should enable the bridge. It is called right before
227 * the preceding element in the display pipe is enabled. If the
228 * preceding element is a bridge this means it's called before that
229 * bridge's @pre_enable function. If the preceding element is a
230 * &drm_encoder it's called right before the encoder's
231 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
232 * &drm_encoder_helper_funcs.dpms hook.
234 * The display pipe (i.e. clocks and timing signals) feeding this bridge
235 * will not yet be running when this callback is called. The bridge must
236 * not enable the display link feeding the next bridge in the chain (if
237 * there is one) when this callback is called.
239 * The @pre_enable callback is optional.
241 void (*pre_enable)(struct drm_bridge *bridge);
246 * This callback should enable the bridge. It is called right after
247 * the preceding element in the display pipe is enabled. If the
248 * preceding element is a bridge this means it's called after that
249 * bridge's @enable function. If the preceding element is a
250 * &drm_encoder it's called right after the encoder's
251 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
252 * &drm_encoder_helper_funcs.dpms hook.
254 * The bridge can assume that the display pipe (i.e. clocks and timing
255 * signals) feeding it is running when this callback is called. This
256 * callback must enable the display link feeding the next bridge in the
257 * chain if there is one.
259 * The @enable callback is optional.
261 void (*enable)(struct drm_bridge *bridge);
264 * @atomic_pre_enable:
266 * This callback should enable the bridge. It is called right before
267 * the preceding element in the display pipe is enabled. If the
268 * preceding element is a bridge this means it's called before that
269 * bridge's @atomic_pre_enable or @pre_enable function. If the preceding
270 * element is a &drm_encoder it's called right before the encoder's
271 * &drm_encoder_helper_funcs.atomic_enable hook.
273 * The display pipe (i.e. clocks and timing signals) feeding this bridge
274 * will not yet be running when this callback is called. The bridge must
275 * not enable the display link feeding the next bridge in the chain (if
276 * there is one) when this callback is called.
278 * Note that this function will only be invoked in the context of an
279 * atomic commit. It will not be invoked from
280 * &drm_bridge_chain_pre_enable. It would be prudent to also provide an
281 * implementation of @pre_enable if you are expecting driver calls into
282 * &drm_bridge_chain_pre_enable.
284 * The @atomic_pre_enable callback is optional.
286 void (*atomic_pre_enable)(struct drm_bridge *bridge,
287 struct drm_bridge_state *old_bridge_state);
292 * This callback should enable the bridge. It is called right after
293 * the preceding element in the display pipe is enabled. If the
294 * preceding element is a bridge this means it's called after that
295 * bridge's @atomic_enable or @enable function. If the preceding element
296 * is a &drm_encoder it's called right after the encoder's
297 * &drm_encoder_helper_funcs.atomic_enable hook.
299 * The bridge can assume that the display pipe (i.e. clocks and timing
300 * signals) feeding it is running when this callback is called. This
301 * callback must enable the display link feeding the next bridge in the
302 * chain if there is one.
304 * Note that this function will only be invoked in the context of an
305 * atomic commit. It will not be invoked from &drm_bridge_chain_enable.
306 * It would be prudent to also provide an implementation of @enable if
307 * you are expecting driver calls into &drm_bridge_chain_enable.
309 * The @atomic_enable callback is optional.
311 void (*atomic_enable)(struct drm_bridge *bridge,
312 struct drm_bridge_state *old_bridge_state);
316 * This callback should disable the bridge. It is called right before
317 * the preceding element in the display pipe is disabled. If the
318 * preceding element is a bridge this means it's called before that
319 * bridge's @atomic_disable or @disable vfunc. If the preceding element
320 * is a &drm_encoder it's called right before the
321 * &drm_encoder_helper_funcs.atomic_disable hook.
323 * The bridge can assume that the display pipe (i.e. clocks and timing
324 * signals) feeding it is still running when this callback is called.
326 * Note that this function will only be invoked in the context of an
327 * atomic commit. It will not be invoked from
328 * &drm_bridge_chain_disable. It would be prudent to also provide an
329 * implementation of @disable if you are expecting driver calls into
330 * &drm_bridge_chain_disable.
332 * The @atomic_disable callback is optional.
334 void (*atomic_disable)(struct drm_bridge *bridge,
335 struct drm_bridge_state *old_bridge_state);
338 * @atomic_post_disable:
340 * This callback should disable the bridge. It is called right after the
341 * preceding element in the display pipe is disabled. If the preceding
342 * element is a bridge this means it's called after that bridge's
343 * @atomic_post_disable or @post_disable function. If the preceding
344 * element is a &drm_encoder it's called right after the encoder's
345 * &drm_encoder_helper_funcs.atomic_disable hook.
347 * The bridge must assume that the display pipe (i.e. clocks and timing
348 * signals) feeding it is no longer running when this callback is
351 * Note that this function will only be invoked in the context of an
352 * atomic commit. It will not be invoked from
353 * &drm_bridge_chain_post_disable.
354 * It would be prudent to also provide an implementation of
355 * @post_disable if you are expecting driver calls into
356 * &drm_bridge_chain_post_disable.
358 * The @atomic_post_disable callback is optional.
360 void (*atomic_post_disable)(struct drm_bridge *bridge,
361 struct drm_bridge_state *old_bridge_state);
364 * @atomic_duplicate_state:
366 * Duplicate the current bridge state object (which is guaranteed to be
369 * The atomic_duplicate_state() is optional. When not implemented the
370 * core allocates a drm_bridge_state object and calls
371 * &__drm_atomic_helper_bridge_duplicate_state() to initialize it.
374 * A valid drm_bridge_state object or NULL if the allocation fails.
376 struct drm_bridge_state *(*atomic_duplicate_state)(struct drm_bridge *bridge);
379 * @atomic_destroy_state:
381 * Destroy a bridge state object previously allocated by
382 * &drm_bridge_funcs.atomic_duplicate_state().
384 * The atomic_destroy_state hook is optional. When not implemented the
385 * core calls kfree() on the state.
387 void (*atomic_destroy_state)(struct drm_bridge *bridge,
388 struct drm_bridge_state *state);
393 * This method is responsible for checking bridge state correctness.
394 * It can also check the state of the surrounding components in chain
395 * to make sure the whole pipeline can work properly.
397 * &drm_bridge_funcs.atomic_check() hooks are called in reverse
398 * order (from the last to the first bridge).
400 * This method is optional. &drm_bridge_funcs.mode_fixup() is not
401 * called when &drm_bridge_funcs.atomic_check() is implemented, so only
402 * one of them should be provided.
405 * zero if the check passed, a negative error code otherwise.
407 int (*atomic_check)(struct drm_bridge *bridge,
408 struct drm_bridge_state *bridge_state,
409 struct drm_crtc_state *crtc_state,
410 struct drm_connector_state *conn_state);
415 * Reset the bridge to a predefined state (or retrieve its current
416 * state) and return a &drm_bridge_state object matching this state.
417 * This function is called at attach time.
419 * The atomic_reset hook is optional. When not implemented the core
420 * allocates a new state and calls &__drm_atomic_helper_bridge_reset().
423 * A valid drm_bridge_state object in case of success, an ERR_PTR()
424 * giving the reason of the failure otherwise.
426 struct drm_bridge_state *(*atomic_reset)(struct drm_bridge *bridge);
430 * struct drm_bridge_timings - timing information for the bridge
432 struct drm_bridge_timings {
436 * Tells what additional settings for the pixel data on the bus
437 * this bridge requires (like pixel signal polarity). See also
438 * &drm_display_info->bus_flags.
444 * Defines the time in picoseconds the input data lines must be
445 * stable before the clock edge.
451 * Defines the time in picoseconds taken for the bridge to sample the
452 * input signal after the clock edge.
458 * True if the bus operates in dual-link mode. The exact meaning is
459 * dependent on the bus type. For LVDS buses, this indicates that even-
460 * and odd-numbered pixels are received on separate links.
466 * struct drm_bridge - central DRM bridge control structure
469 /** @base: inherit from &drm_private_object */
470 struct drm_private_obj base;
471 /** @dev: DRM device this bridge belongs to */
472 struct drm_device *dev;
473 /** @encoder: encoder to which this bridge is connected */
474 struct drm_encoder *encoder;
475 /** @chain_node: used to form a bridge chain */
476 struct list_head chain_node;
478 /** @of_node: device node pointer to the bridge */
479 struct device_node *of_node;
481 /** @list: to keep track of all added bridges */
482 struct list_head list;
486 * the timing specification for the bridge, if any (may be NULL)
488 const struct drm_bridge_timings *timings;
489 /** @funcs: control functions */
490 const struct drm_bridge_funcs *funcs;
491 /** @driver_private: pointer to the bridge driver's internal context */
492 void *driver_private;
495 static inline struct drm_bridge *
496 drm_priv_to_bridge(struct drm_private_obj *priv)
498 return container_of(priv, struct drm_bridge, base);
501 void drm_bridge_add(struct drm_bridge *bridge);
502 void drm_bridge_remove(struct drm_bridge *bridge);
503 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
504 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
505 struct drm_bridge *previous);
508 * drm_bridge_get_next_bridge() - Get the next bridge in the chain
509 * @bridge: bridge object
512 * the next bridge in the chain after @bridge, or NULL if @bridge is the last.
514 static inline struct drm_bridge *
515 drm_bridge_get_next_bridge(struct drm_bridge *bridge)
517 if (list_is_last(&bridge->chain_node, &bridge->encoder->bridge_chain))
520 return list_next_entry(bridge, chain_node);
524 * drm_bridge_get_prev_bridge() - Get the previous bridge in the chain
525 * @bridge: bridge object
528 * the previous bridge in the chain, or NULL if @bridge is the first.
530 static inline struct drm_bridge *
531 drm_bridge_get_prev_bridge(struct drm_bridge *bridge)
533 if (list_is_first(&bridge->chain_node, &bridge->encoder->bridge_chain))
536 return list_prev_entry(bridge, chain_node);
540 * drm_bridge_chain_get_first_bridge() - Get the first bridge in the chain
541 * @encoder: encoder object
544 * the first bridge in the chain, or NULL if @encoder has no bridge attached
547 static inline struct drm_bridge *
548 drm_bridge_chain_get_first_bridge(struct drm_encoder *encoder)
550 return list_first_entry_or_null(&encoder->bridge_chain,
551 struct drm_bridge, chain_node);
555 * drm_for_each_bridge_in_chain() - Iterate over all bridges present in a chain
556 * @encoder: the encoder to iterate bridges on
557 * @bridge: a bridge pointer updated to point to the current bridge at each
560 * Iterate over all bridges present in the bridge chain attached to @encoder.
562 #define drm_for_each_bridge_in_chain(encoder, bridge) \
563 list_for_each_entry(bridge, &(encoder)->bridge_chain, chain_node)
565 bool drm_bridge_chain_mode_fixup(struct drm_bridge *bridge,
566 const struct drm_display_mode *mode,
567 struct drm_display_mode *adjusted_mode);
569 drm_bridge_chain_mode_valid(struct drm_bridge *bridge,
570 const struct drm_display_mode *mode);
571 void drm_bridge_chain_disable(struct drm_bridge *bridge);
572 void drm_bridge_chain_post_disable(struct drm_bridge *bridge);
573 void drm_bridge_chain_mode_set(struct drm_bridge *bridge,
574 const struct drm_display_mode *mode,
575 const struct drm_display_mode *adjusted_mode);
576 void drm_bridge_chain_pre_enable(struct drm_bridge *bridge);
577 void drm_bridge_chain_enable(struct drm_bridge *bridge);
579 int drm_atomic_bridge_chain_check(struct drm_bridge *bridge,
580 struct drm_crtc_state *crtc_state,
581 struct drm_connector_state *conn_state);
582 void drm_atomic_bridge_chain_disable(struct drm_bridge *bridge,
583 struct drm_atomic_state *state);
584 void drm_atomic_bridge_chain_post_disable(struct drm_bridge *bridge,
585 struct drm_atomic_state *state);
586 void drm_atomic_bridge_chain_pre_enable(struct drm_bridge *bridge,
587 struct drm_atomic_state *state);
588 void drm_atomic_bridge_chain_enable(struct drm_bridge *bridge,
589 struct drm_atomic_state *state);
591 void __drm_atomic_helper_bridge_reset(struct drm_bridge *bridge,
592 struct drm_bridge_state *state);
593 void __drm_atomic_helper_bridge_duplicate_state(struct drm_bridge *bridge,
594 struct drm_bridge_state *new);
596 static inline struct drm_bridge_state *
597 drm_atomic_get_bridge_state(struct drm_atomic_state *state,
598 struct drm_bridge *bridge)
600 struct drm_private_state *obj_state;
602 obj_state = drm_atomic_get_private_obj_state(state, &bridge->base);
603 if (IS_ERR(obj_state))
604 return ERR_CAST(obj_state);
606 return drm_priv_to_bridge_state(obj_state);
609 static inline struct drm_bridge_state *
610 drm_atomic_get_old_bridge_state(struct drm_atomic_state *state,
611 struct drm_bridge *bridge)
613 struct drm_private_state *obj_state;
615 obj_state = drm_atomic_get_old_private_obj_state(state, &bridge->base);
619 return drm_priv_to_bridge_state(obj_state);
622 static inline struct drm_bridge_state *
623 drm_atomic_get_new_bridge_state(struct drm_atomic_state *state,
624 struct drm_bridge *bridge)
626 struct drm_private_state *obj_state;
628 obj_state = drm_atomic_get_new_private_obj_state(state, &bridge->base);
632 return drm_priv_to_bridge_state(obj_state);
635 #ifdef CONFIG_DRM_PANEL_BRIDGE
636 struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel);
637 struct drm_bridge *drm_panel_bridge_add_typed(struct drm_panel *panel,
639 void drm_panel_bridge_remove(struct drm_bridge *bridge);
640 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev,
641 struct drm_panel *panel);
642 struct drm_bridge *devm_drm_panel_bridge_add_typed(struct device *dev,
643 struct drm_panel *panel,
645 struct drm_connector *drm_panel_bridge_connector(struct drm_bridge *bridge);