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 */ drm_property_type_is(struct drm_property * property,uint32_t type)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 bool drm_property_replace_blob(struct drm_property_blob **blob, 277 struct drm_property_blob *new_blob); 278 struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob); 279 void drm_property_blob_put(struct drm_property_blob *blob); 280 281 /** 282 * drm_property_reference_blob - acquire a blob property reference 283 * @blob: DRM blob property 284 * 285 * This is a compatibility alias for drm_property_blob_get() and should not be 286 * used by new code. 287 */ 288 static inline struct drm_property_blob * drm_property_reference_blob(struct drm_property_blob * blob)289 drm_property_reference_blob(struct drm_property_blob *blob) 290 { 291 return drm_property_blob_get(blob); 292 } 293 294 /** 295 * drm_property_unreference_blob - release a blob property reference 296 * @blob: DRM blob property 297 * 298 * This is a compatibility alias for drm_property_blob_put() and should not be 299 * used by new code. 300 */ 301 static inline void drm_property_unreference_blob(struct drm_property_blob * blob)302 drm_property_unreference_blob(struct drm_property_blob *blob) 303 { 304 drm_property_blob_put(blob); 305 } 306 307 /** 308 * drm_connector_find - find property object 309 * @dev: DRM device 310 * @id: property object id 311 * 312 * This function looks up the property object specified by id and returns it. 313 */ drm_property_find(struct drm_device * dev,uint32_t id)314 static inline struct drm_property *drm_property_find(struct drm_device *dev, 315 uint32_t id) 316 { 317 struct drm_mode_object *mo; 318 mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PROPERTY); 319 return mo ? obj_to_property(mo) : NULL; 320 } 321 322 #endif 323