xref: /openbmc/linux/include/drm/drm_property.h (revision 68198dca)
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_PROPERTY_H__
24 #define __DRM_PROPERTY_H__
25 
26 #include <linux/list.h>
27 #include <linux/ctype.h>
28 #include <drm/drm_mode_object.h>
29 
30 /**
31  * struct drm_property_enum - symbolic values for enumerations
32  * @value: numeric property value for this enum entry
33  * @head: list of enum values, linked to &drm_property.enum_list
34  * @name: symbolic name for the enum
35  *
36  * For enumeration and bitmask properties this structure stores the symbolic
37  * decoding for each value. This is used for example for the rotation property.
38  */
39 struct drm_property_enum {
40 	uint64_t value;
41 	struct list_head head;
42 	char name[DRM_PROP_NAME_LEN];
43 };
44 
45 /**
46  * struct drm_property - modeset object property
47  *
48  * This structure represent a modeset object property. It combines both the name
49  * of the property with the set of permissible values. This means that when a
50  * driver wants to use a property with the same name on different objects, but
51  * with different value ranges, then it must create property for each one. An
52  * example would be rotation of &drm_plane, when e.g. the primary plane cannot
53  * be rotated. But if both the name and the value range match, then the same
54  * property structure can be instantiated multiple times for the same object.
55  * Userspace must be able to cope with this and cannot assume that the same
56  * symbolic property will have the same modeset object ID on all modeset
57  * objects.
58  *
59  * Properties are created by one of the special functions, as explained in
60  * detail in the @flags structure member.
61  *
62  * To actually expose a property it must be attached to each object using
63  * drm_object_attach_property(). Currently properties can only be attached to
64  * &drm_connector, &drm_crtc and &drm_plane.
65  *
66  * Properties are also used as the generic metadatatransport for the atomic
67  * IOCTL. Everything that was set directly in structures in the legacy modeset
68  * IOCTLs (like the plane source or destination windows, or e.g. the links to
69  * the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.
70  */
71 struct drm_property {
72 	/**
73 	 * @head: per-device list of properties, for cleanup.
74 	 */
75 	struct list_head head;
76 
77 	/**
78 	 * @base: base KMS object
79 	 */
80 	struct drm_mode_object base;
81 
82 	/**
83 	 * @flags:
84 	 *
85 	 * Property flags and type. A property needs to be one of the following
86 	 * types:
87 	 *
88 	 * DRM_MODE_PROP_RANGE
89 	 *     Range properties report their minimum and maximum admissible unsigned values.
90 	 *     The KMS core verifies that values set by application fit in that
91 	 *     range. The range is unsigned. Range properties are created using
92 	 *     drm_property_create_range().
93 	 *
94 	 * DRM_MODE_PROP_SIGNED_RANGE
95 	 *     Range properties report their minimum and maximum admissible unsigned values.
96 	 *     The KMS core verifies that values set by application fit in that
97 	 *     range. The range is signed. Range properties are created using
98 	 *     drm_property_create_signed_range().
99 	 *
100 	 * DRM_MODE_PROP_ENUM
101 	 *     Enumerated properties take a numerical value that ranges from 0 to
102 	 *     the number of enumerated values defined by the property minus one,
103 	 *     and associate a free-formed string name to each value. Applications
104 	 *     can retrieve the list of defined value-name pairs and use the
105 	 *     numerical value to get and set property instance values. Enum
106 	 *     properties are created using drm_property_create_enum().
107 	 *
108 	 * DRM_MODE_PROP_BITMASK
109 	 *     Bitmask properties are enumeration properties that additionally
110 	 *     restrict all enumerated values to the 0..63 range. Bitmask property
111 	 *     instance values combine one or more of the enumerated bits defined
112 	 *     by the property. Bitmask properties are created using
113 	 *     drm_property_create_bitmask().
114 	 *
115 	 * DRM_MODE_PROB_OBJECT
116 	 *     Object properties are used to link modeset objects. This is used
117 	 *     extensively in the atomic support to create the display pipeline,
118 	 *     by linking &drm_framebuffer to &drm_plane, &drm_plane to
119 	 *     &drm_crtc and &drm_connector to &drm_crtc. An object property can
120 	 *     only link to a specific type of &drm_mode_object, this limit is
121 	 *     enforced by the core. Object properties are created using
122 	 *     drm_property_create_object().
123 	 *
124 	 *     Object properties work like blob properties, but in a more
125 	 *     general fashion. They are limited to atomic drivers and must have
126 	 *     the DRM_MODE_PROP_ATOMIC flag set.
127 	 *
128 	 * DRM_MODE_PROP_BLOB
129 	 *     Blob properties store a binary blob without any format restriction.
130 	 *     The binary blobs are created as KMS standalone objects, and blob
131 	 *     property instance values store the ID of their associated blob
132 	 *     object. Blob properties are created by calling
133 	 *     drm_property_create() with DRM_MODE_PROP_BLOB as the type.
134 	 *
135 	 *     Actual blob objects to contain blob data are created using
136 	 *     drm_property_create_blob(), or through the corresponding IOCTL.
137 	 *
138 	 *     Besides the built-in limit to only accept blob objects blob
139 	 *     properties work exactly like object properties. The only reasons
140 	 *     blob properties exist is backwards compatibility with existing
141 	 *     userspace.
142 	 *
143 	 * In addition a property can have any combination of the below flags:
144 	 *
145 	 * DRM_MODE_PROP_ATOMIC
146 	 *     Set for properties which encode atomic modeset state. Such
147 	 *     properties are not exposed to legacy userspace.
148 	 *
149 	 * DRM_MODE_PROP_IMMUTABLE
150 	 *     Set for properties where userspace cannot be changed by
151 	 *     userspace. The kernel is allowed to update the value of these
152 	 *     properties. This is generally used to expose probe state to
153 	 *     usersapce, e.g. the EDID, or the connector path property on DP
154 	 *     MST sinks.
155 	 */
156 	uint32_t flags;
157 
158 	/**
159 	 * @name: symbolic name of the properties
160 	 */
161 	char name[DRM_PROP_NAME_LEN];
162 
163 	/**
164 	 * @num_values: size of the @values array.
165 	 */
166 	uint32_t num_values;
167 
168 	/**
169 	 * @values:
170 	 *
171 	 * Array with limits and values for the property. The
172 	 * interpretation of these limits is dependent upon the type per @flags.
173 	 */
174 	uint64_t *values;
175 
176 	/**
177 	 * @dev: DRM device
178 	 */
179 	struct drm_device *dev;
180 
181 	/**
182 	 * @enum_list:
183 	 *
184 	 * List of &drm_prop_enum_list structures with the symbolic names for
185 	 * enum and bitmask values.
186 	 */
187 	struct list_head enum_list;
188 };
189 
190 /**
191  * struct drm_property_blob - Blob data for &drm_property
192  * @base: base KMS object
193  * @dev: DRM device
194  * @head_global: entry on the global blob list in
195  * 	&drm_mode_config.property_blob_list.
196  * @head_file: entry on the per-file blob list in &drm_file.blobs list.
197  * @length: size of the blob in bytes, invariant over the lifetime of the object
198  * @data: actual data, embedded at the end of this structure
199  *
200  * Blobs are used to store bigger values than what fits directly into the 64
201  * bits available for a &drm_property.
202  *
203  * Blobs are reference counted using drm_property_blob_get() and
204  * drm_property_blob_put(). They are created using drm_property_create_blob().
205  */
206 struct drm_property_blob {
207 	struct drm_mode_object base;
208 	struct drm_device *dev;
209 	struct list_head head_global;
210 	struct list_head head_file;
211 	size_t length;
212 	unsigned char data[];
213 };
214 
215 struct drm_prop_enum_list {
216 	int type;
217 	const char *name;
218 };
219 
220 #define obj_to_property(x) container_of(x, struct drm_property, base)
221 #define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
222 
223 /**
224  * drm_property_type_is - check the type of a property
225  * @property: property to check
226  * @type: property type to compare with
227  *
228  * This is a helper function becauase the uapi encoding of property types is
229  * a bit special for historical reasons.
230  */
231 static inline bool drm_property_type_is(struct drm_property *property,
232 					uint32_t type)
233 {
234 	/* instanceof for props.. handles extended type vs original types: */
235 	if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
236 		return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
237 	return property->flags & type;
238 }
239 
240 struct drm_property *drm_property_create(struct drm_device *dev, int flags,
241 					 const char *name, int num_values);
242 struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
243 					      const char *name,
244 					      const struct drm_prop_enum_list *props,
245 					      int num_values);
246 struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
247 						 int flags, const char *name,
248 						 const struct drm_prop_enum_list *props,
249 						 int num_props,
250 						 uint64_t supported_bits);
251 struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
252 					       const char *name,
253 					       uint64_t min, uint64_t max);
254 struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
255 						      int flags, const char *name,
256 						      int64_t min, int64_t max);
257 struct drm_property *drm_property_create_object(struct drm_device *dev,
258 						int flags, const char *name, uint32_t type);
259 struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags,
260 					      const char *name);
261 int drm_property_add_enum(struct drm_property *property, int index,
262 			  uint64_t value, const char *name);
263 void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
264 
265 struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
266 						   size_t length,
267 						   const void *data);
268 struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
269 						   uint32_t id);
270 int drm_property_replace_global_blob(struct drm_device *dev,
271 				     struct drm_property_blob **replace,
272 				     size_t length,
273 				     const void *data,
274 				     struct drm_mode_object *obj_holds_id,
275 				     struct drm_property *prop_holds_id);
276 bool drm_property_replace_blob(struct drm_property_blob **blob,
277 			       struct drm_property_blob *new_blob);
278 struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
279 void drm_property_blob_put(struct drm_property_blob *blob);
280 
281 /**
282  * drm_property_reference_blob - acquire a blob property reference
283  * @blob: DRM blob property
284  *
285  * This is a compatibility alias for drm_property_blob_get() and should not be
286  * used by new code.
287  */
288 static inline struct drm_property_blob *
289 drm_property_reference_blob(struct drm_property_blob *blob)
290 {
291 	return drm_property_blob_get(blob);
292 }
293 
294 /**
295  * drm_property_unreference_blob - release a blob property reference
296  * @blob: DRM blob property
297  *
298  * This is a compatibility alias for drm_property_blob_put() and should not be
299  * used by new code.
300  */
301 static inline void
302 drm_property_unreference_blob(struct drm_property_blob *blob)
303 {
304 	drm_property_blob_put(blob);
305 }
306 
307 /**
308  * drm_property_find - find property object
309  * @dev: DRM device
310  * @file_priv: drm file to check for lease against.
311  * @id: property object id
312  *
313  * This function looks up the property object specified by id and returns it.
314  */
315 static inline struct drm_property *drm_property_find(struct drm_device *dev,
316 						     struct drm_file *file_priv,
317 						     uint32_t id)
318 {
319 	struct drm_mode_object *mo;
320 	mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
321 	return mo ? obj_to_property(mo) : NULL;
322 }
323 
324 #endif
325