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 struct drm_bridge_timings;
33 struct drm_panel;
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 
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 	 */
94 	enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge,
95 					   const struct drm_display_mode *mode);
96 
97 	/**
98 	 * @mode_fixup:
99 	 *
100 	 * This callback is used to validate and adjust a mode. The parameter
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
105 	 * match mode. See also &drm_crtc_state.adjusted_mode for more details.
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 	 *
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 	 *
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
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.
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 	 *
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.
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
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.
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.
197 	 */
198 	void (*mode_set)(struct drm_bridge *bridge,
199 			 struct drm_display_mode *mode,
200 			 struct drm_display_mode *adjusted_mode);
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
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.
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
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.
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 
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 
271 /**
272  * struct drm_bridge - central DRM bridge control structure
273  */
274 struct drm_bridge {
275 	/** @dev: DRM device this bridge belongs to */
276 	struct drm_device *dev;
277 	/** @encoder: encoder to which this bridge is connected */
278 	struct drm_encoder *encoder;
279 	/** @next: the next bridge in the encoder chain */
280 	struct drm_bridge *next;
281 #ifdef CONFIG_OF
282 	/** @of_node: device node pointer to the bridge */
283 	struct device_node *of_node;
284 #endif
285 	/** @list: to keep track of all added bridges */
286 	struct list_head list;
287 	/**
288 	 * @timings:
289 	 *
290 	 * the timing specification for the bridge, if any (may be NULL)
291 	 */
292 	const struct drm_bridge_timings *timings;
293 	/** @funcs: control functions */
294 	const struct drm_bridge_funcs *funcs;
295 	/** @driver_private: pointer to the bridge driver's internal context */
296 	void *driver_private;
297 };
298 
299 void drm_bridge_add(struct drm_bridge *bridge);
300 void drm_bridge_remove(struct drm_bridge *bridge);
301 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
302 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
303 		      struct drm_bridge *previous);
304 
305 bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
306 			   const struct drm_display_mode *mode,
307 			   struct drm_display_mode *adjusted_mode);
308 enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge,
309 					   const struct drm_display_mode *mode);
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,
313 			 struct drm_display_mode *mode,
314 			 struct drm_display_mode *adjusted_mode);
315 void drm_bridge_pre_enable(struct drm_bridge *bridge);
316 void drm_bridge_enable(struct drm_bridge *bridge);
317 
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);
322 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev,
323 					     struct drm_panel *panel,
324 					     u32 connector_type);
325 #endif
326 
327 #endif
328