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 /**
  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  */
  39 struct 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  */
  71 struct 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  */
 206 struct 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         unsigned char data[];
 213 };
 214
 215 struct 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  */
 231 static 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
 240 struct drm_property *drm_property_create(struct drm_device *dev, int flags,
 241                                          const char *name, int num_values);
 242 struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
 243                                               const char *name,
 244                                               const struct drm_prop_enum_list *props,
 245                                               int num_values);
 246 struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
 247                                                  int flags, const char *name,
 248                                                  const struct drm_prop_enum_list *props,
 249                                                  int num_props,
 250                                                  uint64_t supported_bits);
 251 struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
 252                                                const char *name,
 253                                                uint64_t min, uint64_t max);
 254 struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
 255                                                       int flags, const char *name,
 256                                                       int64_t min, int64_t max);
 257 struct drm_property *drm_property_create_object(struct drm_device *dev,
 258                                                 int flags, const char *name, uint32_t type);
 259 struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags,
 260                                               const char *name);
 261 int drm_property_add_enum(struct drm_property *property, int index,
 262                           uint64_t value, const char *name);
 263 void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
 264
 265 struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
 266                                                    size_t length,
 267                                                    const void *data);
 268 struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
 269                                                    uint32_t id);
 270 int drm_property_replace_global_blob(struct drm_device *dev,
 271                                      struct drm_property_blob **replace,
 272                                      size_t length,
 273                                      const void *data,
 274                                      struct drm_mode_object *obj_holds_id,
 275                                      struct drm_property *prop_holds_id);
 276 struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
 277 void drm_property_blob_put(struct drm_property_blob *blob);
 278
 279 /**
 280  * drm_property_reference_blob - acquire a blob property reference
 281  * @blob: DRM blob property
 282  *
 283  * This is a compatibility alias for drm_property_blob_get() and should not be
 284  * used by new code.
 285  */
 286 static inline struct drm_property_blob *
 287 drm_property_reference_blob(struct drm_property_blob *blob)
 288 {
 289         return drm_property_blob_get(blob);
 290 }
 291
 292 /**
 293  * drm_property_unreference_blob - release a blob property reference
 294  * @blob: DRM blob property
 295  *
 296  * This is a compatibility alias for drm_property_blob_put() and should not be
 297  * used by new code.
 298  */
 299 static inline void
 300 drm_property_unreference_blob(struct drm_property_blob *blob)
 301 {
 302         drm_property_blob_put(blob);
 303 }
 304
 305 /**
 306  * drm_connector_find - find property object
 307  * @dev: DRM device
 308  * @id: property object id
 309  *
 310  * This function looks up the property object specified by id and returns it.
 311  */
 312 static inline struct drm_property *drm_property_find(struct drm_device *dev,
 313                                                      uint32_t id)
 314 {
 315         struct drm_mode_object *mo;
 316         mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PROPERTY);
 317         return mo ? obj_to_property(mo) : NULL;
 318 }
 319
 320 #endif