blob: 43c4b6a2046d6c8cc03636cdde0879193dd3899f [file] [log] [blame]
Daniel Vetter59e71ee2016-08-29 10:27:55 +02001/*
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
Daniel Vetterc8458c72016-08-29 10:27:57 +020030/**
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 enum_list in &drm_property
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 */
39struct 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 */
71struct 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 &drm_mode_config
195 * 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_reference_blob() and
204 * drm_property_unreference_blob(). They are created using
205 * drm_property_create_blob().
206 */
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200207struct drm_property_blob {
208 struct drm_mode_object base;
209 struct drm_device *dev;
210 struct list_head head_global;
211 struct list_head head_file;
212 size_t length;
213 unsigned char data[];
214};
215
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200216struct drm_prop_enum_list {
217 int type;
218 char *name;
219};
220
221#define obj_to_property(x) container_of(x, struct drm_property, base)
Daniel Vetterafb21ea62016-08-31 18:09:04 +0200222#define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200223
Daniel Vetterc8458c72016-08-29 10:27:57 +0200224/**
225 * drm_property_type_is - check the type of a property
226 * @property: property to check
227 * @type: property type to compare with
228 *
229 * This is a helper function becauase the uapi encoding of property types is
230 * a bit special for historical reasons.
231 */
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200232static inline bool drm_property_type_is(struct drm_property *property,
Daniel Vetterc8458c72016-08-29 10:27:57 +0200233 uint32_t type)
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200234{
235 /* instanceof for props.. handles extended type vs original types: */
236 if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
237 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
238 return property->flags & type;
239}
240
241struct drm_property *drm_property_create(struct drm_device *dev, int flags,
242 const char *name, int num_values);
243struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
244 const char *name,
245 const struct drm_prop_enum_list *props,
246 int num_values);
247struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
248 int flags, const char *name,
249 const struct drm_prop_enum_list *props,
250 int num_props,
251 uint64_t supported_bits);
252struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
253 const char *name,
254 uint64_t min, uint64_t max);
255struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
256 int flags, const char *name,
257 int64_t min, int64_t max);
258struct drm_property *drm_property_create_object(struct drm_device *dev,
259 int flags, const char *name, uint32_t type);
260struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags,
261 const char *name);
262int drm_property_add_enum(struct drm_property *property, int index,
263 uint64_t value, const char *name);
264void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
265
266struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
267 size_t length,
268 const void *data);
269struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
270 uint32_t id);
271int drm_property_replace_global_blob(struct drm_device *dev,
272 struct drm_property_blob **replace,
273 size_t length,
274 const void *data,
275 struct drm_mode_object *obj_holds_id,
276 struct drm_property *prop_holds_id);
277struct drm_property_blob *drm_property_reference_blob(struct drm_property_blob *blob);
278void drm_property_unreference_blob(struct drm_property_blob *blob);
279
Daniel Vetterc8458c72016-08-29 10:27:57 +0200280/**
281 * drm_connector_find - find property object
282 * @dev: DRM device
283 * @id: property object id
284 *
285 * This function looks up the property object specified by id and returns it.
286 */
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200287static inline struct drm_property *drm_property_find(struct drm_device *dev,
Daniel Vetterc8458c72016-08-29 10:27:57 +0200288 uint32_t id)
Daniel Vetter59e71ee2016-08-29 10:27:55 +0200289{
290 struct drm_mode_object *mo;
291 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PROPERTY);
292 return mo ? obj_to_property(mo) : NULL;
293}
294
295#endif