317 lines · c
1/*2 * Copyright (c) 2016 Intel Corporation3 *4 * Permission to use, copy, modify, distribute, and sell this software and its5 * documentation for any purpose is hereby granted without fee, provided that6 * the above copyright notice appear in all copies and that both that copyright7 * notice and this permission notice appear in supporting documentation, and8 * that the name of the copyright holders not be used in advertising or9 * publicity pertaining to distribution of the software without specific,10 * written prior permission. The copyright holders make no representations11 * about the suitability of this software for any purpose. It is provided "as12 * 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 NO16 * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR17 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,18 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER19 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE20 * 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 enumerations34 * @head: list of enum values, linked to &drm_property.enum_list35 * @name: symbolic name for the enum36 *37 * For enumeration and bitmask properties this structure stores the symbolic38 * decoding for each value. This is used for example for the rotation property.39 */40struct drm_property_enum {41 /**42 * @value: numeric property value for this enum entry43 *44 * If the property has the type &DRM_MODE_PROP_BITMASK, @value stores a45 * bitshift, not a bitmask. In other words, the enum entry is enabled46 * if the bit number @value is set in the property's value. This enum47 * entry has the bitmask ``1 << value``.48 */49 uint64_t value;50 struct list_head head;51 char name[DRM_PROP_NAME_LEN];52};53 54/**55 * struct drm_property - modeset object property56 *57 * This structure represent a modeset object property. It combines both the name58 * of the property with the set of permissible values. This means that when a59 * driver wants to use a property with the same name on different objects, but60 * with different value ranges, then it must create property for each one. An61 * example would be rotation of &drm_plane, when e.g. the primary plane cannot62 * be rotated. But if both the name and the value range match, then the same63 * property structure can be instantiated multiple times for the same object.64 * Userspace must be able to cope with this and cannot assume that the same65 * symbolic property will have the same modeset object ID on all modeset66 * objects.67 *68 * Properties are created by one of the special functions, as explained in69 * detail in the @flags structure member.70 *71 * To actually expose a property it must be attached to each object using72 * drm_object_attach_property(). Currently properties can only be attached to73 * &drm_connector, &drm_crtc and &drm_plane.74 *75 * Properties are also used as the generic metadatatransport for the atomic76 * IOCTL. Everything that was set directly in structures in the legacy modeset77 * IOCTLs (like the plane source or destination windows, or e.g. the links to78 * the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.79 */80struct drm_property {81 /**82 * @head: per-device list of properties, for cleanup.83 */84 struct list_head head;85 86 /**87 * @base: base KMS object88 */89 struct drm_mode_object base;90 91 /**92 * @flags:93 *94 * Property flags and type. A property needs to be one of the following95 * types:96 *97 * DRM_MODE_PROP_RANGE98 * Range properties report their minimum and maximum admissible unsigned values.99 * The KMS core verifies that values set by application fit in that100 * range. The range is unsigned. Range properties are created using101 * drm_property_create_range().102 *103 * DRM_MODE_PROP_SIGNED_RANGE104 * Range properties report their minimum and maximum admissible unsigned values.105 * The KMS core verifies that values set by application fit in that106 * range. The range is signed. Range properties are created using107 * drm_property_create_signed_range().108 *109 * DRM_MODE_PROP_ENUM110 * Enumerated properties take a numerical value that ranges from 0 to111 * the number of enumerated values defined by the property minus one,112 * and associate a free-formed string name to each value. Applications113 * can retrieve the list of defined value-name pairs and use the114 * numerical value to get and set property instance values. Enum115 * properties are created using drm_property_create_enum().116 *117 * DRM_MODE_PROP_BITMASK118 * Bitmask properties are enumeration properties that additionally119 * restrict all enumerated values to the 0..63 range. Bitmask property120 * instance values combine one or more of the enumerated bits defined121 * by the property. Bitmask properties are created using122 * drm_property_create_bitmask().123 *124 * DRM_MODE_PROP_OBJECT125 * Object properties are used to link modeset objects. This is used126 * extensively in the atomic support to create the display pipeline,127 * by linking &drm_framebuffer to &drm_plane, &drm_plane to128 * &drm_crtc and &drm_connector to &drm_crtc. An object property can129 * only link to a specific type of &drm_mode_object, this limit is130 * enforced by the core. Object properties are created using131 * drm_property_create_object().132 *133 * Object properties work like blob properties, but in a more134 * general fashion. They are limited to atomic drivers and must have135 * the DRM_MODE_PROP_ATOMIC flag set.136 *137 * DRM_MODE_PROP_BLOB138 * Blob properties store a binary blob without any format restriction.139 * The binary blobs are created as KMS standalone objects, and blob140 * property instance values store the ID of their associated blob141 * object. Blob properties are created by calling142 * drm_property_create() with DRM_MODE_PROP_BLOB as the type.143 *144 * Actual blob objects to contain blob data are created using145 * drm_property_create_blob(), or through the corresponding IOCTL.146 *147 * Besides the built-in limit to only accept blob objects blob148 * properties work exactly like object properties. The only reasons149 * blob properties exist is backwards compatibility with existing150 * userspace.151 *152 * In addition a property can have any combination of the below flags:153 *154 * DRM_MODE_PROP_ATOMIC155 * Set for properties which encode atomic modeset state. Such156 * properties are not exposed to legacy userspace.157 *158 * DRM_MODE_PROP_IMMUTABLE159 * Set for properties whose values cannot be changed by160 * userspace. The kernel is allowed to update the value of these161 * properties. This is generally used to expose probe state to162 * userspace, e.g. the EDID, or the connector path property on DP163 * MST sinks. Kernel can update the value of an immutable property164 * by calling drm_object_property_set_value().165 */166 uint32_t flags;167 168 /**169 * @name: symbolic name of the properties170 */171 char name[DRM_PROP_NAME_LEN];172 173 /**174 * @num_values: size of the @values array.175 */176 uint32_t num_values;177 178 /**179 * @values:180 *181 * Array with limits and values for the property. The182 * interpretation of these limits is dependent upon the type per @flags.183 */184 uint64_t *values;185 186 /**187 * @dev: DRM device188 */189 struct drm_device *dev;190 191 /**192 * @enum_list:193 *194 * List of &drm_prop_enum_list structures with the symbolic names for195 * enum and bitmask values.196 */197 struct list_head enum_list;198};199 200/**201 * struct drm_property_blob - Blob data for &drm_property202 * @base: base KMS object203 * @dev: DRM device204 * @head_global: entry on the global blob list in205 * &drm_mode_config.property_blob_list.206 * @head_file: entry on the per-file blob list in &drm_file.blobs list.207 * @length: size of the blob in bytes, invariant over the lifetime of the object208 * @data: actual data, embedded at the end of this structure209 *210 * Blobs are used to store bigger values than what fits directly into the 64211 * bits available for a &drm_property.212 *213 * Blobs are reference counted using drm_property_blob_get() and214 * drm_property_blob_put(). They are created using drm_property_create_blob().215 */216struct drm_property_blob {217 struct drm_mode_object base;218 struct drm_device *dev;219 struct list_head head_global;220 struct list_head head_file;221 size_t length;222 void *data;223};224 225struct drm_prop_enum_list {226 int type;227 const char *name;228};229 230#define obj_to_property(x) container_of(x, struct drm_property, base)231#define obj_to_blob(x) container_of(x, struct drm_property_blob, base)232 233/**234 * drm_property_type_is - check the type of a property235 * @property: property to check236 * @type: property type to compare with237 *238 * This is a helper function becauase the uapi encoding of property types is239 * a bit special for historical reasons.240 */241static inline bool drm_property_type_is(struct drm_property *property,242 uint32_t type)243{244 /* instanceof for props.. handles extended type vs original types: */245 if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)246 return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;247 return property->flags & type;248}249 250struct drm_property *drm_property_create(struct drm_device *dev,251 u32 flags, const char *name,252 int num_values);253struct drm_property *drm_property_create_enum(struct drm_device *dev,254 u32 flags, const char *name,255 const struct drm_prop_enum_list *props,256 int num_values);257struct drm_property *drm_property_create_bitmask(struct drm_device *dev,258 u32 flags, const char *name,259 const struct drm_prop_enum_list *props,260 int num_props,261 uint64_t supported_bits);262struct drm_property *drm_property_create_range(struct drm_device *dev,263 u32 flags, const char *name,264 uint64_t min, uint64_t max);265struct drm_property *drm_property_create_signed_range(struct drm_device *dev,266 u32 flags, const char *name,267 int64_t min, int64_t max);268struct drm_property *drm_property_create_object(struct drm_device *dev,269 u32 flags, const char *name,270 uint32_t type);271struct drm_property *drm_property_create_bool(struct drm_device *dev,272 u32 flags, const char *name);273int drm_property_add_enum(struct drm_property *property,274 uint64_t value, const char *name);275void drm_property_destroy(struct drm_device *dev, struct drm_property *property);276 277struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,278 size_t length,279 const void *data);280struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,281 uint32_t id);282int drm_property_replace_blob_from_id(struct drm_device *dev,283 struct drm_property_blob **blob,284 uint64_t blob_id,285 ssize_t expected_size,286 ssize_t expected_elem_size,287 bool *replaced);288int drm_property_replace_global_blob(struct drm_device *dev,289 struct drm_property_blob **replace,290 size_t length,291 const void *data,292 struct drm_mode_object *obj_holds_id,293 struct drm_property *prop_holds_id);294bool drm_property_replace_blob(struct drm_property_blob **blob,295 struct drm_property_blob *new_blob);296struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);297void drm_property_blob_put(struct drm_property_blob *blob);298 299/**300 * drm_property_find - find property object301 * @dev: DRM device302 * @file_priv: drm file to check for lease against.303 * @id: property object id304 *305 * This function looks up the property object specified by id and returns it.306 */307static inline struct drm_property *drm_property_find(struct drm_device *dev,308 struct drm_file *file_priv,309 uint32_t id)310{311 struct drm_mode_object *mo;312 mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);313 return mo ? obj_to_property(mo) : NULL;314}315 316#endif317