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(6, 7)
198 void *__drmm_encoder_alloc(struct drm_device *dev,
199 			   size_t size, size_t offset,
200 			   const struct drm_encoder_funcs *funcs,
201 			   int encoder_type,
202 			   const char *name, ...);
203 
204 /**
205  * drmm_encoder_alloc - Allocate and initialize an encoder
206  * @dev: drm device
207  * @type: the type of the struct which contains struct &drm_encoder
208  * @member: the name of the &drm_encoder within @type
209  * @funcs: callbacks for this encoder (optional)
210  * @encoder_type: user visible type of the encoder
211  * @name: printf style format string for the encoder name, or NULL for default name
212  *
213  * Allocates and initializes an encoder. Encoder should be subclassed as part of
214  * driver encoder objects. Cleanup is automatically handled through registering
215  * drm_encoder_cleanup() with drmm_add_action().
216  *
217  * The @drm_encoder_funcs.destroy hook must be NULL.
218  *
219  * Returns:
220  * Pointer to new encoder, or ERR_PTR on failure.
221  */
222 #define drmm_encoder_alloc(dev, type, member, funcs, encoder_type, name, ...) \
223 	((type *)__drmm_encoder_alloc(dev, sizeof(type), \
224 				      offsetof(type, member), funcs, \
225 				      encoder_type, name, ##__VA_ARGS__))
226 
227 /**
228  * drmm_plain_encoder_alloc - Allocate and initialize an encoder
229  * @dev: drm device
230  * @funcs: callbacks for this encoder (optional)
231  * @encoder_type: user visible type of the encoder
232  * @name: printf style format string for the encoder name, or NULL for default name
233  *
234  * This is a simplified version of drmm_encoder_alloc(), which only allocates
235  * and returns a struct drm_encoder instance, with no subclassing.
236  *
237  * Returns:
238  * Pointer to the new drm_encoder struct, or ERR_PTR on failure.
239  */
240 #define drmm_plain_encoder_alloc(dev, funcs, encoder_type, name, ...) \
241 	((struct drm_encoder *) \
242 	 __drmm_encoder_alloc(dev, sizeof(struct drm_encoder), \
243 			      0, funcs, encoder_type, name, ##__VA_ARGS__))
244 
245 /**
246  * drm_encoder_index - find the index of a registered encoder
247  * @encoder: encoder to find index for
248  *
249  * Given a registered encoder, return the index of that encoder within a DRM
250  * device's list of encoders.
251  */
drm_encoder_index(const struct drm_encoder * encoder)252 static inline unsigned int drm_encoder_index(const struct drm_encoder *encoder)
253 {
254 	return encoder->index;
255 }
256 
257 /**
258  * drm_encoder_mask - find the mask of a registered encoder
259  * @encoder: encoder to find mask for
260  *
261  * Given a registered encoder, return the mask bit of that encoder for an
262  * encoder's possible_clones field.
263  */
drm_encoder_mask(const struct drm_encoder * encoder)264 static inline u32 drm_encoder_mask(const struct drm_encoder *encoder)
265 {
266 	return 1 << drm_encoder_index(encoder);
267 }
268 
269 /**
270  * drm_encoder_crtc_ok - can a given crtc drive a given encoder?
271  * @encoder: encoder to test
272  * @crtc: crtc to test
273  *
274  * Returns false if @encoder can't be driven by @crtc, true otherwise.
275  */
drm_encoder_crtc_ok(struct drm_encoder * encoder,struct drm_crtc * crtc)276 static inline bool drm_encoder_crtc_ok(struct drm_encoder *encoder,
277 				       struct drm_crtc *crtc)
278 {
279 	return !!(encoder->possible_crtcs & drm_crtc_mask(crtc));
280 }
281 
282 /**
283  * drm_encoder_find - find a &drm_encoder
284  * @dev: DRM device
285  * @file_priv: drm file to check for lease against.
286  * @id: encoder id
287  *
288  * Returns the encoder with @id, NULL if it doesn't exist. Simple wrapper around
289  * drm_mode_object_find().
290  */
drm_encoder_find(struct drm_device * dev,struct drm_file * file_priv,uint32_t id)291 static inline struct drm_encoder *drm_encoder_find(struct drm_device *dev,
292 						   struct drm_file *file_priv,
293 						   uint32_t id)
294 {
295 	struct drm_mode_object *mo;
296 
297 	mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_ENCODER);
298 
299 	return mo ? obj_to_encoder(mo) : NULL;
300 }
301 
302 void drm_encoder_cleanup(struct drm_encoder *encoder);
303 
304 /**
305  * drm_for_each_encoder_mask - iterate over encoders specified by bitmask
306  * @encoder: the loop cursor
307  * @dev: the DRM device
308  * @encoder_mask: bitmask of encoder indices
309  *
310  * Iterate over all encoders specified by bitmask.
311  */
312 #define drm_for_each_encoder_mask(encoder, dev, encoder_mask) \
313 	list_for_each_entry((encoder), &(dev)->mode_config.encoder_list, head) \
314 		for_each_if ((encoder_mask) & drm_encoder_mask(encoder))
315 
316 /**
317  * drm_for_each_encoder - iterate over all encoders
318  * @encoder: the loop cursor
319  * @dev: the DRM device
320  *
321  * Iterate over all encoders of @dev.
322  */
323 #define drm_for_each_encoder(encoder, dev) \
324 	list_for_each_entry(encoder, &(dev)->mode_config.encoder_list, head)
325 
326 #endif
327