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
 31struct drm_bridge;
 32struct drm_bridge_timings;
 33struct drm_panel;
 34
 35/**
 36 * struct drm_bridge_funcs - drm_bridge control functions
 37 */
 38struct 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 paramater
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	void (*mode_set)(struct drm_bridge *bridge,
183			 struct drm_display_mode *mode,
184			 struct drm_display_mode *adjusted_mode);
185	/**
186	 * @pre_enable:
187	 *
188	 * This callback should enable the bridge. It is called right before
189	 * the preceding element in the display pipe is enabled. If the
190	 * preceding element is a bridge this means it's called before that
191	 * bridge's @pre_enable function. If the preceding element is a
192	 * &drm_encoder it's called right before the encoder's
193	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
194	 * &drm_encoder_helper_funcs.dpms hook.
195	 *
196	 * The display pipe (i.e. clocks and timing signals) feeding this bridge
197	 * will not yet be running when this callback is called. The bridge must
198	 * not enable the display link feeding the next bridge in the chain (if
199	 * there is one) when this callback is called.
200	 *
201	 * The pre_enable callback is optional.
202	 */
203	void (*pre_enable)(struct drm_bridge *bridge);
204
205	/**
206	 * @enable:
207	 *
208	 * This callback should enable the bridge. It is called right after
209	 * the preceding element in the display pipe is enabled. If the
210	 * preceding element is a bridge this means it's called after that
211	 * bridge's @enable function. If the preceding element is a
212	 * &drm_encoder it's called right after the encoder's
213	 * &drm_encoder_helper_funcs.enable, &drm_encoder_helper_funcs.commit or
214	 * &drm_encoder_helper_funcs.dpms hook.
215	 *
216	 * The bridge can assume that the display pipe (i.e. clocks and timing
217	 * signals) feeding it is running when this callback is called. This
218	 * callback must enable the display link feeding the next bridge in the
219	 * chain if there is one.
220	 *
221	 * The enable callback is optional.
222	 */
223	void (*enable)(struct drm_bridge *bridge);
224};
225
226/**
227 * struct drm_bridge_timings - timing information for the bridge
228 */
229struct drm_bridge_timings {
230	/**
231	 * @sampling_edge:
232	 *
233	 * Tells whether the bridge samples the digital input signal
234	 * from the display engine on the positive or negative edge of the
235	 * clock, this should reuse the DRM_BUS_FLAG_PIXDATA_[POS|NEG]EDGE
236	 * bitwise flags from the DRM connector (bit 2 and 3 valid).
237	 */
238	u32 sampling_edge;
239	/**
240	 * @setup_time_ps:
241	 *
242	 * Defines the time in picoseconds the input data lines must be
243	 * stable before the clock edge.
244	 */
245	u32 setup_time_ps;
246	/**
247	 * @hold_time_ps:
248	 *
249	 * Defines the time in picoseconds taken for the bridge to sample the
250	 * input signal after the clock edge.
251	 */
252	u32 hold_time_ps;
253};
254
255/**
256 * struct drm_bridge - central DRM bridge control structure
257 * @dev: DRM device this bridge belongs to
258 * @encoder: encoder to which this bridge is connected
259 * @next: the next bridge in the encoder chain
260 * @of_node: device node pointer to the bridge
261 * @list: to keep track of all added bridges
262 * @timings: the timing specification for the bridge, if any (may
263 * be NULL)
264 * @funcs: control functions
265 * @driver_private: pointer to the bridge driver's internal context
266 */
267struct drm_bridge {
268	struct drm_device *dev;
269	struct drm_encoder *encoder;
270	struct drm_bridge *next;
271#ifdef CONFIG_OF
272	struct device_node *of_node;
273#endif
274	struct list_head list;
275	const struct drm_bridge_timings *timings;
276
277	const struct drm_bridge_funcs *funcs;
278	void *driver_private;
279};
280
281void drm_bridge_add(struct drm_bridge *bridge);
282void drm_bridge_remove(struct drm_bridge *bridge);
283struct drm_bridge *of_drm_find_bridge(struct device_node *np);
284int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
285		      struct drm_bridge *previous);
286
287bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
288			const struct drm_display_mode *mode,
289			struct drm_display_mode *adjusted_mode);
290enum drm_mode_status drm_bridge_mode_valid(struct drm_bridge *bridge,
291					   const struct drm_display_mode *mode);
292void drm_bridge_disable(struct drm_bridge *bridge);
293void drm_bridge_post_disable(struct drm_bridge *bridge);
294void drm_bridge_mode_set(struct drm_bridge *bridge,
295			struct drm_display_mode *mode,
296			struct drm_display_mode *adjusted_mode);
297void drm_bridge_pre_enable(struct drm_bridge *bridge);
298void drm_bridge_enable(struct drm_bridge *bridge);
299
300#ifdef CONFIG_DRM_PANEL_BRIDGE
301struct drm_bridge *drm_panel_bridge_add(struct drm_panel *panel,
302					u32 connector_type);
303void drm_panel_bridge_remove(struct drm_bridge *bridge);
304struct drm_bridge *devm_drm_panel_bridge_add(struct device *dev,
305					     struct drm_panel *panel,
306					     u32 connector_type);
307#endif
308
309#endif