xref: /linux/include/drm/drm_bridge.h (revision b2d0f5d5dc53532e6f07bc546a476a55ebdfe0f3)
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_panel;
33 
34 /**
35  * struct drm_bridge_funcs - drm_bridge control functions
36  */
37 struct drm_bridge_funcs {
38 	/**
39 	 * @attach:
40 	 *
41 	 * This callback is invoked whenever our bridge is being attached to a
42 	 * &drm_encoder.
43 	 *
44 	 * The attach callback is optional.
45 	 *
46 	 * RETURNS:
47 	 *
48 	 * Zero on success, error code on failure.
49 	 */
50 	int (*attach)(struct drm_bridge *bridge);
51 
52 	/**
53 	 * @detach:
54 	 *
55 	 * This callback is invoked whenever our bridge is being detached from a
56 	 * &drm_encoder.
57 	 *
58 	 * The detach callback is optional.
59 	 */
60 	void (*detach)(struct drm_bridge *bridge);
61 
62 	/**
63 	 * @mode_valid:
64 	 *
65 	 * This callback is used to check if a specific mode is valid in this
66 	 * bridge. This should be implemented if the bridge has some sort of
67 	 * restriction in the modes it can display. For example, a given bridge
68 	 * may be responsible to set a clock value. If the clock can not
69 	 * produce all the values for the available modes then this callback
70 	 * can be used to restrict the number of modes to only the ones that
71 	 * can be displayed.
72 	 *
73 	 * This hook is used by the probe helpers to filter the mode list in
74 	 * drm_helper_probe_single_connector_modes(), and it is used by the
75 	 * atomic helpers to validate modes supplied by userspace in
76 	 * drm_atomic_helper_check_modeset().
77 	 *
78 	 * This function is optional.
79 	 *
80 	 * NOTE:
81 	 *
82 	 * Since this function is both called from the check phase of an atomic
83 	 * commit, and the mode validation in the probe paths it is not allowed
84 	 * to look at anything else but the passed-in mode, and validate it
85 	 * against configuration-invariant hardward constraints. Any further
86 	 * limits which depend upon the configuration can only be checked in
87 	 * @mode_fixup.
88 	 *
89 	 * RETURNS:
90 	 *
91 	 * drm_mode_status Enum
92 	 */
93 	enum drm_mode_status (*mode_valid)(struct drm_bridge *crtc,
94 					   const struct drm_display_mode *mode);
95 
96 	/**
97 	 * @mode_fixup:
98 	 *
99 	 * This callback is used to validate and adjust a mode. The paramater
100 	 * mode is the display mode that should be fed to the next element in
101 	 * the display chain, either the final &drm_connector or the next
102 	 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
103 	 * requires. It can be modified by this callback and does not need to
104 	 * match mode. See also &drm_crtc_state.adjusted_mode for more details.
105 	 *
106 	 * This is the only hook that allows a bridge to reject a modeset. If
107 	 * this function passes all other callbacks must succeed for this
108 	 * configuration.
109 	 *
110 	 * The mode_fixup callback is optional.
111 	 *
112 	 * NOTE:
113 	 *
114 	 * This function is called in the check phase of atomic modesets, which
115 	 * can be aborted for any reason (including on userspace's request to
116 	 * just check whether a configuration would be possible). Drivers MUST
117 	 * NOT touch any persistent state (hardware or software) or data
118 	 * structures except the passed in @state parameter.
119 	 *
120 	 * Also beware that userspace can request its own custom modes, neither
121 	 * core nor helpers filter modes to the list of probe modes reported by
122 	 * the GETCONNECTOR IOCTL and stored in &drm_connector.modes. To ensure
123 	 * that modes are filtered consistently put any bridge constraints and
124 	 * limits checks into @mode_valid.
125 	 *
126 	 * RETURNS:
127 	 *
128 	 * True if an acceptable configuration is possible, false if the modeset
129 	 * operation should be rejected.
130 	 */
131 	bool (*mode_fixup)(struct drm_bridge *bridge,
132 			   const struct drm_display_mode *mode,
133 			   struct drm_display_mode *adjusted_mode);
134 	/**
135 	 * @disable:
136 	 *
137 	 * This callback should disable the bridge. It is called right before
138 	 * the preceding element in the display pipe is disabled. If the
139 	 * preceding element is a bridge this means it's called before that
140 	 * bridge's @disable vfunc. If the preceding element is a &drm_encoder
141 	 * it's called right before the &drm_encoder_helper_funcs.disable,
142 	 * &drm_encoder_helper_funcs.prepare or &drm_encoder_helper_funcs.dpms
143 	 * hook.
144 	 *
145 	 * The bridge can assume that the display pipe (i.e. clocks and timing
146 	 * signals) feeding it is still running when this callback is called.
147 	 *
148 	 * The disable callback is optional.
149 	 */
150 	void (*disable)(struct drm_bridge *bridge);
151 
152 	/**
153 	 * @post_disable:
154 	 *
155 	 * This callback should disable the bridge. It is called right after the
156 	 * preceding element in the display pipe is disabled. If the preceding
157 	 * element is a bridge this means it's called after that bridge's
158 	 * @post_disable function. If the preceding element is a &drm_encoder
159 	 * it's called right after the encoder's
160 	 * &drm_encoder_helper_funcs.disable, &drm_encoder_helper_funcs.prepare
161 	 * or &drm_encoder_helper_funcs.dpms hook.
162 	 *
163 	 * The bridge must assume that the display pipe (i.e. clocks and timing
164 	 * singals) feeding it is no longer running when this callback is
165 	 * called.
166 	 *
167 	 * The post_disable callback is optional.
168 	 */
169 	void (*post_disable)(struct drm_bridge *bridge);
170 
171 	/**
172 	 * @mode_set:
173 	 *
174 	 * This callback should set the given mode on the bridge. It is called
175 	 * after the @mode_set callback for the preceding element in the display
176 	 * pipeline has been called already. If the bridge is the first element
177 	 * then this would be &drm_encoder_helper_funcs.mode_set. The display
178 	 * pipe (i.e.  clocks and timing signals) is off when this function is
179 	 * called.
180 	 */
181 	void (*mode_set)(struct drm_bridge *bridge,
182 			 struct drm_display_mode *mode,
183 			 struct drm_display_mode *adjusted_mode);
184 	/**
185 	 * @pre_enable:
186 	 *
187 	 * This callback should enable the bridge. It is called right before
188 	 * the preceding element in the display pipe is enabled. If the
189 	 * preceding element is a bridge this means it's called before that
190 	 * bridge's @pre_enable function. If the preceding element is a
191 	 * &drm_encoder it's called right before the encoder's
192 	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
193 	 * &drm_encoder_helper_funcs.dpms hook.
194 	 *
195 	 * The display pipe (i.e. clocks and timing signals) feeding this bridge
196 	 * will not yet be running when this callback is called. The bridge must
197 	 * not enable the display link feeding the next bridge in the chain (if
198 	 * there is one) when this callback is called.
199 	 *
200 	 * The pre_enable callback is optional.
201 	 */
202 	void (*pre_enable)(struct drm_bridge *bridge);
203 
204 	/**
205 	 * @enable:
206 	 *
207 	 * This callback should enable the bridge. It is called right after
208 	 * the preceding element in the display pipe is enabled. If the
209 	 * preceding element is a bridge this means it's called after that
210 	 * bridge's @enable function. If the preceding element is a
211 	 * &drm_encoder it's called right after the encoder's
212 	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
213 	 * &drm_encoder_helper_funcs.dpms hook.
214 	 *
215 	 * The bridge can assume that the display pipe (i.e. clocks and timing
216 	 * signals) feeding it is running when this callback is called. This
217 	 * callback must enable the display link feeding the next bridge in the
218 	 * chain if there is one.
219 	 *
220 	 * The enable callback is optional.
221 	 */
222 	void (*enable)(struct drm_bridge *bridge);
223 };
224 
225 /**
226  * struct drm_bridge - central DRM bridge control structure
227  * @dev: DRM device this bridge belongs to
228  * @encoder: encoder to which this bridge is connected
229  * @next: the next bridge in the encoder chain
230  * @of_node: device node pointer to the bridge
231  * @list: to keep track of all added bridges
232  * @funcs: control functions
233  * @driver_private: pointer to the bridge driver's internal context
234  */
235 struct drm_bridge {
236 	struct drm_device *dev;
237 	struct drm_encoder *encoder;
238 	struct drm_bridge *next;
239 #ifdef CONFIG_OF
240 	struct device_node *of_node;
241 #endif
242 	struct list_head list;
243 
244 	const struct drm_bridge_funcs *funcs;
245 	void *driver_private;
246 };
247 
248 int drm_bridge_add(struct drm_bridge *bridge);
249 void drm_bridge_remove(struct drm_bridge *bridge);
250 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
251 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
252 		      struct drm_bridge *previous);
253 
254 bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
255 			const struct drm_display_mode *mode,
256 			struct drm_display_mode *adjusted_mode);
257 enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge,
258 					   const struct drm_display_mode *mode);
259 void drm_bridge_disable(struct drm_bridge *bridge);
260 void drm_bridge_post_disable(struct drm_bridge *bridge);
261 void drm_bridge_mode_set(struct drm_bridge *bridge,
262 			struct drm_display_mode *mode,
263 			struct drm_display_mode *adjusted_mode);
264 void drm_bridge_pre_enable(struct drm_bridge *bridge);
265 void drm_bridge_enable(struct drm_bridge *bridge);
266 
267 #ifdef CONFIG_DRM_PANEL_BRIDGE
268 struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel,
269 					u32 connector_type);
270 void drm_panel_bridge_remove(struct drm_bridge *bridge);
271 struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev,
272 					     struct drm_panel *panel,
273 					     u32 connector_type);
274 #endif
275 
276 #endif
277