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/**
 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 &drm_property.enum_list
 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
195 * 	&drm_mode_config.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_blob_get() and
204 * drm_property_blob_put(). They are created using drm_property_create_blob().
205 */
206struct drm_property_blob {
207	struct drm_mode_object base;
208	struct drm_device *dev;
209	struct list_head head_global;
210	struct list_head head_file;
211	size_t length;
212	void *data;
213};
214
215struct drm_prop_enum_list {
216	int type;
217	const char *name;
218};
219
220#define obj_to_property(x) container_of(x, struct drm_property, base)
221#define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
222
223/**
224 * drm_property_type_is - check the type of a property
225 * @property: property to check
226 * @type: property type to compare with
227 *
228 * This is a helper function becauase the uapi encoding of property types is
229 * a bit special for historical reasons.
230 */
231static inline bool drm_property_type_is(struct drm_property *property,
232					uint32_t type)
233{
234	/* instanceof for props.. handles extended type vs original types: */
235	if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
236		return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
237	return property->flags & type;
238}
239
240struct drm_property *drm_property_create(struct drm_device *dev,
241					 u32 flags, const char *name,
242					 int num_values);
243struct drm_property *drm_property_create_enum(struct drm_device *dev,
244					      u32 flags, 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						 u32 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,
253					       u32 flags, const char *name,
254					       uint64_t min, uint64_t max);
255struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
256						      u32 flags, const char *name,
257						      int64_t min, int64_t max);
258struct drm_property *drm_property_create_object(struct drm_device *dev,
259						u32 flags, const char *name,
260						uint32_t type);
261struct drm_property *drm_property_create_bool(struct drm_device *dev,
262					      u32 flags, const char *name);
263int drm_property_add_enum(struct drm_property *property, int index,
264			  uint64_t value, const char *name);
265void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
266
267struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
268						   size_t length,
269						   const void *data);
270struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
271						   uint32_t id);
272int drm_property_replace_global_blob(struct drm_device *dev,
273				     struct drm_property_blob **replace,
274				     size_t length,
275				     const void *data,
276				     struct drm_mode_object *obj_holds_id,
277				     struct drm_property *prop_holds_id);
278bool drm_property_replace_blob(struct drm_property_blob **blob,
279			       struct drm_property_blob *new_blob);
280struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
281void drm_property_blob_put(struct drm_property_blob *blob);
282
283/**
284 * drm_property_reference_blob - acquire a blob property reference
285 * @blob: DRM blob property
286 *
287 * This is a compatibility alias for drm_property_blob_get() and should not be
288 * used by new code.
289 */
290static inline struct drm_property_blob *
291drm_property_reference_blob(struct drm_property_blob *blob)
292{
293	return drm_property_blob_get(blob);
294}
295
296/**
297 * drm_property_unreference_blob - release a blob property reference
298 * @blob: DRM blob property
299 *
300 * This is a compatibility alias for drm_property_blob_put() and should not be
301 * used by new code.
302 */
303static inline void
304drm_property_unreference_blob(struct drm_property_blob *blob)
305{
306	drm_property_blob_put(blob);
307}
308
309/**
310 * drm_property_find - find property object
311 * @dev: DRM device
312 * @file_priv: drm file to check for lease against.
313 * @id: property object id
314 *
315 * This function looks up the property object specified by id and returns it.
316 */
317static inline struct drm_property *drm_property_find(struct drm_device *dev,
318						     struct drm_file *file_priv,
319						     uint32_t id)
320{
321	struct drm_mode_object *mo;
322	mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
323	return mo ? obj_to_property(mo) : NULL;
324}
325
326#endif