Merge tag 'audit-pr-20211019' of git://git.kernel.org/pub/scm/linux/kernel/git/pcmoor...
[platform/kernel/linux-starfive.git] / include / drm / drm_property.h
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         if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
246                 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
247         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         mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
307         return mo ? obj_to_property(mo) : NULL;
308 }
309
310 #endif