tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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 */
41struct 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 */
73struct 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.
157 */
158 uint32_t flags;
159
160 /**
161 * @name: symbolic name of the properties
162 */
163 char name[DRM_PROP_NAME_LEN];
164
165 /**
166 * @num_values: size of the @values array.
167 */
168 uint32_t num_values;
169
170 /**
171 * @values:
172 *
173 * Array with limits and values for the property. The
174 * interpretation of these limits is dependent upon the type per @flags.
175 */
176 uint64_t *values;
177
178 /**
179 * @dev: DRM device
180 */
181 struct drm_device *dev;
182
183 /**
184 * @enum_list:
185 *
186 * List of &drm_prop_enum_list structures with the symbolic names for
187 * enum and bitmask values.
188 */
189 struct list_head enum_list;
190};
191
192/**
193 * struct drm_property_blob - Blob data for &drm_property
194 * @base: base KMS object
195 * @dev: DRM device
196 * @head_global: entry on the global blob list in
197 * &drm_mode_config.property_blob_list.
198 * @head_file: entry on the per-file blob list in &drm_file.blobs list.
199 * @length: size of the blob in bytes, invariant over the lifetime of the object
200 * @data: actual data, embedded at the end of this structure
201 *
202 * Blobs are used to store bigger values than what fits directly into the 64
203 * bits available for a &drm_property.
204 *
205 * Blobs are reference counted using drm_property_blob_get() and
206 * drm_property_blob_put(). They are created using drm_property_create_blob().
207 */
208struct drm_property_blob {
209 struct drm_mode_object base;
210 struct drm_device *dev;
211 struct list_head head_global;
212 struct list_head head_file;
213 size_t length;
214 void *data;
215};
216
217struct drm_prop_enum_list {
218 int type;
219 const char *name;
220};
221
222#define obj_to_property(x) container_of(x, struct drm_property, base)
223#define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
224
225/**
226 * drm_property_type_is - check the type of a property
227 * @property: property to check
228 * @type: property type to compare with
229 *
230 * This is a helper function becauase the uapi encoding of property types is
231 * a bit special for historical reasons.
232 */
233static inline bool drm_property_type_is(struct drm_property *property,
234 uint32_t type)
235{
236 /* instanceof for props.. handles extended type vs original types: */
237 if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
238 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
239 return property->flags & type;
240}
241
242struct drm_property *drm_property_create(struct drm_device *dev,
243 u32 flags, const char *name,
244 int num_values);
245struct drm_property *drm_property_create_enum(struct drm_device *dev,
246 u32 flags, const char *name,
247 const struct drm_prop_enum_list *props,
248 int num_values);
249struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
250 u32 flags, const char *name,
251 const struct drm_prop_enum_list *props,
252 int num_props,
253 uint64_t supported_bits);
254struct drm_property *drm_property_create_range(struct drm_device *dev,
255 u32 flags, const char *name,
256 uint64_t min, uint64_t max);
257struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
258 u32 flags, const char *name,
259 int64_t min, int64_t max);
260struct drm_property *drm_property_create_object(struct drm_device *dev,
261 u32 flags, const char *name,
262 uint32_t type);
263struct drm_property *drm_property_create_bool(struct drm_device *dev,
264 u32 flags, const char *name);
265int drm_property_add_enum(struct drm_property *property,
266 uint64_t value, const char *name);
267void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
268
269struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
270 size_t length,
271 const void *data);
272struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
273 uint32_t id);
274int drm_property_replace_global_blob(struct drm_device *dev,
275 struct drm_property_blob **replace,
276 size_t length,
277 const void *data,
278 struct drm_mode_object *obj_holds_id,
279 struct drm_property *prop_holds_id);
280bool drm_property_replace_blob(struct drm_property_blob **blob,
281 struct drm_property_blob *new_blob);
282struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
283void drm_property_blob_put(struct drm_property_blob *blob);
284
285/**
286 * drm_property_find - find property object
287 * @dev: DRM device
288 * @file_priv: drm file to check for lease against.
289 * @id: property object id
290 *
291 * This function looks up the property object specified by id and returns it.
292 */
293static inline struct drm_property *drm_property_find(struct drm_device *dev,
294 struct drm_file *file_priv,
295 uint32_t id)
296{
297 struct drm_mode_object *mo;
298 mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
299 return mo ? obj_to_property(mo) : NULL;
300}
301
302#endif