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  * @value: numeric property value for this enum entry
  35  * @head: list of enum values, linked to &drm_property.enum_list
  36  * @name: symbolic name for the enum
  37  *
  38  * For enumeration and bitmask properties this structure stores the symbolic
  39  * decoding for each value. This is used for example for the rotation property.
  40  */
  41 struct drm_property_enum {
  42         uint64_t value;
  43         struct list_head head;
  44         char name[DRM_PROP_NAME_LEN];
  45 };
  46
  47 /**
  48  * struct drm_property - modeset object property
  49  *
  50  * This structure represent a modeset object property. It combines both the name
  51  * of the property with the set of permissible values. This means that when a
  52  * driver wants to use a property with the same name on different objects, but
  53  * with different value ranges, then it must create property for each one. An
  54  * example would be rotation of &drm_plane, when e.g. the primary plane cannot
  55  * be rotated. But if both the name and the value range match, then the same
  56  * property structure can be instantiated multiple times for the same object.
  57  * Userspace must be able to cope with this and cannot assume that the same
  58  * symbolic property will have the same modeset object ID on all modeset
  59  * objects.
  60  *
  61  * Properties are created by one of the special functions, as explained in
  62  * detail in the @flags structure member.
  63  *
  64  * To actually expose a property it must be attached to each object using
  65  * drm_object_attach_property(). Currently properties can only be attached to
  66  * &drm_connector, &drm_crtc and &drm_plane.
  67  *
  68  * Properties are also used as the generic metadatatransport for the atomic
  69  * IOCTL. Everything that was set directly in structures in the legacy modeset
  70  * IOCTLs (like the plane source or destination windows, or e.g. the links to
  71  * the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.
  72  */
  73 struct drm_property {
  74         /**
  75          * @head: per-device list of properties, for cleanup.
  76          */
  77         struct list_head head;
  78
  79         /**
  80          * @base: base KMS object
  81          */
  82         struct drm_mode_object base;
  83
  84         /**
  85          * @flags:
  86          *
  87          * Property flags and type. A property needs to be one of the following
  88          * types:
  89          *
  90          * DRM_MODE_PROP_RANGE
  91          *     Range properties report their minimum and maximum admissible unsigned values.
  92          *     The KMS core verifies that values set by application fit in that
  93          *     range. The range is unsigned. Range properties are created using
  94          *     drm_property_create_range().
  95          *
  96          * DRM_MODE_PROP_SIGNED_RANGE
  97          *     Range properties report their minimum and maximum admissible unsigned values.
  98          *     The KMS core verifies that values set by application fit in that
  99          *     range. The range is signed. Range properties are created using
 100          *     drm_property_create_signed_range().
 101          *
 102          * DRM_MODE_PROP_ENUM
 103          *     Enumerated properties take a numerical value that ranges from 0 to
 104          *     the number of enumerated values defined by the property minus one,
 105          *     and associate a free-formed string name to each value. Applications
 106          *     can retrieve the list of defined value-name pairs and use the
 107          *     numerical value to get and set property instance values. Enum
 108          *     properties are created using drm_property_create_enum().
 109          *
 110          * DRM_MODE_PROP_BITMASK
 111          *     Bitmask properties are enumeration properties that additionally
 112          *     restrict all enumerated values to the 0..63 range. Bitmask property
 113          *     instance values combine one or more of the enumerated bits defined
 114          *     by the property. Bitmask properties are created using
 115          *     drm_property_create_bitmask().
 116          *
 117          * DRM_MODE_PROB_OBJECT
 118          *     Object properties are used to link modeset objects. This is used
 119          *     extensively in the atomic support to create the display pipeline,
 120          *     by linking &drm_framebuffer to &drm_plane, &drm_plane to
 121          *     &drm_crtc and &drm_connector to &drm_crtc. An object property can
 122          *     only link to a specific type of &drm_mode_object, this limit is
 123          *     enforced by the core. Object properties are created using
 124          *     drm_property_create_object().
 125          *
 126          *     Object properties work like blob properties, but in a more
 127          *     general fashion. They are limited to atomic drivers and must have
 128          *     the DRM_MODE_PROP_ATOMIC flag set.
 129          *
 130          * DRM_MODE_PROP_BLOB
 131          *     Blob properties store a binary blob without any format restriction.
 132          *     The binary blobs are created as KMS standalone objects, and blob
 133          *     property instance values store the ID of their associated blob
 134          *     object. Blob properties are created by calling
 135          *     drm_property_create() with DRM_MODE_PROP_BLOB as the type.
 136          *
 137          *     Actual blob objects to contain blob data are created using
 138          *     drm_property_create_blob(), or through the corresponding IOCTL.
 139          *
 140          *     Besides the built-in limit to only accept blob objects blob
 141          *     properties work exactly like object properties. The only reasons
 142          *     blob properties exist is backwards compatibility with existing
 143          *     userspace.
 144          *
 145          * In addition a property can have any combination of the below flags:
 146          *
 147          * DRM_MODE_PROP_ATOMIC
 148          *     Set for properties which encode atomic modeset state. Such
 149          *     properties are not exposed to legacy userspace.
 150          *
 151          * DRM_MODE_PROP_IMMUTABLE
 152          *     Set for properties whose values cannot be changed by
 153          *     userspace. The kernel is allowed to update the value of these
 154          *     properties. This is generally used to expose probe state to
 155          *     userspace, e.g. the EDID, or the connector path property on DP
 156          *     MST sinks. Kernel can update the value of an immutable property
 157          *     by calling drm_object_property_set_value().
 158          */
 159         uint32_t flags;
 160
 161         /**
 162          * @name: symbolic name of the properties
 163          */
 164         char name[DRM_PROP_NAME_LEN];
 165
 166         /**
 167          * @num_values: size of the @values array.
 168          */
 169         uint32_t num_values;
 170
 171         /**
 172          * @values:
 173          *
 174          * Array with limits and values for the property. The
 175          * interpretation of these limits is dependent upon the type per @flags.
 176          */
 177         uint64_t *values;
 178
 179         /**
 180          * @dev: DRM device
 181          */
 182         struct drm_device *dev;
 183
 184         /**
 185          * @enum_list:
 186          *
 187          * List of &drm_prop_enum_list structures with the symbolic names for
 188          * enum and bitmask values.
 189          */
 190         struct list_head enum_list;
 191 };
 192
 193 /**
 194  * struct drm_property_blob - Blob data for &drm_property
 195  * @base: base KMS object
 196  * @dev: DRM device
 197  * @head_global: entry on the global blob list in
 198  *      &drm_mode_config.property_blob_list.
 199  * @head_file: entry on the per-file blob list in &drm_file.blobs list.
 200  * @length: size of the blob in bytes, invariant over the lifetime of the object
 201  * @data: actual data, embedded at the end of this structure
 202  *
 203  * Blobs are used to store bigger values than what fits directly into the 64
 204  * bits available for a &drm_property.
 205  *
 206  * Blobs are reference counted using drm_property_blob_get() and
 207  * drm_property_blob_put(). They are created using drm_property_create_blob().
 208  */
 209 struct drm_property_blob {
 210         struct drm_mode_object base;
 211         struct drm_device *dev;
 212         struct list_head head_global;
 213         struct list_head head_file;
 214         size_t length;
 215         void *data;
 216 };
 217
 218 struct drm_prop_enum_list {
 219         int type;
 220         const char *name;
 221 };
 222
 223 #define obj_to_property(x) container_of(x, struct drm_property, base)
 224 #define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
 225
 226 /**
 227  * drm_property_type_is - check the type of a property
 228  * @property: property to check
 229  * @type: property type to compare with
 230  *
 231  * This is a helper function becauase the uapi encoding of property types is
 232  * a bit special for historical reasons.
 233  */
 234 static inline bool drm_property_type_is(struct drm_property *property,
 235                                         uint32_t type)
 236 {
 237         /* instanceof for props.. handles extended type vs original types: */
 238         if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
 239                 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
 240         return property->flags & type;
 241 }
 242
 243 struct drm_property *drm_property_create(struct drm_device *dev,
 244                                          u32 flags, const char *name,
 245                                          int num_values);
 246 struct drm_property *drm_property_create_enum(struct drm_device *dev,
 247                                               u32 flags, const char *name,
 248                                               const struct drm_prop_enum_list *props,
 249                                               int num_values);
 250 struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
 251                                                  u32 flags, const char *name,
 252                                                  const struct drm_prop_enum_list *props,
 253                                                  int num_props,
 254                                                  uint64_t supported_bits);
 255 struct drm_property *drm_property_create_range(struct drm_device *dev,
 256                                                u32 flags, const char *name,
 257                                                uint64_t min, uint64_t max);
 258 struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
 259                                                       u32 flags, const char *name,
 260                                                       int64_t min, int64_t max);
 261 struct drm_property *drm_property_create_object(struct drm_device *dev,
 262                                                 u32 flags, const char *name,
 263                                                 uint32_t type);
 264 struct drm_property *drm_property_create_bool(struct drm_device *dev,
 265                                               u32 flags, const char *name);
 266 int drm_property_add_enum(struct drm_property *property,
 267                           uint64_t value, const char *name);
 268 void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
 269
 270 struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
 271                                                    size_t length,
 272                                                    const void *data);
 273 struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
 274                                                    uint32_t id);
 275 int drm_property_replace_global_blob(struct drm_device *dev,
 276                                      struct drm_property_blob **replace,
 277                                      size_t length,
 278                                      const void *data,
 279                                      struct drm_mode_object *obj_holds_id,
 280                                      struct drm_property *prop_holds_id);
 281 bool drm_property_replace_blob(struct drm_property_blob **blob,
 282                                struct drm_property_blob *new_blob);
 283 struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
 284 void drm_property_blob_put(struct drm_property_blob *blob);
 285
 286 /**
 287  * drm_property_find - find property object
 288  * @dev: DRM device
 289  * @file_priv: drm file to check for lease against.
 290  * @id: property object id
 291  *
 292  * This function looks up the property object specified by id and returns it.
 293  */
 294 static inline struct drm_property *drm_property_find(struct drm_device *dev,
 295                                                      struct drm_file *file_priv,
 296                                                      uint32_t id)
 297 {
 298         struct drm_mode_object *mo;
 299         mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
 300         return mo ? obj_to_property(mo) : NULL;
 301 }
 302
 303 #endif