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