]>
Commit | Line | Data |
---|---|---|
199e4e96 SV |
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_mode_object.h> | |
29 | #include <drm/drm_modes.h> | |
30 | ||
31 | struct drm_bridge; | |
36a776df | 32 | struct drm_bridge_timings; |
13dfc054 | 33 | struct drm_panel; |
199e4e96 SV |
34 | |
35 | /** | |
36 | * struct drm_bridge_funcs - drm_bridge control functions | |
37 | */ | |
38 | struct drm_bridge_funcs { | |
39 | /** | |
40 | * @attach: | |
41 | * | |
42 | * This callback is invoked whenever our bridge is being attached to a | |
43 | * &drm_encoder. | |
44 | * | |
45 | * The attach callback is optional. | |
46 | * | |
47 | * RETURNS: | |
48 | * | |
49 | * Zero on success, error code on failure. | |
50 | */ | |
51 | int (*attach)(struct drm_bridge *bridge); | |
52 | ||
53 | /** | |
54 | * @detach: | |
55 | * | |
56 | * This callback is invoked whenever our bridge is being detached from a | |
57 | * &drm_encoder. | |
58 | * | |
59 | * The detach callback is optional. | |
60 | */ | |
61 | void (*detach)(struct drm_bridge *bridge); | |
62 | ||
3eb220a5 JA |
63 | /** |
64 | * @mode_valid: | |
65 | * | |
66 | * This callback is used to check if a specific mode is valid in this | |
67 | * bridge. This should be implemented if the bridge has some sort of | |
68 | * restriction in the modes it can display. For example, a given bridge | |
69 | * may be responsible to set a clock value. If the clock can not | |
70 | * produce all the values for the available modes then this callback | |
71 | * can be used to restrict the number of modes to only the ones that | |
72 | * can be displayed. | |
73 | * | |
74 | * This hook is used by the probe helpers to filter the mode list in | |
75 | * drm_helper_probe_single_connector_modes(), and it is used by the | |
76 | * atomic helpers to validate modes supplied by userspace in | |
77 | * drm_atomic_helper_check_modeset(). | |
78 | * | |
79 | * This function is optional. | |
80 | * | |
81 | * NOTE: | |
82 | * | |
83 | * Since this function is both called from the check phase of an atomic | |
84 | * commit, and the mode validation in the probe paths it is not allowed | |
85 | * to look at anything else but the passed-in mode, and validate it | |
86 | * against configuration-invariant hardward constraints. Any further | |
87 | * limits which depend upon the configuration can only be checked in | |
88 | * @mode_fixup. | |
89 | * | |
90 | * RETURNS: | |
91 | * | |
92 | * drm_mode_status Enum | |
93 | */ | |
312924d3 | 94 | enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge, |
3eb220a5 JA |
95 | const struct drm_display_mode *mode); |
96 | ||
199e4e96 SV |
97 | /** |
98 | * @mode_fixup: | |
99 | * | |
5d435b46 | 100 | * This callback is used to validate and adjust a mode. The parameter |
199e4e96 SV |
101 | * mode is the display mode that should be fed to the next element in |
102 | * the display chain, either the final &drm_connector or the next | |
103 | * &drm_bridge. The parameter adjusted_mode is the input mode the bridge | |
104 | * requires. It can be modified by this callback and does not need to | |
9de5d4a6 | 105 | * match mode. See also &drm_crtc_state.adjusted_mode for more details. |
199e4e96 SV |
106 | * |
107 | * This is the only hook that allows a bridge to reject a modeset. If | |
108 | * this function passes all other callbacks must succeed for this | |
109 | * configuration. | |
110 | * | |
111 | * The mode_fixup callback is optional. | |
112 | * | |
113 | * NOTE: | |
114 | * | |
115 | * This function is called in the check phase of atomic modesets, which | |
116 | * can be aborted for any reason (including on userspace's request to | |
117 | * just check whether a configuration would be possible). Drivers MUST | |
118 | * NOT touch any persistent state (hardware or software) or data | |
119 | * structures except the passed in @state parameter. | |
120 | * | |
3eb220a5 JA |
121 | * Also beware that userspace can request its own custom modes, neither |
122 | * core nor helpers filter modes to the list of probe modes reported by | |
123 | * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure | |
124 | * that modes are filtered consistently put any bridge constraints and | |
125 | * limits checks into @mode_valid. | |
126 | * | |
199e4e96 SV |
127 | * RETURNS: |
128 | * | |
129 | * True if an acceptable configuration is possible, false if the modeset | |
130 | * operation should be rejected. | |
131 | */ | |
132 | bool (*mode_fixup)(struct drm_bridge *bridge, | |
133 | const struct drm_display_mode *mode, | |
134 | struct drm_display_mode *adjusted_mode); | |
135 | /** | |
136 | * @disable: | |
137 | * | |
138 | * This callback should disable the bridge. It is called right before | |
139 | * the preceding element in the display pipe is disabled. If the | |
140 | * preceding element is a bridge this means it's called before that | |
4541d31e SV |
141 | * bridge's @disable vfunc. If the preceding element is a &drm_encoder |
142 | * it's called right before the &drm_encoder_helper_funcs.disable, | |
143 | * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms | |
144 | * hook. | |
199e4e96 SV |
145 | * |
146 | * The bridge can assume that the display pipe (i.e. clocks and timing | |
147 | * signals) feeding it is still running when this callback is called. | |
148 | * | |
149 | * The disable callback is optional. | |
150 | */ | |
151 | void (*disable)(struct drm_bridge *bridge); | |
152 | ||
153 | /** | |
154 | * @post_disable: | |
155 | * | |
4541d31e SV |
156 | * This callback should disable the bridge. It is called right after the |
157 | * preceding element in the display pipe is disabled. If the preceding | |
158 | * element is a bridge this means it's called after that bridge's | |
159 | * @post_disable function. If the preceding element is a &drm_encoder | |
160 | * it's called right after the encoder's | |
161 | * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare | |
162 | * or &drm_encoder_helper_funcs.dpms hook. | |
199e4e96 SV |
163 | * |
164 | * The bridge must assume that the display pipe (i.e. clocks and timing | |
165 | * singals) feeding it is no longer running when this callback is | |
166 | * called. | |
167 | * | |
168 | * The post_disable callback is optional. | |
169 | */ | |
170 | void (*post_disable)(struct drm_bridge *bridge); | |
171 | ||
172 | /** | |
173 | * @mode_set: | |
174 | * | |
175 | * This callback should set the given mode on the bridge. It is called | |
4541d31e SV |
176 | * after the @mode_set callback for the preceding element in the display |
177 | * pipeline has been called already. If the bridge is the first element | |
178 | * then this would be &drm_encoder_helper_funcs.mode_set. The display | |
179 | * pipe (i.e. clocks and timing signals) is off when this function is | |
180 | * called. | |
584a0146 PC |
181 | * |
182 | * The adjusted_mode parameter is the mode output by the CRTC for the | |
183 | * first bridge in the chain. It can be different from the mode | |
184 | * parameter that contains the desired mode for the connector at the end | |
185 | * of the bridges chain, for instance when the first bridge in the chain | |
186 | * performs scaling. The adjusted mode is mostly useful for the first | |
187 | * bridge in the chain and is likely irrelevant for the other bridges. | |
188 | * | |
189 | * For atomic drivers the adjusted_mode is the mode stored in | |
190 | * &drm_crtc_state.adjusted_mode. | |
191 | * | |
192 | * NOTE: | |
193 | * | |
194 | * If a need arises to store and access modes adjusted for other | |
195 | * locations than the connection between the CRTC and the first bridge, | |
196 | * the DRM framework will have to be extended with DRM bridge states. | |
199e4e96 SV |
197 | */ |
198 | void (*mode_set)(struct drm_bridge *bridge, | |
63f8f3ba LP |
199 | const struct drm_display_mode *mode, |
200 | const struct drm_display_mode *adjusted_mode); | |
199e4e96 SV |
201 | /** |
202 | * @pre_enable: | |
203 | * | |
204 | * This callback should enable the bridge. It is called right before | |
205 | * the preceding element in the display pipe is enabled. If the | |
206 | * preceding element is a bridge this means it's called before that | |
4541d31e SV |
207 | * bridge's @pre_enable function. If the preceding element is a |
208 | * &drm_encoder it's called right before the encoder's | |
209 | * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or | |
210 | * &drm_encoder_helper_funcs.dpms hook. | |
199e4e96 SV |
211 | * |
212 | * The display pipe (i.e. clocks and timing signals) feeding this bridge | |
213 | * will not yet be running when this callback is called. The bridge must | |
214 | * not enable the display link feeding the next bridge in the chain (if | |
215 | * there is one) when this callback is called. | |
216 | * | |
217 | * The pre_enable callback is optional. | |
218 | */ | |
219 | void (*pre_enable)(struct drm_bridge *bridge); | |
220 | ||
221 | /** | |
222 | * @enable: | |
223 | * | |
224 | * This callback should enable the bridge. It is called right after | |
225 | * the preceding element in the display pipe is enabled. If the | |
226 | * preceding element is a bridge this means it's called after that | |
4541d31e SV |
227 | * bridge's @enable function. If the preceding element is a |
228 | * &drm_encoder it's called right after the encoder's | |
229 | * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or | |
230 | * &drm_encoder_helper_funcs.dpms hook. | |
199e4e96 SV |
231 | * |
232 | * The bridge can assume that the display pipe (i.e. clocks and timing | |
233 | * signals) feeding it is running when this callback is called. This | |
234 | * callback must enable the display link feeding the next bridge in the | |
235 | * chain if there is one. | |
236 | * | |
237 | * The enable callback is optional. | |
238 | */ | |
239 | void (*enable)(struct drm_bridge *bridge); | |
240 | }; | |
241 | ||
36a776df LW |
242 | /** |
243 | * struct drm_bridge_timings - timing information for the bridge | |
244 | */ | |
245 | struct drm_bridge_timings { | |
246 | /** | |
247 | * @sampling_edge: | |
248 | * | |
249 | * Tells whether the bridge samples the digital input signal | |
250 | * from the display engine on the positive or negative edge of the | |
251 | * clock, this should reuse the DRM_BUS_FLAG_PIXDATA_[POS|NEG]EDGE | |
252 | * bitwise flags from the DRM connector (bit 2 and 3 valid). | |
253 | */ | |
254 | u32 sampling_edge; | |
255 | /** | |
256 | * @setup_time_ps: | |
257 | * | |
258 | * Defines the time in picoseconds the input data lines must be | |
259 | * stable before the clock edge. | |
260 | */ | |
261 | u32 setup_time_ps; | |
262 | /** | |
263 | * @hold_time_ps: | |
264 | * | |
265 | * Defines the time in picoseconds taken for the bridge to sample the | |
266 | * input signal after the clock edge. | |
267 | */ | |
268 | u32 hold_time_ps; | |
269 | }; | |
270 | ||
199e4e96 SV |
271 | /** |
272 | * struct drm_bridge - central DRM bridge control structure | |
199e4e96 SV |
273 | */ |
274 | struct drm_bridge { | |
6aa13402 | 275 | /** @dev: DRM device this bridge belongs to */ |
199e4e96 | 276 | struct drm_device *dev; |
6aa13402 | 277 | /** @encoder: encoder to which this bridge is connected */ |
199e4e96 | 278 | struct drm_encoder *encoder; |
6aa13402 | 279 | /** @next: the next bridge in the encoder chain */ |
199e4e96 SV |
280 | struct drm_bridge *next; |
281 | #ifdef CONFIG_OF | |
6aa13402 | 282 | /** @of_node: device node pointer to the bridge */ |
199e4e96 SV |
283 | struct device_node *of_node; |
284 | #endif | |
6aa13402 | 285 | /** @list: to keep track of all added bridges */ |
199e4e96 | 286 | struct list_head list; |
6aa13402 EA |
287 | /** |
288 | * @timings: | |
289 | * | |
290 | * the timing specification for the bridge, if any (may be NULL) | |
291 | */ | |
36a776df | 292 | const struct drm_bridge_timings *timings; |
6aa13402 | 293 | /** @funcs: control functions */ |
199e4e96 | 294 | const struct drm_bridge_funcs *funcs; |
6aa13402 | 295 | /** @driver_private: pointer to the bridge driver's internal context */ |
199e4e96 SV |
296 | void *driver_private; |
297 | }; | |
298 | ||
99286884 | 299 | void drm_bridge_add(struct drm_bridge *bridge); |
199e4e96 SV |
300 | void drm_bridge_remove(struct drm_bridge *bridge); |
301 | struct drm_bridge *of_drm_find_bridge(struct device_node *np); | |
3bb80f24 LP |
302 | int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge, |
303 | struct drm_bridge *previous); | |
199e4e96 SV |
304 | |
305 | bool drm_bridge_mode_fixup(struct drm_bridge *bridge, | |
5d435b46 PC |
306 | const struct drm_display_mode *mode, |
307 | struct drm_display_mode *adjusted_mode); | |
b1240f81 JA |
308 | enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge, |
309 | const struct drm_display_mode *mode); | |
199e4e96 SV |
310 | void drm_bridge_disable(struct drm_bridge *bridge); |
311 | void drm_bridge_post_disable(struct drm_bridge *bridge); | |
312 | void drm_bridge_mode_set(struct drm_bridge *bridge, | |
63f8f3ba LP |
313 | const struct drm_display_mode *mode, |
314 | const struct drm_display_mode *adjusted_mode); | |
199e4e96 SV |
315 | void drm_bridge_pre_enable(struct drm_bridge *bridge); |
316 | void drm_bridge_enable(struct drm_bridge *bridge); | |
317 | ||
13dfc054 EA |
318 | #ifdef CONFIG_DRM_PANEL_BRIDGE |
319 | struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel, | |
320 | u32 connector_type); | |
321 | void drm_panel_bridge_remove(struct drm_bridge *bridge); | |
67022227 EA |
322 | struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev, |
323 | struct drm_panel *panel, | |
324 | u32 connector_type); | |
13dfc054 EA |
325 | #endif |
326 | ||
199e4e96 | 327 | #endif |