drm_property.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310
  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. #ifndef __DRM_PROPERTY_H__
  23. #define __DRM_PROPERTY_H__
  24. #include <linux/list.h>
  25. #include <linux/ctype.h>
  26. #include <drm/drm_mode_object.h>
  27. #include <uapi/drm/drm_mode.h>
  28. /**
  29. * struct drm_property_enum - symbolic values for enumerations
  30. * @head: list of enum values, linked to &drm_property.enum_list
  31. * @name: symbolic name for the enum
  32. *
  33. * For enumeration and bitmask properties this structure stores the symbolic
  34. * decoding for each value. This is used for example for the rotation property.
  35. */
  36. struct drm_property_enum {
  37. /**
  38. * @value: numeric property value for this enum entry
  39. *
  40. * If the property has the type &DRM_MODE_PROP_BITMASK, @value stores a
  41. * bitshift, not a bitmask. In other words, the enum entry is enabled
  42. * if the bit number @value is set in the property's value. This enum
  43. * entry has the bitmask ``1 << value``.
  44. */
  45. uint64_t value;
  46. struct list_head head;
  47. char name[DRM_PROP_NAME_LEN];
  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. * @base: base KMS object
  82. */
  83. struct drm_mode_object base;
  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_PROP_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. Kernel can update the value of an immutable property
  157. * by calling drm_object_property_set_value().
  158. */
  159. uint32_t flags;
  160. /**
  161. * @name: symbolic name of the properties
  162. */
  163. char name[DRM_PROP_NAME_LEN];
  164. /**
  165. * @num_values: size of the @values array.
  166. */
  167. uint32_t num_values;
  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. * @dev: DRM device
  177. */
  178. struct drm_device *dev;
  179. /**
  180. * @enum_list:
  181. *
  182. * List of &drm_prop_enum_list structures with the symbolic names for
  183. * enum and bitmask values.
  184. */
  185. struct list_head enum_list;
  186. };
  187. /**
  188. * struct drm_property_blob - Blob data for &drm_property
  189. * @base: base KMS object
  190. * @dev: DRM device
  191. * @head_global: entry on the global blob list in
  192. * &drm_mode_config.property_blob_list.
  193. * @head_file: entry on the per-file blob list in &drm_file.blobs list.
  194. * @length: size of the blob in bytes, invariant over the lifetime of the object
  195. * @data: actual data, embedded at the end of this structure
  196. *
  197. * Blobs are used to store bigger values than what fits directly into the 64
  198. * bits available for a &drm_property.
  199. *
  200. * Blobs are reference counted using drm_property_blob_get() and
  201. * drm_property_blob_put(). They are created using drm_property_create_blob().
  202. */
  203. struct drm_property_blob {
  204. struct drm_mode_object base;
  205. struct drm_device *dev;
  206. struct list_head head_global;
  207. struct list_head head_file;
  208. size_t length;
  209. void *data;
  210. };
  211. struct drm_prop_enum_list {
  212. int type;
  213. const char *name;
  214. };
  215. #define obj_to_property(x) container_of(x, struct drm_property, base)
  216. #define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
  217. /**
  218. * drm_property_type_is - check the type of a property
  219. * @property: property to check
  220. * @type: property type to compare with
  221. *
  222. * This is a helper function becauase the uapi encoding of property types is
  223. * a bit special for historical reasons.
  224. */
  225. static inline bool drm_property_type_is(struct drm_property *property,
  226. uint32_t type)
  227. {
  228. /* instanceof for props.. handles extended type vs original types: */
  229. if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
  230. return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
  231. return property->flags & type;
  232. }
  233. struct drm_property *drm_property_create(struct drm_device *dev,
  234. u32 flags, const char *name,
  235. int num_values);
  236. struct drm_property *drm_property_create_enum(struct drm_device *dev,
  237. u32 flags, const char *name,
  238. const struct drm_prop_enum_list *props,
  239. int num_values);
  240. struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
  241. u32 flags, const char *name,
  242. const struct drm_prop_enum_list *props,
  243. int num_props,
  244. uint64_t supported_bits);
  245. struct drm_property *drm_property_create_range(struct drm_device *dev,
  246. u32 flags, const char *name,
  247. uint64_t min, uint64_t max);
  248. struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
  249. u32 flags, const char *name,
  250. int64_t min, int64_t max);
  251. struct drm_property *drm_property_create_object(struct drm_device *dev,
  252. u32 flags, const char *name,
  253. uint32_t type);
  254. struct drm_property *drm_property_create_bool(struct drm_device *dev,
  255. u32 flags, const char *name);
  256. int drm_property_add_enum(struct drm_property *property,
  257. uint64_t value, const char *name);
  258. void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
  259. struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
  260. size_t length,
  261. const void *data);
  262. struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
  263. uint32_t id);
  264. int drm_property_replace_global_blob(struct drm_device *dev,
  265. struct drm_property_blob **replace,
  266. size_t length,
  267. const void *data,
  268. struct drm_mode_object *obj_holds_id,
  269. struct drm_property *prop_holds_id);
  270. bool drm_property_replace_blob(struct drm_property_blob **blob,
  271. struct drm_property_blob *new_blob);
  272. struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
  273. void drm_property_blob_put(struct drm_property_blob *blob);
  274. /**
  275. * drm_property_find - find property object
  276. * @dev: DRM device
  277. * @file_priv: drm file to check for lease against.
  278. * @id: property object id
  279. *
  280. * This function looks up the property object specified by id and returns it.
  281. */
  282. static inline struct drm_property *drm_property_find(struct drm_device *dev,
  283. struct drm_file *file_priv,
  284. uint32_t id)
  285. {
  286. struct drm_mode_object *mo;
  287. mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
  288. return mo ? obj_to_property(mo) : NULL;
  289. }
  290. #endif