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