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