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;
 32
 33/**
 34 * struct drm_bridge_funcs - drm_bridge control functions
 35 */
 36struct 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
 61	/**
 62	 * @mode_fixup:
 63	 *
 64	 * This callback is used to validate and adjust a mode. The paramater
 65	 * mode is the display mode that should be fed to the next element in
 66	 * the display chain, either the final &drm_connector or the next
 67	 * &drm_bridge. The parameter adjusted_mode is the input mode the bridge
 68	 * requires. It can be modified by this callback and does not need to
 69	 * match mode.
 70	 *
 71	 * This is the only hook that allows a bridge to reject a modeset. If
 72	 * this function passes all other callbacks must succeed for this
 73	 * configuration.
 74	 *
 75	 * The mode_fixup callback is optional.
 76	 *
 77	 * NOTE:
 78	 *
 79	 * This function is called in the check phase of atomic modesets, which
 80	 * can be aborted for any reason (including on userspace's request to
 81	 * just check whether a configuration would be possible). Drivers MUST
 82	 * NOT touch any persistent state (hardware or software) or data
 83	 * structures except the passed in @state parameter.
 84	 *
 85	 * RETURNS:
 86	 *
 87	 * True if an acceptable configuration is possible, false if the modeset
 88	 * operation should be rejected.
 89	 */
 90	bool (*mode_fixup)(struct drm_bridge *bridge,
 91			   const struct drm_display_mode *mode,
 92			   struct drm_display_mode *adjusted_mode);
 93	/**
 94	 * @disable:
 95	 *
 96	 * This callback should disable the bridge. It is called right before
 97	 * the preceding element in the display pipe is disabled. If the
 98	 * preceding element is a bridge this means it's called before that
 99	 * bridge's ->disable() function. If the preceding element is a
100	 * &drm_encoder it's called right before the encoder's ->disable(),
101	 * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
102	 *
103	 * The bridge can assume that the display pipe (i.e. clocks and timing
104	 * signals) feeding it is still running when this callback is called.
105	 *
106	 * The disable callback is optional.
107	 */
108	void (*disable)(struct drm_bridge *bridge);
109
110	/**
111	 * @post_disable:
112	 *
113	 * This callback should disable the bridge. It is called right after
114	 * the preceding element in the display pipe is disabled. If the
115	 * preceding element is a bridge this means it's called after that
116	 * bridge's ->post_disable() function. If the preceding element is a
117	 * &drm_encoder it's called right after the encoder's ->disable(),
118	 * ->prepare() or ->dpms() hook from struct &drm_encoder_helper_funcs.
119	 *
120	 * The bridge must assume that the display pipe (i.e. clocks and timing
121	 * singals) feeding it is no longer running when this callback is
122	 * called.
123	 *
124	 * The post_disable callback is optional.
125	 */
126	void (*post_disable)(struct drm_bridge *bridge);
127
128	/**
129	 * @mode_set:
130	 *
131	 * This callback should set the given mode on the bridge. It is called
132	 * after the ->mode_set() callback for the preceding element in the
133	 * display pipeline has been called already. The display pipe (i.e.
134	 * clocks and timing signals) is off when this function is called.
135	 */
136	void (*mode_set)(struct drm_bridge *bridge,
137			 struct drm_display_mode *mode,
138			 struct drm_display_mode *adjusted_mode);
139	/**
140	 * @pre_enable:
141	 *
142	 * This callback should enable the bridge. It is called right before
143	 * the preceding element in the display pipe is enabled. If the
144	 * preceding element is a bridge this means it's called before that
145	 * bridge's ->pre_enable() function. If the preceding element is a
146	 * &drm_encoder it's called right before the encoder's ->enable(),
147	 * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
148	 *
149	 * The display pipe (i.e. clocks and timing signals) feeding this bridge
150	 * will not yet be running when this callback is called. The bridge must
151	 * not enable the display link feeding the next bridge in the chain (if
152	 * there is one) when this callback is called.
153	 *
154	 * The pre_enable callback is optional.
155	 */
156	void (*pre_enable)(struct drm_bridge *bridge);
157
158	/**
159	 * @enable:
160	 *
161	 * This callback should enable the bridge. It is called right after
162	 * the preceding element in the display pipe is enabled. If the
163	 * preceding element is a bridge this means it's called after that
164	 * bridge's ->enable() function. If the preceding element is a
165	 * &drm_encoder it's called right after the encoder's ->enable(),
166	 * ->commit() or ->dpms() hook from struct &drm_encoder_helper_funcs.
167	 *
168	 * The bridge can assume that the display pipe (i.e. clocks and timing
169	 * signals) feeding it is running when this callback is called. This
170	 * callback must enable the display link feeding the next bridge in the
171	 * chain if there is one.
172	 *
173	 * The enable callback is optional.
174	 */
175	void (*enable)(struct drm_bridge *bridge);
176};
177
178/**
179 * struct drm_bridge - central DRM bridge control structure
180 * @dev: DRM device this bridge belongs to
181 * @encoder: encoder to which this bridge is connected
182 * @next: the next bridge in the encoder chain
183 * @of_node: device node pointer to the bridge
184 * @list: to keep track of all added bridges
185 * @funcs: control functions
186 * @driver_private: pointer to the bridge driver's internal context
187 */
188struct drm_bridge {
189	struct drm_device *dev;
190	struct drm_encoder *encoder;
191	struct drm_bridge *next;
192#ifdef CONFIG_OF
193	struct device_node *of_node;
194#endif
195	struct list_head list;
196
197	const struct drm_bridge_funcs *funcs;
198	void *driver_private;
199};
200
201int drm_bridge_add(struct drm_bridge *bridge);
202void drm_bridge_remove(struct drm_bridge *bridge);
203struct drm_bridge *of_drm_find_bridge(struct device_node *np);
204int drm_bridge_attach(struct drm_device *dev, struct drm_bridge *bridge);
205void drm_bridge_detach(struct drm_bridge *bridge);
206
207bool drm_bridge_mode_fixup(struct drm_bridge *bridge,
208			const struct drm_display_mode *mode,
209			struct drm_display_mode *adjusted_mode);
210void drm_bridge_disable(struct drm_bridge *bridge);
211void drm_bridge_post_disable(struct drm_bridge *bridge);
212void drm_bridge_mode_set(struct drm_bridge *bridge,
213			struct drm_display_mode *mode,
214			struct drm_display_mode *adjusted_mode);
215void drm_bridge_pre_enable(struct drm_bridge *bridge);
216void drm_bridge_enable(struct drm_bridge *bridge);
217
218#endif