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