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_ENCODER_H__
24 #define __DRM_ENCODER_H__
25 
26 #include <linux/list.h>
27 #include <linux/ctype.h>
28 #include <drm/drm_crtc.h>
29 #include <drm/drm_mode.h>
30 #include <drm/drm_mode_object.h>
31 #include <drm/drm_util.h>
32 
33 struct drm_encoder;
34 
35 /**
36  * struct drm_encoder_funcs - encoder controls
37  *
38  * Encoders sit between CRTCs and connectors.
39  */
40 struct drm_encoder_funcs {
41 	/**
42 	 * @reset:
43 	 *
44 	 * Reset encoder hardware and software state to off. This function isn't
45 	 * called by the core directly, only through drm_mode_config_reset().
46 	 * It's not a helper hook only for historical reasons.
47 	 */
48 	void (*reset)(struct drm_encoder *encoder);
49 
50 	/**
51 	 * @destroy:
52 	 *
53 	 * Clean up encoder resources. This is only called at driver unload time
54 	 * through drm_mode_config_cleanup() since an encoder cannot be
55 	 * hotplugged in DRM.
56 	 */
57 	void (*destroy)(struct drm_encoder *encoder);
58 
59 	/**
60 	 * @late_register:
61 	 *
62 	 * This optional hook can be used to register additional userspace
63 	 * interfaces attached to the encoder like debugfs interfaces.
64 	 * It is called late in the driver load sequence from drm_dev_register().
65 	 * Everything added from this callback should be unregistered in
66 	 * the early_unregister callback.
67 	 *
68 	 * Returns:
69 	 *
70 	 * 0 on success, or a negative error code on failure.
71 	 */
72 	int (*late_register)(struct drm_encoder *encoder);
73 
74 	/**
75 	 * @early_unregister:
76 	 *
77 	 * This optional hook should be used to unregister the additional
78 	 * userspace interfaces attached to the encoder from
79 	 * @late_register. It is called from drm_dev_unregister(),
80 	 * early in the driver unload sequence to disable userspace access
81 	 * before data structures are torndown.
82 	 */
83 	void (*early_unregister)(struct drm_encoder *encoder);
84 };
85 
86 /**
87  * struct drm_encoder - central DRM encoder structure
88  * @dev: parent DRM device
89  * @head: list management
90  * @base: base KMS object
91  * @name: human readable name, can be overwritten by the driver
92  * @funcs: control functions, can be NULL for simple managed encoders
93  * @helper_private: mid-layer private data
94  *
95  * CRTCs drive pixels to encoders, which convert them into signals
96  * appropriate for a given connector or set of connectors.
97  */
98 struct drm_encoder {
99 	struct drm_device *dev;
100 	struct list_head head;
101 
102 	struct drm_mode_object base;
103 	char *name;
104 	/**
105 	 * @encoder_type:
106 	 *
107 	 * One of the DRM_MODE_ENCODER_<foo> types in drm_mode.h. The following
108 	 * encoder types are defined thus far:
109 	 *
110 	 * - DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A.
111 	 *
112 	 * - DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort.
113 	 *
114 	 * - DRM_MODE_ENCODER_LVDS for display panels, or in general any panel
115 	 *   with a proprietary parallel connector.
116 	 *
117 	 * - DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video,
118 	 *   Component, SCART).
119 	 *
120 	 * - DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
121 	 *
122 	 * - DRM_MODE_ENCODER_DSI for panels connected using the DSI serial bus.
123 	 *
124 	 * - DRM_MODE_ENCODER_DPI for panels connected using the DPI parallel
125 	 *   bus.
126 	 *
127 	 * - DRM_MODE_ENCODER_DPMST for special fake encoders used to allow
128 	 *   mutliple DP MST streams to share one physical encoder.
129 	 */
130 	int encoder_type;
131 
132 	/**
133 	 * @index: Position inside the mode_config.list, can be used as an array
134 	 * index. It is invariant over the lifetime of the encoder.
135 	 */
136 	unsigned index;
137 
138 	/**
139 	 * @possible_crtcs: Bitmask of potential CRTC bindings, using
140 	 * drm_crtc_index() as the index into the bitfield. The driver must set
141 	 * the bits for all &drm_crtc objects this encoder can be connected to
142 	 * before calling drm_dev_register().
143 	 *
144 	 * You will get a WARN if you get this wrong in the driver.
145 	 *
146 	 * Note that since CRTC objects can't be hotplugged the assigned indices
147 	 * are stable and hence known before registering all objects.
148 	 */
149 	uint32_t possible_crtcs;
150 
151 	/**
152 	 * @possible_clones: Bitmask of potential sibling encoders for cloning,
153 	 * using drm_encoder_index() as the index into the bitfield. The driver
154 	 * must set the bits for all &drm_encoder objects which can clone a
155 	 * &drm_crtc together with this encoder before calling
156 	 * drm_dev_register(). Drivers should set the bit representing the
157 	 * encoder itself, too. Cloning bits should be set such that when two
158 	 * encoders can be used in a cloned configuration, they both should have
159 	 * each another bits set.
160 	 *
161 	 * As an exception to the above rule if the driver doesn't implement
162 	 * any cloning it can leave @possible_clones set to 0. The core will
163 	 * automagically fix this up by setting the bit for the encoder itself.
164 	 *
165 	 * You will get a WARN if you get this wrong in the driver.
166 	 *
167 	 * Note that since encoder objects can't be hotplugged the assigned indices
168 	 * are stable and hence known before registering all objects.
169 	 */
170 	uint32_t possible_clones;
171 
172 	/**
173 	 * @crtc: Currently bound CRTC, only really meaningful for non-atomic
174 	 * drivers.  Atomic drivers should instead check
175 	 * &drm_connector_state.crtc.
176 	 */
177 	struct drm_crtc *crtc;
178 
179 	/**
180 	 * @bridge_chain: Bridges attached to this encoder. Drivers shall not
181 	 * access this field directly.
182 	 */
183 	struct list_head bridge_chain;
184 
185 	const struct drm_encoder_funcs *funcs;
186 	const struct drm_encoder_helper_funcs *helper_private;
187 };
188 
189 #define obj_to_encoder(x) container_of(x, struct drm_encoder, base)
190 
191 __printf(5, 6)
192 int drm_encoder_init(struct drm_device *dev,
193 		     struct drm_encoder *encoder,
194 		     const struct drm_encoder_funcs *funcs,
195 		     int encoder_type, const char *name, ...);
196 
197 __printf(5, 6)
198 int drmm_encoder_init(struct drm_device *dev,
199 		      struct drm_encoder *encoder,
200 		      const struct drm_encoder_funcs *funcs,
201 		      int encoder_type, const char *name, ...);
202 
203 __printf(6, 7)
204 void *__drmm_encoder_alloc(struct drm_device *dev,
205 			   size_t size, size_t offset,
206 			   const struct drm_encoder_funcs *funcs,
207 			   int encoder_type,
208 			   const char *name, ...);
209 
210 /**
211  * drmm_encoder_alloc - Allocate and initialize an encoder
212  * @dev: drm device
213  * @type: the type of the struct which contains struct &drm_encoder
214  * @member: the name of the &drm_encoder within @type
215  * @funcs: callbacks for this encoder (optional)
216  * @encoder_type: user visible type of the encoder
217  * @name: printf style format string for the encoder name, or NULL for default name
218  *
219  * Allocates and initializes an encoder. Encoder should be subclassed as part of
220  * driver encoder objects. Cleanup is automatically handled through registering
221  * drm_encoder_cleanup() with drmm_add_action().
222  *
223  * The @drm_encoder_funcs.destroy hook must be NULL.
224  *
225  * Returns:
226  * Pointer to new encoder, or ERR_PTR on failure.
227  */
228 #define drmm_encoder_alloc(dev, type, member, funcs, encoder_type, name, ...) \
229 	((type *)__drmm_encoder_alloc(dev, sizeof(type), \
230 				      offsetof(type, member), funcs, \
231 				      encoder_type, name, ##__VA_ARGS__))
232 
233 /**
234  * drmm_plain_encoder_alloc - Allocate and initialize an encoder
235  * @dev: drm device
236  * @funcs: callbacks for this encoder (optional)
237  * @encoder_type: user visible type of the encoder
238  * @name: printf style format string for the encoder name, or NULL for default name
239  *
240  * This is a simplified version of drmm_encoder_alloc(), which only allocates
241  * and returns a struct drm_encoder instance, with no subclassing.
242  *
243  * Returns:
244  * Pointer to the new drm_encoder struct, or ERR_PTR on failure.
245  */
246 #define drmm_plain_encoder_alloc(dev, funcs, encoder_type, name, ...) \
247 	((struct drm_encoder *) \
248 	 __drmm_encoder_alloc(dev, sizeof(struct drm_encoder), \
249 			      0, funcs, encoder_type, name, ##__VA_ARGS__))
250 
251 /**
252  * drm_encoder_index - find the index of a registered encoder
253  * @encoder: encoder to find index for
254  *
255  * Given a registered encoder, return the index of that encoder within a DRM
256  * device's list of encoders.
257  */
drm_encoder_index(const struct drm_encoder * encoder)258 static inline unsigned int drm_encoder_index(const struct drm_encoder *encoder)
259 {
260 	return encoder->index;
261 }
262 
263 /**
264  * drm_encoder_mask - find the mask of a registered encoder
265  * @encoder: encoder to find mask for
266  *
267  * Given a registered encoder, return the mask bit of that encoder for an
268  * encoder's possible_clones field.
269  */
drm_encoder_mask(const struct drm_encoder * encoder)270 static inline u32 drm_encoder_mask(const struct drm_encoder *encoder)
271 {
272 	return 1 << drm_encoder_index(encoder);
273 }
274 
275 /**
276  * drm_encoder_crtc_ok - can a given crtc drive a given encoder?
277  * @encoder: encoder to test
278  * @crtc: crtc to test
279  *
280  * Returns false if @encoder can't be driven by @crtc, true otherwise.
281  */
drm_encoder_crtc_ok(struct drm_encoder * encoder,struct drm_crtc * crtc)282 static inline bool drm_encoder_crtc_ok(struct drm_encoder *encoder,
283 				       struct drm_crtc *crtc)
284 {
285 	return !!(encoder->possible_crtcs & drm_crtc_mask(crtc));
286 }
287 
288 /**
289  * drm_encoder_find - find a &drm_encoder
290  * @dev: DRM device
291  * @file_priv: drm file to check for lease against.
292  * @id: encoder id
293  *
294  * Returns the encoder with @id, NULL if it doesn't exist. Simple wrapper around
295  * drm_mode_object_find().
296  */
drm_encoder_find(struct drm_device * dev,struct drm_file * file_priv,uint32_t id)297 static inline struct drm_encoder *drm_encoder_find(struct drm_device *dev,
298 						   struct drm_file *file_priv,
299 						   uint32_t id)
300 {
301 	struct drm_mode_object *mo;
302 
303 	mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_ENCODER);
304 
305 	return mo ? obj_to_encoder(mo) : NULL;
306 }
307 
308 void drm_encoder_cleanup(struct drm_encoder *encoder);
309 
310 /**
311  * drm_for_each_encoder_mask - iterate over encoders specified by bitmask
312  * @encoder: the loop cursor
313  * @dev: the DRM device
314  * @encoder_mask: bitmask of encoder indices
315  *
316  * Iterate over all encoders specified by bitmask.
317  */
318 #define drm_for_each_encoder_mask(encoder, dev, encoder_mask) \
319 	list_for_each_entry((encoder), &(dev)->mode_config.encoder_list, head) \
320 		for_each_if ((encoder_mask) & drm_encoder_mask(encoder))
321 
322 /**
323  * drm_for_each_encoder - iterate over all encoders
324  * @encoder: the loop cursor
325  * @dev: the DRM device
326  *
327  * Iterate over all encoders of @dev.
328  */
329 #define drm_for_each_encoder(encoder, dev) \
330 	list_for_each_entry(encoder, &(dev)->mode_config.encoder_list, head)
331 
332 #endif
333