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>
28 #include <drm/drm_mode_object.h>
29 #include <drm/drm_modes.h>
34 * struct drm_bridge_funcs - drm_bridge control functions
36 struct drm_bridge_funcs
{
40 * This callback is invoked whenever our bridge is being attached to a
43 * The attach callback is optional.
47 * Zero on success, error code on failure.
49 int (*attach
)(struct drm_bridge
*bridge
);
54 * This callback is invoked whenever our bridge is being detached from a
57 * The detach callback is optional.
59 void (*detach
)(struct drm_bridge
*bridge
);
64 * This callback is used to check if a specific mode is valid in this
65 * bridge. This should be implemented if the bridge has some sort of
66 * restriction in the modes it can display. For example, a given bridge
67 * may be responsible to set a clock value. If the clock can not
68 * produce all the values for the available modes then this callback
69 * can be used to restrict the number of modes to only the ones that
72 * This hook is used by the probe helpers to filter the mode list in
73 * drm_helper_probe_single_connector_modes(), and it is used by the
74 * atomic helpers to validate modes supplied by userspace in
75 * drm_atomic_helper_check_modeset().
77 * This function is optional.
81 * Since this function is both called from the check phase of an atomic
82 * commit, and the mode validation in the probe paths it is not allowed
83 * to look at anything else but the passed-in mode, and validate it
84 * against configuration-invariant hardward constraints. Any further
85 * limits which depend upon the configuration can only be checked in
90 * drm_mode_status Enum
92 enum drm_mode_status (*mode_valid
)(struct drm_bridge
*crtc
,
93 const struct drm_display_mode
*mode
);
98 * This callback is used to validate and adjust a mode. The paramater
99 * mode is the display mode that should be fed to the next element in
100 * the display chain, either the final &drm_connector or the next
101 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
102 * requires. It can be modified by this callback and does not need to
105 * This is the only hook that allows a bridge to reject a modeset. If
106 * this function passes all other callbacks must succeed for this
109 * The mode_fixup callback is optional.
113 * This function is called in the check phase of atomic modesets, which
114 * can be aborted for any reason (including on userspace's request to
115 * just check whether a configuration would be possible). Drivers MUST
116 * NOT touch any persistent state (hardware or software) or data
117 * structures except the passed in @state parameter.
119 * Also beware that userspace can request its own custom modes, neither
120 * core nor helpers filter modes to the list of probe modes reported by
121 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
122 * that modes are filtered consistently put any bridge constraints and
123 * limits checks into @mode_valid.
127 * True if an acceptable configuration is possible, false if the modeset
128 * operation should be rejected.
130 bool (*mode_fixup
)(struct drm_bridge
*bridge
,
131 const struct drm_display_mode
*mode
,
132 struct drm_display_mode
*adjusted_mode
);
136 * This callback should disable the bridge. It is called right before
137 * the preceding element in the display pipe is disabled. If the
138 * preceding element is a bridge this means it's called before that
139 * bridge's @disable vfunc. If the preceding element is a &drm_encoder
140 * it's called right before the &drm_encoder_helper_funcs.disable,
141 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
144 * The bridge can assume that the display pipe (i.e. clocks and timing
145 * signals) feeding it is still running when this callback is called.
147 * The disable callback is optional.
149 void (*disable
)(struct drm_bridge
*bridge
);
154 * This callback should disable the bridge. It is called right after the
155 * preceding element in the display pipe is disabled. If the preceding
156 * element is a bridge this means it's called after that bridge's
157 * @post_disable function. If the preceding element is a &drm_encoder
158 * it's called right after the encoder's
159 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
160 * or &drm_encoder_helper_funcs.dpms hook.
162 * The bridge must assume that the display pipe (i.e. clocks and timing
163 * singals) feeding it is no longer running when this callback is
166 * The post_disable callback is optional.
168 void (*post_disable
)(struct drm_bridge
*bridge
);
173 * This callback should set the given mode on the bridge. It is called
174 * after the @mode_set callback for the preceding element in the display
175 * pipeline has been called already. If the bridge is the first element
176 * then this would be &drm_encoder_helper_funcs.mode_set. The display
177 * pipe (i.e. clocks and timing signals) is off when this function is
180 void (*mode_set
)(struct drm_bridge
*bridge
,
181 struct drm_display_mode
*mode
,
182 struct drm_display_mode
*adjusted_mode
);
186 * This callback should enable the bridge. It is called right before
187 * the preceding element in the display pipe is enabled. If the
188 * preceding element is a bridge this means it's called before that
189 * bridge's @pre_enable function. If the preceding element is a
190 * &drm_encoder it's called right before the encoder's
191 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
192 * &drm_encoder_helper_funcs.dpms hook.
194 * The display pipe (i.e. clocks and timing signals) feeding this bridge
195 * will not yet be running when this callback is called. The bridge must
196 * not enable the display link feeding the next bridge in the chain (if
197 * there is one) when this callback is called.
199 * The pre_enable callback is optional.
201 void (*pre_enable
)(struct drm_bridge
*bridge
);
206 * This callback should enable the bridge. It is called right after
207 * the preceding element in the display pipe is enabled. If the
208 * preceding element is a bridge this means it's called after that
209 * bridge's @enable function. If the preceding element is a
210 * &drm_encoder it's called right after the encoder's
211 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
212 * &drm_encoder_helper_funcs.dpms hook.
214 * The bridge can assume that the display pipe (i.e. clocks and timing
215 * signals) feeding it is running when this callback is called. This
216 * callback must enable the display link feeding the next bridge in the
217 * chain if there is one.
219 * The enable callback is optional.
221 void (*enable
)(struct drm_bridge
*bridge
);
225 * struct drm_bridge - central DRM bridge control structure
226 * @dev: DRM device this bridge belongs to
227 * @encoder: encoder to which this bridge is connected
228 * @next: the next bridge in the encoder chain
229 * @of_node: device node pointer to the bridge
230 * @list: to keep track of all added bridges
231 * @funcs: control functions
232 * @driver_private: pointer to the bridge driver's internal context
235 struct drm_device
*dev
;
236 struct drm_encoder
*encoder
;
237 struct drm_bridge
*next
;
239 struct device_node
*of_node
;
241 struct list_head list
;
243 const struct drm_bridge_funcs
*funcs
;
244 void *driver_private
;
247 int drm_bridge_add(struct drm_bridge
*bridge
);
248 void drm_bridge_remove(struct drm_bridge
*bridge
);
249 struct drm_bridge
*of_drm_find_bridge(struct device_node
*np
);
250 int drm_bridge_attach(struct drm_encoder
*encoder
, struct drm_bridge
*bridge
,
251 struct drm_bridge
*previous
);
253 bool drm_bridge_mode_fixup(struct drm_bridge
*bridge
,
254 const struct drm_display_mode
*mode
,
255 struct drm_display_mode
*adjusted_mode
);
256 void drm_bridge_disable(struct drm_bridge
*bridge
);
257 void drm_bridge_post_disable(struct drm_bridge
*bridge
);
258 void drm_bridge_mode_set(struct drm_bridge
*bridge
,
259 struct drm_display_mode
*mode
,
260 struct drm_display_mode
*adjusted_mode
);
261 void drm_bridge_pre_enable(struct drm_bridge
*bridge
);
262 void drm_bridge_enable(struct drm_bridge
*bridge
);