xref: /openbmc/linux/include/drm/drm_property.h (revision 418da172)
159e71ee7SDaniel Vetter /*
259e71ee7SDaniel Vetter  * Copyright (c) 2016 Intel Corporation
359e71ee7SDaniel Vetter  *
459e71ee7SDaniel Vetter  * Permission to use, copy, modify, distribute, and sell this software and its
559e71ee7SDaniel Vetter  * documentation for any purpose is hereby granted without fee, provided that
659e71ee7SDaniel Vetter  * the above copyright notice appear in all copies and that both that copyright
759e71ee7SDaniel Vetter  * notice and this permission notice appear in supporting documentation, and
859e71ee7SDaniel Vetter  * that the name of the copyright holders not be used in advertising or
959e71ee7SDaniel Vetter  * publicity pertaining to distribution of the software without specific,
1059e71ee7SDaniel Vetter  * written prior permission.  The copyright holders make no representations
1159e71ee7SDaniel Vetter  * about the suitability of this software for any purpose.  It is provided "as
1259e71ee7SDaniel Vetter  * is" without express or implied warranty.
1359e71ee7SDaniel Vetter  *
1459e71ee7SDaniel Vetter  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
1559e71ee7SDaniel Vetter  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
1659e71ee7SDaniel Vetter  * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
1759e71ee7SDaniel Vetter  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
1859e71ee7SDaniel Vetter  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
1959e71ee7SDaniel Vetter  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
2059e71ee7SDaniel Vetter  * OF THIS SOFTWARE.
2159e71ee7SDaniel Vetter  */
2259e71ee7SDaniel Vetter 
2359e71ee7SDaniel Vetter #ifndef __DRM_PROPERTY_H__
2459e71ee7SDaniel Vetter #define __DRM_PROPERTY_H__
2559e71ee7SDaniel Vetter 
2659e71ee7SDaniel Vetter #include <linux/list.h>
2759e71ee7SDaniel Vetter #include <linux/ctype.h>
2859e71ee7SDaniel Vetter #include <drm/drm_mode_object.h>
2959e71ee7SDaniel Vetter 
30c8458c7eSDaniel Vetter /**
31c8458c7eSDaniel Vetter  * struct drm_property_enum - symbolic values for enumerations
32c8458c7eSDaniel Vetter  * @value: numeric property value for this enum entry
33d574528aSDaniel Vetter  * @head: list of enum values, linked to &drm_property.enum_list
34c8458c7eSDaniel Vetter  * @name: symbolic name for the enum
35c8458c7eSDaniel Vetter  *
36c8458c7eSDaniel Vetter  * For enumeration and bitmask properties this structure stores the symbolic
37c8458c7eSDaniel Vetter  * decoding for each value. This is used for example for the rotation property.
38c8458c7eSDaniel Vetter  */
39c8458c7eSDaniel Vetter struct drm_property_enum {
40c8458c7eSDaniel Vetter 	uint64_t value;
41c8458c7eSDaniel Vetter 	struct list_head head;
42c8458c7eSDaniel Vetter 	char name[DRM_PROP_NAME_LEN];
43c8458c7eSDaniel Vetter };
44c8458c7eSDaniel Vetter 
45c8458c7eSDaniel Vetter /**
46c8458c7eSDaniel Vetter  * struct drm_property - modeset object property
47c8458c7eSDaniel Vetter  *
48c8458c7eSDaniel Vetter  * This structure represent a modeset object property. It combines both the name
49c8458c7eSDaniel Vetter  * of the property with the set of permissible values. This means that when a
50c8458c7eSDaniel Vetter  * driver wants to use a property with the same name on different objects, but
51c8458c7eSDaniel Vetter  * with different value ranges, then it must create property for each one. An
52c8458c7eSDaniel Vetter  * example would be rotation of &drm_plane, when e.g. the primary plane cannot
53c8458c7eSDaniel Vetter  * be rotated. But if both the name and the value range match, then the same
54c8458c7eSDaniel Vetter  * property structure can be instantiated multiple times for the same object.
55c8458c7eSDaniel Vetter  * Userspace must be able to cope with this and cannot assume that the same
56c8458c7eSDaniel Vetter  * symbolic property will have the same modeset object ID on all modeset
57c8458c7eSDaniel Vetter  * objects.
58c8458c7eSDaniel Vetter  *
59c8458c7eSDaniel Vetter  * Properties are created by one of the special functions, as explained in
60c8458c7eSDaniel Vetter  * detail in the @flags structure member.
61c8458c7eSDaniel Vetter  *
62c8458c7eSDaniel Vetter  * To actually expose a property it must be attached to each object using
63c8458c7eSDaniel Vetter  * drm_object_attach_property(). Currently properties can only be attached to
64c8458c7eSDaniel Vetter  * &drm_connector, &drm_crtc and &drm_plane.
65c8458c7eSDaniel Vetter  *
66c8458c7eSDaniel Vetter  * Properties are also used as the generic metadatatransport for the atomic
67c8458c7eSDaniel Vetter  * IOCTL. Everything that was set directly in structures in the legacy modeset
68c8458c7eSDaniel Vetter  * IOCTLs (like the plane source or destination windows, or e.g. the links to
69c8458c7eSDaniel Vetter  * the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.
70c8458c7eSDaniel Vetter  */
71c8458c7eSDaniel Vetter struct drm_property {
72c8458c7eSDaniel Vetter 	/**
73c8458c7eSDaniel Vetter 	 * @head: per-device list of properties, for cleanup.
74c8458c7eSDaniel Vetter 	 */
75c8458c7eSDaniel Vetter 	struct list_head head;
76c8458c7eSDaniel Vetter 
77c8458c7eSDaniel Vetter 	/**
78c8458c7eSDaniel Vetter 	 * @base: base KMS object
79c8458c7eSDaniel Vetter 	 */
80c8458c7eSDaniel Vetter 	struct drm_mode_object base;
81c8458c7eSDaniel Vetter 
82c8458c7eSDaniel Vetter 	/**
83c8458c7eSDaniel Vetter 	 * @flags:
84c8458c7eSDaniel Vetter 	 *
85c8458c7eSDaniel Vetter 	 * Property flags and type. A property needs to be one of the following
86c8458c7eSDaniel Vetter 	 * types:
87c8458c7eSDaniel Vetter 	 *
88c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_RANGE
89c8458c7eSDaniel Vetter 	 *     Range properties report their minimum and maximum admissible unsigned values.
90c8458c7eSDaniel Vetter 	 *     The KMS core verifies that values set by application fit in that
91c8458c7eSDaniel Vetter 	 *     range. The range is unsigned. Range properties are created using
92c8458c7eSDaniel Vetter 	 *     drm_property_create_range().
93c8458c7eSDaniel Vetter 	 *
94c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_SIGNED_RANGE
95c8458c7eSDaniel Vetter 	 *     Range properties report their minimum and maximum admissible unsigned values.
96c8458c7eSDaniel Vetter 	 *     The KMS core verifies that values set by application fit in that
97c8458c7eSDaniel Vetter 	 *     range. The range is signed. Range properties are created using
98c8458c7eSDaniel Vetter 	 *     drm_property_create_signed_range().
99c8458c7eSDaniel Vetter 	 *
100c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_ENUM
101c8458c7eSDaniel Vetter 	 *     Enumerated properties take a numerical value that ranges from 0 to
102c8458c7eSDaniel Vetter 	 *     the number of enumerated values defined by the property minus one,
103c8458c7eSDaniel Vetter 	 *     and associate a free-formed string name to each value. Applications
104c8458c7eSDaniel Vetter 	 *     can retrieve the list of defined value-name pairs and use the
105c8458c7eSDaniel Vetter 	 *     numerical value to get and set property instance values. Enum
106c8458c7eSDaniel Vetter 	 *     properties are created using drm_property_create_enum().
107c8458c7eSDaniel Vetter 	 *
108c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_BITMASK
109c8458c7eSDaniel Vetter 	 *     Bitmask properties are enumeration properties that additionally
110c8458c7eSDaniel Vetter 	 *     restrict all enumerated values to the 0..63 range. Bitmask property
111c8458c7eSDaniel Vetter 	 *     instance values combine one or more of the enumerated bits defined
112c8458c7eSDaniel Vetter 	 *     by the property. Bitmask properties are created using
113c8458c7eSDaniel Vetter 	 *     drm_property_create_bitmask().
114c8458c7eSDaniel Vetter 	 *
115c8458c7eSDaniel Vetter 	 * DRM_MODE_PROB_OBJECT
116c8458c7eSDaniel Vetter 	 *     Object properties are used to link modeset objects. This is used
117c8458c7eSDaniel Vetter 	 *     extensively in the atomic support to create the display pipeline,
118c8458c7eSDaniel Vetter 	 *     by linking &drm_framebuffer to &drm_plane, &drm_plane to
119c8458c7eSDaniel Vetter 	 *     &drm_crtc and &drm_connector to &drm_crtc. An object property can
120c8458c7eSDaniel Vetter 	 *     only link to a specific type of &drm_mode_object, this limit is
121c8458c7eSDaniel Vetter 	 *     enforced by the core. Object properties are created using
122c8458c7eSDaniel Vetter 	 *     drm_property_create_object().
123c8458c7eSDaniel Vetter 	 *
124c8458c7eSDaniel Vetter 	 *     Object properties work like blob properties, but in a more
125c8458c7eSDaniel Vetter 	 *     general fashion. They are limited to atomic drivers and must have
126c8458c7eSDaniel Vetter 	 *     the DRM_MODE_PROP_ATOMIC flag set.
127c8458c7eSDaniel Vetter 	 *
128c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_BLOB
129c8458c7eSDaniel Vetter 	 *     Blob properties store a binary blob without any format restriction.
130c8458c7eSDaniel Vetter 	 *     The binary blobs are created as KMS standalone objects, and blob
131c8458c7eSDaniel Vetter 	 *     property instance values store the ID of their associated blob
132c8458c7eSDaniel Vetter 	 *     object. Blob properties are created by calling
133c8458c7eSDaniel Vetter 	 *     drm_property_create() with DRM_MODE_PROP_BLOB as the type.
134c8458c7eSDaniel Vetter 	 *
135c8458c7eSDaniel Vetter 	 *     Actual blob objects to contain blob data are created using
136c8458c7eSDaniel Vetter 	 *     drm_property_create_blob(), or through the corresponding IOCTL.
137c8458c7eSDaniel Vetter 	 *
138c8458c7eSDaniel Vetter 	 *     Besides the built-in limit to only accept blob objects blob
139c8458c7eSDaniel Vetter 	 *     properties work exactly like object properties. The only reasons
140c8458c7eSDaniel Vetter 	 *     blob properties exist is backwards compatibility with existing
141c8458c7eSDaniel Vetter 	 *     userspace.
142c8458c7eSDaniel Vetter 	 *
143c8458c7eSDaniel Vetter 	 * In addition a property can have any combination of the below flags:
144c8458c7eSDaniel Vetter 	 *
145c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_ATOMIC
146c8458c7eSDaniel Vetter 	 *     Set for properties which encode atomic modeset state. Such
147c8458c7eSDaniel Vetter 	 *     properties are not exposed to legacy userspace.
148c8458c7eSDaniel Vetter 	 *
149c8458c7eSDaniel Vetter 	 * DRM_MODE_PROP_IMMUTABLE
150c8458c7eSDaniel Vetter 	 *     Set for properties where userspace cannot be changed by
151c8458c7eSDaniel Vetter 	 *     userspace. The kernel is allowed to update the value of these
152c8458c7eSDaniel Vetter 	 *     properties. This is generally used to expose probe state to
153c8458c7eSDaniel Vetter 	 *     usersapce, e.g. the EDID, or the connector path property on DP
154c8458c7eSDaniel Vetter 	 *     MST sinks.
155c8458c7eSDaniel Vetter 	 */
156c8458c7eSDaniel Vetter 	uint32_t flags;
157c8458c7eSDaniel Vetter 
158c8458c7eSDaniel Vetter 	/**
159c8458c7eSDaniel Vetter 	 * @name: symbolic name of the properties
160c8458c7eSDaniel Vetter 	 */
161c8458c7eSDaniel Vetter 	char name[DRM_PROP_NAME_LEN];
162c8458c7eSDaniel Vetter 
163c8458c7eSDaniel Vetter 	/**
164c8458c7eSDaniel Vetter 	 * @num_values: size of the @values array.
165c8458c7eSDaniel Vetter 	 */
166c8458c7eSDaniel Vetter 	uint32_t num_values;
167c8458c7eSDaniel Vetter 
168c8458c7eSDaniel Vetter 	/**
169c8458c7eSDaniel Vetter 	 * @values:
170c8458c7eSDaniel Vetter 	 *
171c8458c7eSDaniel Vetter 	 * Array with limits and values for the property. The
172c8458c7eSDaniel Vetter 	 * interpretation of these limits is dependent upon the type per @flags.
173c8458c7eSDaniel Vetter 	 */
174c8458c7eSDaniel Vetter 	uint64_t *values;
175c8458c7eSDaniel Vetter 
176c8458c7eSDaniel Vetter 	/**
177c8458c7eSDaniel Vetter 	 * @dev: DRM device
178c8458c7eSDaniel Vetter 	 */
179c8458c7eSDaniel Vetter 	struct drm_device *dev;
180c8458c7eSDaniel Vetter 
181c8458c7eSDaniel Vetter 	/**
182c8458c7eSDaniel Vetter 	 * @enum_list:
183c8458c7eSDaniel Vetter 	 *
184c8458c7eSDaniel Vetter 	 * List of &drm_prop_enum_list structures with the symbolic names for
185c8458c7eSDaniel Vetter 	 * enum and bitmask values.
186c8458c7eSDaniel Vetter 	 */
187c8458c7eSDaniel Vetter 	struct list_head enum_list;
188c8458c7eSDaniel Vetter };
189c8458c7eSDaniel Vetter 
190c8458c7eSDaniel Vetter /**
191c8458c7eSDaniel Vetter  * struct drm_property_blob - Blob data for &drm_property
192c8458c7eSDaniel Vetter  * @base: base KMS object
193c8458c7eSDaniel Vetter  * @dev: DRM device
194d574528aSDaniel Vetter  * @head_global: entry on the global blob list in
195d574528aSDaniel Vetter  * 	&drm_mode_config.property_blob_list.
196d574528aSDaniel Vetter  * @head_file: entry on the per-file blob list in &drm_file.blobs list.
197c8458c7eSDaniel Vetter  * @length: size of the blob in bytes, invariant over the lifetime of the object
198c8458c7eSDaniel Vetter  * @data: actual data, embedded at the end of this structure
199c8458c7eSDaniel Vetter  *
200c8458c7eSDaniel Vetter  * Blobs are used to store bigger values than what fits directly into the 64
201c8458c7eSDaniel Vetter  * bits available for a &drm_property.
202c8458c7eSDaniel Vetter  *
2036472e509SThierry Reding  * Blobs are reference counted using drm_property_blob_get() and
2046472e509SThierry Reding  * drm_property_blob_put(). They are created using drm_property_create_blob().
205c8458c7eSDaniel Vetter  */
20659e71ee7SDaniel Vetter struct drm_property_blob {
20759e71ee7SDaniel Vetter 	struct drm_mode_object base;
20859e71ee7SDaniel Vetter 	struct drm_device *dev;
20959e71ee7SDaniel Vetter 	struct list_head head_global;
21059e71ee7SDaniel Vetter 	struct list_head head_file;
21159e71ee7SDaniel Vetter 	size_t length;
21259e71ee7SDaniel Vetter 	unsigned char data[];
21359e71ee7SDaniel Vetter };
21459e71ee7SDaniel Vetter 
21559e71ee7SDaniel Vetter struct drm_prop_enum_list {
21659e71ee7SDaniel Vetter 	int type;
217dc629141SJyri Sarha 	const char *name;
21859e71ee7SDaniel Vetter };
21959e71ee7SDaniel Vetter 
22059e71ee7SDaniel Vetter #define obj_to_property(x) container_of(x, struct drm_property, base)
221afb21ea6SDaniel Vetter #define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
22259e71ee7SDaniel Vetter 
223c8458c7eSDaniel Vetter /**
224c8458c7eSDaniel Vetter  * drm_property_type_is - check the type of a property
225c8458c7eSDaniel Vetter  * @property: property to check
226c8458c7eSDaniel Vetter  * @type: property type to compare with
227c8458c7eSDaniel Vetter  *
228c8458c7eSDaniel Vetter  * This is a helper function becauase the uapi encoding of property types is
229c8458c7eSDaniel Vetter  * a bit special for historical reasons.
230c8458c7eSDaniel Vetter  */
23159e71ee7SDaniel Vetter static inline bool drm_property_type_is(struct drm_property *property,
23259e71ee7SDaniel Vetter 					uint32_t type)
23359e71ee7SDaniel Vetter {
23459e71ee7SDaniel Vetter 	/* instanceof for props.. handles extended type vs original types: */
23559e71ee7SDaniel Vetter 	if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
23659e71ee7SDaniel Vetter 		return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
23759e71ee7SDaniel Vetter 	return property->flags & type;
23859e71ee7SDaniel Vetter }
23959e71ee7SDaniel Vetter 
24059e71ee7SDaniel Vetter struct drm_property *drm_property_create(struct drm_device *dev, int flags,
24159e71ee7SDaniel Vetter 					 const char *name, int num_values);
24259e71ee7SDaniel Vetter struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
24359e71ee7SDaniel Vetter 					      const char *name,
24459e71ee7SDaniel Vetter 					      const struct drm_prop_enum_list *props,
24559e71ee7SDaniel Vetter 					      int num_values);
24659e71ee7SDaniel Vetter struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
24759e71ee7SDaniel Vetter 						 int flags, const char *name,
24859e71ee7SDaniel Vetter 						 const struct drm_prop_enum_list *props,
24959e71ee7SDaniel Vetter 						 int num_props,
25059e71ee7SDaniel Vetter 						 uint64_t supported_bits);
25159e71ee7SDaniel Vetter struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
25259e71ee7SDaniel Vetter 					       const char *name,
25359e71ee7SDaniel Vetter 					       uint64_t min, uint64_t max);
25459e71ee7SDaniel Vetter struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
25559e71ee7SDaniel Vetter 						      int flags, const char *name,
25659e71ee7SDaniel Vetter 						      int64_t min, int64_t max);
25759e71ee7SDaniel Vetter struct drm_property *drm_property_create_object(struct drm_device *dev,
25859e71ee7SDaniel Vetter 						int flags, const char *name, uint32_t type);
25959e71ee7SDaniel Vetter struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags,
26059e71ee7SDaniel Vetter 					      const char *name);
26159e71ee7SDaniel Vetter int drm_property_add_enum(struct drm_property *property, int index,
26259e71ee7SDaniel Vetter 			  uint64_t value, const char *name);
26359e71ee7SDaniel Vetter void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
26459e71ee7SDaniel Vetter 
26559e71ee7SDaniel Vetter struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
26659e71ee7SDaniel Vetter 						   size_t length,
26759e71ee7SDaniel Vetter 						   const void *data);
26859e71ee7SDaniel Vetter struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
26959e71ee7SDaniel Vetter 						   uint32_t id);
27059e71ee7SDaniel Vetter int drm_property_replace_global_blob(struct drm_device *dev,
27159e71ee7SDaniel Vetter 				     struct drm_property_blob **replace,
27259e71ee7SDaniel Vetter 				     size_t length,
27359e71ee7SDaniel Vetter 				     const void *data,
27459e71ee7SDaniel Vetter 				     struct drm_mode_object *obj_holds_id,
27559e71ee7SDaniel Vetter 				     struct drm_property *prop_holds_id);
2765f057ffdSPeter Rosin bool drm_property_replace_blob(struct drm_property_blob **blob,
2775f057ffdSPeter Rosin 			       struct drm_property_blob *new_blob);
2786472e509SThierry Reding struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
2796472e509SThierry Reding void drm_property_blob_put(struct drm_property_blob *blob);
2806472e509SThierry Reding 
2816472e509SThierry Reding /**
2826472e509SThierry Reding  * drm_property_reference_blob - acquire a blob property reference
2836472e509SThierry Reding  * @blob: DRM blob property
2846472e509SThierry Reding  *
2856472e509SThierry Reding  * This is a compatibility alias for drm_property_blob_get() and should not be
2866472e509SThierry Reding  * used by new code.
2876472e509SThierry Reding  */
2886472e509SThierry Reding static inline struct drm_property_blob *
2896472e509SThierry Reding drm_property_reference_blob(struct drm_property_blob *blob)
2906472e509SThierry Reding {
2916472e509SThierry Reding 	return drm_property_blob_get(blob);
2926472e509SThierry Reding }
2936472e509SThierry Reding 
2946472e509SThierry Reding /**
2956472e509SThierry Reding  * drm_property_unreference_blob - release a blob property reference
2966472e509SThierry Reding  * @blob: DRM blob property
2976472e509SThierry Reding  *
2986472e509SThierry Reding  * This is a compatibility alias for drm_property_blob_put() and should not be
2996472e509SThierry Reding  * used by new code.
3006472e509SThierry Reding  */
3016472e509SThierry Reding static inline void
3026472e509SThierry Reding drm_property_unreference_blob(struct drm_property_blob *blob)
3036472e509SThierry Reding {
3046472e509SThierry Reding 	drm_property_blob_put(blob);
3056472e509SThierry Reding }
30659e71ee7SDaniel Vetter 
307c8458c7eSDaniel Vetter /**
308c8458c7eSDaniel Vetter  * drm_connector_find - find property object
309c8458c7eSDaniel Vetter  * @dev: DRM device
310c8458c7eSDaniel Vetter  * @id: property object id
311c8458c7eSDaniel Vetter  *
312c8458c7eSDaniel Vetter  * This function looks up the property object specified by id and returns it.
313c8458c7eSDaniel Vetter  */
31459e71ee7SDaniel Vetter static inline struct drm_property *drm_property_find(struct drm_device *dev,
315418da172SKeith Packard 						     struct drm_file *file_priv,
31659e71ee7SDaniel Vetter 						     uint32_t id)
31759e71ee7SDaniel Vetter {
31859e71ee7SDaniel Vetter 	struct drm_mode_object *mo;
319418da172SKeith Packard 	mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
32059e71ee7SDaniel Vetter 	return mo ? obj_to_property(mo) : NULL;
32159e71ee7SDaniel Vetter }
32259e71ee7SDaniel Vetter 
32359e71ee7SDaniel Vetter #endif
324