Commit | Line | Data |
---|---|---|
199e4e96 DV |
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; | |
32 | ||
33 | /** | |
34 | * struct drm_bridge_funcs - drm_bridge control functions | |
35 | */ | |
36 | struct drm_bridge_funcs { | |
37 | /** | |
38 | * @attach: | |
39 | * | |
40 | * This callback is invoked whenever our bridge is being attached to a | |
41 | * &drm_encoder. | |
42 | * | |
43 | * The attach callback is optional. | |
44 | * | |
45 | * RETURNS: | |
46 | * | |
47 | * Zero on success, error code on failure. | |
48 | */ | |
49 | int (*attach)(struct drm_bridge *bridge); | |
50 | ||
51 | /** | |
52 | * @detach: | |
53 | * | |
54 | * This callback is invoked whenever our bridge is being detached from a | |
55 | * &drm_encoder. | |
56 | * | |
57 | * The detach callback is optional. | |
58 | */ | |
59 | void (*detach)(struct drm_bridge *bridge); | |
60 | ||
3eb220a5 JA |
61 | /** |
62 | * @mode_valid: | |
63 | * | |
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 | |
70 | * can be displayed. | |
71 | * | |
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(). | |
76 | * | |
77 | * This function is optional. | |
78 | * | |
79 | * NOTE: | |
80 | * | |
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 | |
86 | * @mode_fixup. | |
87 | * | |
88 | * RETURNS: | |
89 | * | |
90 | * drm_mode_status Enum | |
91 | */ | |
92 | enum drm_mode_status (*mode_valid)(struct drm_bridge *crtc, | |
93 | const struct drm_display_mode *mode); | |
94 | ||
199e4e96 DV |
95 | /** |
96 | * @mode_fixup: | |
97 | * | |
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 | |
103 | * match mode. | |
104 | * | |
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 | |
107 | * configuration. | |
108 | * | |
109 | * The mode_fixup callback is optional. | |
110 | * | |
111 | * NOTE: | |
112 | * | |
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. | |
118 | * | |
3eb220a5 JA |
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. | |
124 | * | |
199e4e96 DV |
125 | * RETURNS: |
126 | * | |
127 | * True if an acceptable configuration is possible, false if the modeset | |
128 | * operation should be rejected. | |
129 | */ | |
130 | bool (*mode_fixup)(struct drm_bridge *bridge, | |
131 | const struct drm_display_mode *mode, | |
132 | struct drm_display_mode *adjusted_mode); | |
133 | /** | |
134 | * @disable: | |
135 | * | |
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 | |
4541d31e DV |
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 | |
142 | * hook. | |
199e4e96 DV |
143 | * |
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. | |
146 | * | |
147 | * The disable callback is optional. | |
148 | */ | |
149 | void (*disable)(struct drm_bridge *bridge); | |
150 | ||
151 | /** | |
152 | * @post_disable: | |
153 | * | |
4541d31e DV |
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. | |
199e4e96 DV |
161 | * |
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 | |
164 | * called. | |
165 | * | |
166 | * The post_disable callback is optional. | |
167 | */ | |
168 | void (*post_disable)(struct drm_bridge *bridge); | |
169 | ||
170 | /** | |
171 | * @mode_set: | |
172 | * | |
173 | * This callback should set the given mode on the bridge. It is called | |
4541d31e DV |
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 | |
178 | * called. | |
199e4e96 DV |
179 | */ |
180 | void (*mode_set)(struct drm_bridge *bridge, | |
181 | struct drm_display_mode *mode, | |
182 | struct drm_display_mode *adjusted_mode); | |
183 | /** | |
184 | * @pre_enable: | |
185 | * | |
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 | |
4541d31e DV |
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. | |
199e4e96 DV |
193 | * |
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. | |
198 | * | |
199 | * The pre_enable callback is optional. | |
200 | */ | |
201 | void (*pre_enable)(struct drm_bridge *bridge); | |
202 | ||
203 | /** | |
204 | * @enable: | |
205 | * | |
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 | |
4541d31e DV |
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. | |
199e4e96 DV |
213 | * |
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. | |
218 | * | |
219 | * The enable callback is optional. | |
220 | */ | |
221 | void (*enable)(struct drm_bridge *bridge); | |
222 | }; | |
223 | ||
224 | /** | |
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 | |
233 | */ | |
234 | struct drm_bridge { | |
235 | struct drm_device *dev; | |
236 | struct drm_encoder *encoder; | |
237 | struct drm_bridge *next; | |
238 | #ifdef CONFIG_OF | |
239 | struct device_node *of_node; | |
240 | #endif | |
241 | struct list_head list; | |
242 | ||
243 | const struct drm_bridge_funcs *funcs; | |
244 | void *driver_private; | |
245 | }; | |
246 | ||
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); | |
3bb80f24 LP |
250 | int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge, |
251 | struct drm_bridge *previous); | |
199e4e96 DV |
252 | |
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); | |
263 | ||
264 | #endif |