159e71ee7SDaniel Vetter /* 259e71ee7SDaniel Vetter * Copyright (c) 2016 Intel Corporation 359e71ee7SDaniel Vetter * 459e71ee7SDaniel Vetter * Permission to use, copy, modify, distribute, and sell this software and its 559e71ee7SDaniel Vetter * documentation for any purpose is hereby granted without fee, provided that 659e71ee7SDaniel Vetter * the above copyright notice appear in all copies and that both that copyright 759e71ee7SDaniel Vetter * notice and this permission notice appear in supporting documentation, and 859e71ee7SDaniel Vetter * that the name of the copyright holders not be used in advertising or 959e71ee7SDaniel Vetter * publicity pertaining to distribution of the software without specific, 1059e71ee7SDaniel Vetter * written prior permission. The copyright holders make no representations 1159e71ee7SDaniel Vetter * about the suitability of this software for any purpose. It is provided "as 1259e71ee7SDaniel Vetter * is" without express or implied warranty. 1359e71ee7SDaniel Vetter * 1459e71ee7SDaniel Vetter * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 1559e71ee7SDaniel Vetter * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 1659e71ee7SDaniel Vetter * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR 1759e71ee7SDaniel Vetter * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 1859e71ee7SDaniel Vetter * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 1959e71ee7SDaniel Vetter * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 2059e71ee7SDaniel Vetter * OF THIS SOFTWARE. 2159e71ee7SDaniel Vetter */ 2259e71ee7SDaniel Vetter 2359e71ee7SDaniel Vetter #ifndef __DRM_PROPERTY_H__ 2459e71ee7SDaniel Vetter #define __DRM_PROPERTY_H__ 2559e71ee7SDaniel Vetter 2659e71ee7SDaniel Vetter #include <linux/list.h> 2759e71ee7SDaniel Vetter #include <linux/ctype.h> 2859e71ee7SDaniel Vetter #include <drm/drm_mode_object.h> 2959e71ee7SDaniel Vetter 30c8458c7eSDaniel Vetter /** 31c8458c7eSDaniel Vetter * struct drm_property_enum - symbolic values for enumerations 32c8458c7eSDaniel Vetter * @value: numeric property value for this enum entry 33d574528aSDaniel Vetter * @head: list of enum values, linked to &drm_property.enum_list 34c8458c7eSDaniel Vetter * @name: symbolic name for the enum 35c8458c7eSDaniel Vetter * 36c8458c7eSDaniel Vetter * For enumeration and bitmask properties this structure stores the symbolic 37c8458c7eSDaniel Vetter * decoding for each value. This is used for example for the rotation property. 38c8458c7eSDaniel Vetter */ 39c8458c7eSDaniel Vetter struct drm_property_enum { 40c8458c7eSDaniel Vetter uint64_t value; 41c8458c7eSDaniel Vetter struct list_head head; 42c8458c7eSDaniel Vetter char name[DRM_PROP_NAME_LEN]; 43c8458c7eSDaniel Vetter }; 44c8458c7eSDaniel Vetter 45c8458c7eSDaniel Vetter /** 46c8458c7eSDaniel Vetter * struct drm_property - modeset object property 47c8458c7eSDaniel Vetter * 48c8458c7eSDaniel Vetter * This structure represent a modeset object property. It combines both the name 49c8458c7eSDaniel Vetter * of the property with the set of permissible values. This means that when a 50c8458c7eSDaniel Vetter * driver wants to use a property with the same name on different objects, but 51c8458c7eSDaniel Vetter * with different value ranges, then it must create property for each one. An 52c8458c7eSDaniel Vetter * example would be rotation of &drm_plane, when e.g. the primary plane cannot 53c8458c7eSDaniel Vetter * be rotated. But if both the name and the value range match, then the same 54c8458c7eSDaniel Vetter * property structure can be instantiated multiple times for the same object. 55c8458c7eSDaniel Vetter * Userspace must be able to cope with this and cannot assume that the same 56c8458c7eSDaniel Vetter * symbolic property will have the same modeset object ID on all modeset 57c8458c7eSDaniel Vetter * objects. 58c8458c7eSDaniel Vetter * 59c8458c7eSDaniel Vetter * Properties are created by one of the special functions, as explained in 60c8458c7eSDaniel Vetter * detail in the @flags structure member. 61c8458c7eSDaniel Vetter * 62c8458c7eSDaniel Vetter * To actually expose a property it must be attached to each object using 63c8458c7eSDaniel Vetter * drm_object_attach_property(). Currently properties can only be attached to 64c8458c7eSDaniel Vetter * &drm_connector, &drm_crtc and &drm_plane. 65c8458c7eSDaniel Vetter * 66c8458c7eSDaniel Vetter * Properties are also used as the generic metadatatransport for the atomic 67c8458c7eSDaniel Vetter * IOCTL. Everything that was set directly in structures in the legacy modeset 68c8458c7eSDaniel Vetter * IOCTLs (like the plane source or destination windows, or e.g. the links to 69c8458c7eSDaniel Vetter * the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set. 70c8458c7eSDaniel Vetter */ 71c8458c7eSDaniel Vetter struct drm_property { 72c8458c7eSDaniel Vetter /** 73c8458c7eSDaniel Vetter * @head: per-device list of properties, for cleanup. 74c8458c7eSDaniel Vetter */ 75c8458c7eSDaniel Vetter struct list_head head; 76c8458c7eSDaniel Vetter 77c8458c7eSDaniel Vetter /** 78c8458c7eSDaniel Vetter * @base: base KMS object 79c8458c7eSDaniel Vetter */ 80c8458c7eSDaniel Vetter struct drm_mode_object base; 81c8458c7eSDaniel Vetter 82c8458c7eSDaniel Vetter /** 83c8458c7eSDaniel Vetter * @flags: 84c8458c7eSDaniel Vetter * 85c8458c7eSDaniel Vetter * Property flags and type. A property needs to be one of the following 86c8458c7eSDaniel Vetter * types: 87c8458c7eSDaniel Vetter * 88c8458c7eSDaniel Vetter * DRM_MODE_PROP_RANGE 89c8458c7eSDaniel Vetter * Range properties report their minimum and maximum admissible unsigned values. 90c8458c7eSDaniel Vetter * The KMS core verifies that values set by application fit in that 91c8458c7eSDaniel Vetter * range. The range is unsigned. Range properties are created using 92c8458c7eSDaniel Vetter * drm_property_create_range(). 93c8458c7eSDaniel Vetter * 94c8458c7eSDaniel Vetter * DRM_MODE_PROP_SIGNED_RANGE 95c8458c7eSDaniel Vetter * Range properties report their minimum and maximum admissible unsigned values. 96c8458c7eSDaniel Vetter * The KMS core verifies that values set by application fit in that 97c8458c7eSDaniel Vetter * range. The range is signed. Range properties are created using 98c8458c7eSDaniel Vetter * drm_property_create_signed_range(). 99c8458c7eSDaniel Vetter * 100c8458c7eSDaniel Vetter * DRM_MODE_PROP_ENUM 101c8458c7eSDaniel Vetter * Enumerated properties take a numerical value that ranges from 0 to 102c8458c7eSDaniel Vetter * the number of enumerated values defined by the property minus one, 103c8458c7eSDaniel Vetter * and associate a free-formed string name to each value. Applications 104c8458c7eSDaniel Vetter * can retrieve the list of defined value-name pairs and use the 105c8458c7eSDaniel Vetter * numerical value to get and set property instance values. Enum 106c8458c7eSDaniel Vetter * properties are created using drm_property_create_enum(). 107c8458c7eSDaniel Vetter * 108c8458c7eSDaniel Vetter * DRM_MODE_PROP_BITMASK 109c8458c7eSDaniel Vetter * Bitmask properties are enumeration properties that additionally 110c8458c7eSDaniel Vetter * restrict all enumerated values to the 0..63 range. Bitmask property 111c8458c7eSDaniel Vetter * instance values combine one or more of the enumerated bits defined 112c8458c7eSDaniel Vetter * by the property. Bitmask properties are created using 113c8458c7eSDaniel Vetter * drm_property_create_bitmask(). 114c8458c7eSDaniel Vetter * 115c8458c7eSDaniel Vetter * DRM_MODE_PROB_OBJECT 116c8458c7eSDaniel Vetter * Object properties are used to link modeset objects. This is used 117c8458c7eSDaniel Vetter * extensively in the atomic support to create the display pipeline, 118c8458c7eSDaniel Vetter * by linking &drm_framebuffer to &drm_plane, &drm_plane to 119c8458c7eSDaniel Vetter * &drm_crtc and &drm_connector to &drm_crtc. An object property can 120c8458c7eSDaniel Vetter * only link to a specific type of &drm_mode_object, this limit is 121c8458c7eSDaniel Vetter * enforced by the core. Object properties are created using 122c8458c7eSDaniel Vetter * drm_property_create_object(). 123c8458c7eSDaniel Vetter * 124c8458c7eSDaniel Vetter * Object properties work like blob properties, but in a more 125c8458c7eSDaniel Vetter * general fashion. They are limited to atomic drivers and must have 126c8458c7eSDaniel Vetter * the DRM_MODE_PROP_ATOMIC flag set. 127c8458c7eSDaniel Vetter * 128c8458c7eSDaniel Vetter * DRM_MODE_PROP_BLOB 129c8458c7eSDaniel Vetter * Blob properties store a binary blob without any format restriction. 130c8458c7eSDaniel Vetter * The binary blobs are created as KMS standalone objects, and blob 131c8458c7eSDaniel Vetter * property instance values store the ID of their associated blob 132c8458c7eSDaniel Vetter * object. Blob properties are created by calling 133c8458c7eSDaniel Vetter * drm_property_create() with DRM_MODE_PROP_BLOB as the type. 134c8458c7eSDaniel Vetter * 135c8458c7eSDaniel Vetter * Actual blob objects to contain blob data are created using 136c8458c7eSDaniel Vetter * drm_property_create_blob(), or through the corresponding IOCTL. 137c8458c7eSDaniel Vetter * 138c8458c7eSDaniel Vetter * Besides the built-in limit to only accept blob objects blob 139c8458c7eSDaniel Vetter * properties work exactly like object properties. The only reasons 140c8458c7eSDaniel Vetter * blob properties exist is backwards compatibility with existing 141c8458c7eSDaniel Vetter * userspace. 142c8458c7eSDaniel Vetter * 143c8458c7eSDaniel Vetter * In addition a property can have any combination of the below flags: 144c8458c7eSDaniel Vetter * 145c8458c7eSDaniel Vetter * DRM_MODE_PROP_ATOMIC 146c8458c7eSDaniel Vetter * Set for properties which encode atomic modeset state. Such 147c8458c7eSDaniel Vetter * properties are not exposed to legacy userspace. 148c8458c7eSDaniel Vetter * 149c8458c7eSDaniel Vetter * DRM_MODE_PROP_IMMUTABLE 150c8458c7eSDaniel Vetter * Set for properties where userspace cannot be changed by 151c8458c7eSDaniel Vetter * userspace. The kernel is allowed to update the value of these 152c8458c7eSDaniel Vetter * properties. This is generally used to expose probe state to 153c8458c7eSDaniel Vetter * usersapce, e.g. the EDID, or the connector path property on DP 154c8458c7eSDaniel Vetter * MST sinks. 155c8458c7eSDaniel Vetter */ 156c8458c7eSDaniel Vetter uint32_t flags; 157c8458c7eSDaniel Vetter 158c8458c7eSDaniel Vetter /** 159c8458c7eSDaniel Vetter * @name: symbolic name of the properties 160c8458c7eSDaniel Vetter */ 161c8458c7eSDaniel Vetter char name[DRM_PROP_NAME_LEN]; 162c8458c7eSDaniel Vetter 163c8458c7eSDaniel Vetter /** 164c8458c7eSDaniel Vetter * @num_values: size of the @values array. 165c8458c7eSDaniel Vetter */ 166c8458c7eSDaniel Vetter uint32_t num_values; 167c8458c7eSDaniel Vetter 168c8458c7eSDaniel Vetter /** 169c8458c7eSDaniel Vetter * @values: 170c8458c7eSDaniel Vetter * 171c8458c7eSDaniel Vetter * Array with limits and values for the property. The 172c8458c7eSDaniel Vetter * interpretation of these limits is dependent upon the type per @flags. 173c8458c7eSDaniel Vetter */ 174c8458c7eSDaniel Vetter uint64_t *values; 175c8458c7eSDaniel Vetter 176c8458c7eSDaniel Vetter /** 177c8458c7eSDaniel Vetter * @dev: DRM device 178c8458c7eSDaniel Vetter */ 179c8458c7eSDaniel Vetter struct drm_device *dev; 180c8458c7eSDaniel Vetter 181c8458c7eSDaniel Vetter /** 182c8458c7eSDaniel Vetter * @enum_list: 183c8458c7eSDaniel Vetter * 184c8458c7eSDaniel Vetter * List of &drm_prop_enum_list structures with the symbolic names for 185c8458c7eSDaniel Vetter * enum and bitmask values. 186c8458c7eSDaniel Vetter */ 187c8458c7eSDaniel Vetter struct list_head enum_list; 188c8458c7eSDaniel Vetter }; 189c8458c7eSDaniel Vetter 190c8458c7eSDaniel Vetter /** 191c8458c7eSDaniel Vetter * struct drm_property_blob - Blob data for &drm_property 192c8458c7eSDaniel Vetter * @base: base KMS object 193c8458c7eSDaniel Vetter * @dev: DRM device 194d574528aSDaniel Vetter * @head_global: entry on the global blob list in 195d574528aSDaniel Vetter * &drm_mode_config.property_blob_list. 196d574528aSDaniel Vetter * @head_file: entry on the per-file blob list in &drm_file.blobs list. 197c8458c7eSDaniel Vetter * @length: size of the blob in bytes, invariant over the lifetime of the object 198c8458c7eSDaniel Vetter * @data: actual data, embedded at the end of this structure 199c8458c7eSDaniel Vetter * 200c8458c7eSDaniel Vetter * Blobs are used to store bigger values than what fits directly into the 64 201c8458c7eSDaniel Vetter * bits available for a &drm_property. 202c8458c7eSDaniel Vetter * 2036472e509SThierry Reding * Blobs are reference counted using drm_property_blob_get() and 2046472e509SThierry Reding * drm_property_blob_put(). They are created using drm_property_create_blob(). 205c8458c7eSDaniel Vetter */ 20659e71ee7SDaniel Vetter struct drm_property_blob { 20759e71ee7SDaniel Vetter struct drm_mode_object base; 20859e71ee7SDaniel Vetter struct drm_device *dev; 20959e71ee7SDaniel Vetter struct list_head head_global; 21059e71ee7SDaniel Vetter struct list_head head_file; 21159e71ee7SDaniel Vetter size_t length; 21259e71ee7SDaniel Vetter unsigned char data[]; 21359e71ee7SDaniel Vetter }; 21459e71ee7SDaniel Vetter 21559e71ee7SDaniel Vetter struct drm_prop_enum_list { 21659e71ee7SDaniel Vetter int type; 217dc629141SJyri Sarha const char *name; 21859e71ee7SDaniel Vetter }; 21959e71ee7SDaniel Vetter 22059e71ee7SDaniel Vetter #define obj_to_property(x) container_of(x, struct drm_property, base) 221afb21ea6SDaniel Vetter #define obj_to_blob(x) container_of(x, struct drm_property_blob, base) 22259e71ee7SDaniel Vetter 223c8458c7eSDaniel Vetter /** 224c8458c7eSDaniel Vetter * drm_property_type_is - check the type of a property 225c8458c7eSDaniel Vetter * @property: property to check 226c8458c7eSDaniel Vetter * @type: property type to compare with 227c8458c7eSDaniel Vetter * 228c8458c7eSDaniel Vetter * This is a helper function becauase the uapi encoding of property types is 229c8458c7eSDaniel Vetter * a bit special for historical reasons. 230c8458c7eSDaniel Vetter */ 23159e71ee7SDaniel Vetter static inline bool drm_property_type_is(struct drm_property *property, 23259e71ee7SDaniel Vetter uint32_t type) 23359e71ee7SDaniel Vetter { 23459e71ee7SDaniel Vetter /* instanceof for props.. handles extended type vs original types: */ 23559e71ee7SDaniel Vetter if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) 23659e71ee7SDaniel Vetter return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type; 23759e71ee7SDaniel Vetter return property->flags & type; 23859e71ee7SDaniel Vetter } 23959e71ee7SDaniel Vetter 24059e71ee7SDaniel Vetter struct drm_property *drm_property_create(struct drm_device *dev, int flags, 24159e71ee7SDaniel Vetter const char *name, int num_values); 24259e71ee7SDaniel Vetter struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags, 24359e71ee7SDaniel Vetter const char *name, 24459e71ee7SDaniel Vetter const struct drm_prop_enum_list *props, 24559e71ee7SDaniel Vetter int num_values); 24659e71ee7SDaniel Vetter struct drm_property *drm_property_create_bitmask(struct drm_device *dev, 24759e71ee7SDaniel Vetter int flags, const char *name, 24859e71ee7SDaniel Vetter const struct drm_prop_enum_list *props, 24959e71ee7SDaniel Vetter int num_props, 25059e71ee7SDaniel Vetter uint64_t supported_bits); 25159e71ee7SDaniel Vetter struct drm_property *drm_property_create_range(struct drm_device *dev, int flags, 25259e71ee7SDaniel Vetter const char *name, 25359e71ee7SDaniel Vetter uint64_t min, uint64_t max); 25459e71ee7SDaniel Vetter struct drm_property *drm_property_create_signed_range(struct drm_device *dev, 25559e71ee7SDaniel Vetter int flags, const char *name, 25659e71ee7SDaniel Vetter int64_t min, int64_t max); 25759e71ee7SDaniel Vetter struct drm_property *drm_property_create_object(struct drm_device *dev, 25859e71ee7SDaniel Vetter int flags, const char *name, uint32_t type); 25959e71ee7SDaniel Vetter struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags, 26059e71ee7SDaniel Vetter const char *name); 26159e71ee7SDaniel Vetter int drm_property_add_enum(struct drm_property *property, int index, 26259e71ee7SDaniel Vetter uint64_t value, const char *name); 26359e71ee7SDaniel Vetter void drm_property_destroy(struct drm_device *dev, struct drm_property *property); 26459e71ee7SDaniel Vetter 26559e71ee7SDaniel Vetter struct drm_property_blob *drm_property_create_blob(struct drm_device *dev, 26659e71ee7SDaniel Vetter size_t length, 26759e71ee7SDaniel Vetter const void *data); 26859e71ee7SDaniel Vetter struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev, 26959e71ee7SDaniel Vetter uint32_t id); 27059e71ee7SDaniel Vetter int drm_property_replace_global_blob(struct drm_device *dev, 27159e71ee7SDaniel Vetter struct drm_property_blob **replace, 27259e71ee7SDaniel Vetter size_t length, 27359e71ee7SDaniel Vetter const void *data, 27459e71ee7SDaniel Vetter struct drm_mode_object *obj_holds_id, 27559e71ee7SDaniel Vetter struct drm_property *prop_holds_id); 2765f057ffdSPeter Rosin bool drm_property_replace_blob(struct drm_property_blob **blob, 2775f057ffdSPeter Rosin struct drm_property_blob *new_blob); 2786472e509SThierry Reding struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob); 2796472e509SThierry Reding void drm_property_blob_put(struct drm_property_blob *blob); 2806472e509SThierry Reding 2816472e509SThierry Reding /** 2826472e509SThierry Reding * drm_property_reference_blob - acquire a blob property reference 2836472e509SThierry Reding * @blob: DRM blob property 2846472e509SThierry Reding * 2856472e509SThierry Reding * This is a compatibility alias for drm_property_blob_get() and should not be 2866472e509SThierry Reding * used by new code. 2876472e509SThierry Reding */ 2886472e509SThierry Reding static inline struct drm_property_blob * 2896472e509SThierry Reding drm_property_reference_blob(struct drm_property_blob *blob) 2906472e509SThierry Reding { 2916472e509SThierry Reding return drm_property_blob_get(blob); 2926472e509SThierry Reding } 2936472e509SThierry Reding 2946472e509SThierry Reding /** 2956472e509SThierry Reding * drm_property_unreference_blob - release a blob property reference 2966472e509SThierry Reding * @blob: DRM blob property 2976472e509SThierry Reding * 2986472e509SThierry Reding * This is a compatibility alias for drm_property_blob_put() and should not be 2996472e509SThierry Reding * used by new code. 3006472e509SThierry Reding */ 3016472e509SThierry Reding static inline void 3026472e509SThierry Reding drm_property_unreference_blob(struct drm_property_blob *blob) 3036472e509SThierry Reding { 3046472e509SThierry Reding drm_property_blob_put(blob); 3056472e509SThierry Reding } 30659e71ee7SDaniel Vetter 307c8458c7eSDaniel Vetter /** 308c8458c7eSDaniel Vetter * drm_connector_find - find property object 309c8458c7eSDaniel Vetter * @dev: DRM device 310c8458c7eSDaniel Vetter * @id: property object id 311c8458c7eSDaniel Vetter * 312c8458c7eSDaniel Vetter * This function looks up the property object specified by id and returns it. 313c8458c7eSDaniel Vetter */ 31459e71ee7SDaniel Vetter static inline struct drm_property *drm_property_find(struct drm_device *dev, 315418da172SKeith Packard struct drm_file *file_priv, 31659e71ee7SDaniel Vetter uint32_t id) 31759e71ee7SDaniel Vetter { 31859e71ee7SDaniel Vetter struct drm_mode_object *mo; 319418da172SKeith Packard mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY); 32059e71ee7SDaniel Vetter return mo ? obj_to_property(mo) : NULL; 32159e71ee7SDaniel Vetter } 32259e71ee7SDaniel Vetter 32359e71ee7SDaniel Vetter #endif 324