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.
 157          */
 158         uint32_t flags;
 159
 160         /**
 161          * @name: symbolic name of the properties
 162          */
 163         char name[DRM_PROP_NAME_LEN];
 164
 165         /**
 166          * @num_values: size of the @values array.
 167          */
 168         uint32_t num_values;
 169
 170         /**
 171          * @values:
 172          *
 173          * Array with limits and values for the property. The
 174          * interpretation of these limits is dependent upon the type per @flags.
 175          */
 176         uint64_t *values;
 177
 178         /**
 179          * @dev: DRM device
 180          */
 181         struct drm_device *dev;
 182
 183         /**
 184          * @enum_list:
 185          *
 186          * List of &drm_prop_enum_list structures with the symbolic names for
 187          * enum and bitmask values.
 188          */
 189         struct list_head enum_list;
 190 };
 191
 192 /**
 193  * struct drm_property_blob - Blob data for &drm_property
 194  * @base: base KMS object
 195  * @dev: DRM device
 196  * @head_global: entry on the global blob list in
 197  *      &drm_mode_config.property_blob_list.
 198  * @head_file: entry on the per-file blob list in &drm_file.blobs list.
 199  * @length: size of the blob in bytes, invariant over the lifetime of the object
 200  * @data: actual data, embedded at the end of this structure
 201  *
 202  * Blobs are used to store bigger values than what fits directly into the 64
 203  * bits available for a &drm_property.
 204  *
 205  * Blobs are reference counted using drm_property_blob_get() and
 206  * drm_property_blob_put(). They are created using drm_property_create_blob().
 207  */
 208 struct drm_property_blob {
 209         struct drm_mode_object base;
 210         struct drm_device *dev;
 211         struct list_head head_global;
 212         struct list_head head_file;
 213         size_t length;
 214         void *data;
 215 };
 216
 217 struct drm_prop_enum_list {
 218         int type;
 219         const char *name;
 220 };
 221
 222 #define obj_to_property(x) container_of(x, struct drm_property, base)
 223 #define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
 224
 225 /**
 226  * drm_property_type_is - check the type of a property
 227  * @property: property to check
 228  * @type: property type to compare with
 229  *
 230  * This is a helper function becauase the uapi encoding of property types is
 231  * a bit special for historical reasons.
 232  */
 233 static inline bool drm_property_type_is(struct drm_property *property,
 234                                         uint32_t type)
 235 {
 236         /* instanceof for props.. handles extended type vs original types: */
 237         if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
 238                 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
 239         return property->flags & type;
 240 }
 241
 242 struct drm_property *drm_property_create(struct drm_device *dev,
 243                                          u32 flags, const char *name,
 244                                          int num_values);
 245 struct drm_property *drm_property_create_enum(struct drm_device *dev,
 246                                               u32 flags, const char *name,
 247                                               const struct drm_prop_enum_list *props,
 248                                               int num_values);
 249 struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
 250                                                  u32 flags, const char *name,
 251                                                  const struct drm_prop_enum_list *props,
 252                                                  int num_props,
 253                                                  uint64_t supported_bits);
 254 struct drm_property *drm_property_create_range(struct drm_device *dev,
 255                                                u32 flags, const char *name,
 256                                                uint64_t min, uint64_t max);
 257 struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
 258                                                       u32 flags, const char *name,
 259                                                       int64_t min, int64_t max);
 260 struct drm_property *drm_property_create_object(struct drm_device *dev,
 261                                                 u32 flags, const char *name,
 262                                                 uint32_t type);
 263 struct drm_property *drm_property_create_bool(struct drm_device *dev,
 264                                               u32 flags, const char *name);
 265 int drm_property_add_enum(struct drm_property *property,
 266                           uint64_t value, const char *name);
 267 void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
 268
 269 struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
 270                                                    size_t length,
 271                                                    const void *data);
 272 struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
 273                                                    uint32_t id);
 274 int drm_property_replace_global_blob(struct drm_device *dev,
 275                                      struct drm_property_blob **replace,
 276                                      size_t length,
 277                                      const void *data,
 278                                      struct drm_mode_object *obj_holds_id,
 279                                      struct drm_property *prop_holds_id);
 280 bool drm_property_replace_blob(struct drm_property_blob **blob,
 281                                struct drm_property_blob *new_blob);
 282 struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
 283 void drm_property_blob_put(struct drm_property_blob *blob);
 284
 285 /**
 286  * drm_property_find - find property object
 287  * @dev: DRM device
 288  * @file_priv: drm file to check for lease against.
 289  * @id: property object id
 290  *
 291  * This function looks up the property object specified by id and returns it.
 292  */
 293 static inline struct drm_property *drm_property_find(struct drm_device *dev,
 294                                                      struct drm_file *file_priv,
 295                                                      uint32_t id)
 296 {
 297         struct drm_mode_object *mo;
 298         mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
 299         return mo ? obj_to_property(mo) : NULL;
 300 }
 301
 302 #endif