drm_property.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303
  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. * @value: numeric property value for this enum entry
  31. * @head: list of enum values, linked to &drm_property.enum_list
  32. * @name: symbolic name for the enum
  33. *
  34. * For enumeration and bitmask properties this structure stores the symbolic
  35. * decoding for each value. This is used for example for the rotation property.
  36. */
  37. struct drm_property_enum {
  38. uint64_t value;
  39. struct list_head head;
  40. char name[DRM_PROP_NAME_LEN];
  41. };
  42. /**
  43. * struct drm_property - modeset object property
  44. *
  45. * This structure represent a modeset object property. It combines both the name
  46. * of the property with the set of permissible values. This means that when a
  47. * driver wants to use a property with the same name on different objects, but
  48. * with different value ranges, then it must create property for each one. An
  49. * example would be rotation of &drm_plane, when e.g. the primary plane cannot
  50. * be rotated. But if both the name and the value range match, then the same
  51. * property structure can be instantiated multiple times for the same object.
  52. * Userspace must be able to cope with this and cannot assume that the same
  53. * symbolic property will have the same modeset object ID on all modeset
  54. * objects.
  55. *
  56. * Properties are created by one of the special functions, as explained in
  57. * detail in the @flags structure member.
  58. *
  59. * To actually expose a property it must be attached to each object using
  60. * drm_object_attach_property(). Currently properties can only be attached to
  61. * &drm_connector, &drm_crtc and &drm_plane.
  62. *
  63. * Properties are also used as the generic metadatatransport for the atomic
  64. * IOCTL. Everything that was set directly in structures in the legacy modeset
  65. * IOCTLs (like the plane source or destination windows, or e.g. the links to
  66. * the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.
  67. */
  68. struct drm_property {
  69. /**
  70. * @head: per-device list of properties, for cleanup.
  71. */
  72. struct list_head head;
  73. /**
  74. * @base: base KMS object
  75. */
  76. struct drm_mode_object base;
  77. /**
  78. * @flags:
  79. *
  80. * Property flags and type. A property needs to be one of the following
  81. * types:
  82. *
  83. * DRM_MODE_PROP_RANGE
  84. * Range properties report their minimum and maximum admissible unsigned values.
  85. * The KMS core verifies that values set by application fit in that
  86. * range. The range is unsigned. Range properties are created using
  87. * drm_property_create_range().
  88. *
  89. * DRM_MODE_PROP_SIGNED_RANGE
  90. * Range properties report their minimum and maximum admissible unsigned values.
  91. * The KMS core verifies that values set by application fit in that
  92. * range. The range is signed. Range properties are created using
  93. * drm_property_create_signed_range().
  94. *
  95. * DRM_MODE_PROP_ENUM
  96. * Enumerated properties take a numerical value that ranges from 0 to
  97. * the number of enumerated values defined by the property minus one,
  98. * and associate a free-formed string name to each value. Applications
  99. * can retrieve the list of defined value-name pairs and use the
  100. * numerical value to get and set property instance values. Enum
  101. * properties are created using drm_property_create_enum().
  102. *
  103. * DRM_MODE_PROP_BITMASK
  104. * Bitmask properties are enumeration properties that additionally
  105. * restrict all enumerated values to the 0..63 range. Bitmask property
  106. * instance values combine one or more of the enumerated bits defined
  107. * by the property. Bitmask properties are created using
  108. * drm_property_create_bitmask().
  109. *
  110. * DRM_MODE_PROB_OBJECT
  111. * Object properties are used to link modeset objects. This is used
  112. * extensively in the atomic support to create the display pipeline,
  113. * by linking &drm_framebuffer to &drm_plane, &drm_plane to
  114. * &drm_crtc and &drm_connector to &drm_crtc. An object property can
  115. * only link to a specific type of &drm_mode_object, this limit is
  116. * enforced by the core. Object properties are created using
  117. * drm_property_create_object().
  118. *
  119. * Object properties work like blob properties, but in a more
  120. * general fashion. They are limited to atomic drivers and must have
  121. * the DRM_MODE_PROP_ATOMIC flag set.
  122. *
  123. * DRM_MODE_PROP_BLOB
  124. * Blob properties store a binary blob without any format restriction.
  125. * The binary blobs are created as KMS standalone objects, and blob
  126. * property instance values store the ID of their associated blob
  127. * object. Blob properties are created by calling
  128. * drm_property_create() with DRM_MODE_PROP_BLOB as the type.
  129. *
  130. * Actual blob objects to contain blob data are created using
  131. * drm_property_create_blob(), or through the corresponding IOCTL.
  132. *
  133. * Besides the built-in limit to only accept blob objects blob
  134. * properties work exactly like object properties. The only reasons
  135. * blob properties exist is backwards compatibility with existing
  136. * userspace.
  137. *
  138. * In addition a property can have any combination of the below flags:
  139. *
  140. * DRM_MODE_PROP_ATOMIC
  141. * Set for properties which encode atomic modeset state. Such
  142. * properties are not exposed to legacy userspace.
  143. *
  144. * DRM_MODE_PROP_IMMUTABLE
  145. * Set for properties whose values cannot be changed by
  146. * userspace. The kernel is allowed to update the value of these
  147. * properties. This is generally used to expose probe state to
  148. * userspace, e.g. the EDID, or the connector path property on DP
  149. * MST sinks. Kernel can update the value of an immutable property
  150. * by calling drm_object_property_set_value().
  151. */
  152. uint32_t flags;
  153. /**
  154. * @name: symbolic name of the properties
  155. */
  156. char name[DRM_PROP_NAME_LEN];
  157. /**
  158. * @num_values: size of the @values array.
  159. */
  160. uint32_t num_values;
  161. /**
  162. * @values:
  163. *
  164. * Array with limits and values for the property. The
  165. * interpretation of these limits is dependent upon the type per @flags.
  166. */
  167. uint64_t *values;
  168. /**
  169. * @dev: DRM device
  170. */
  171. struct drm_device *dev;
  172. /**
  173. * @enum_list:
  174. *
  175. * List of &drm_prop_enum_list structures with the symbolic names for
  176. * enum and bitmask values.
  177. */
  178. struct list_head enum_list;
  179. };
  180. /**
  181. * struct drm_property_blob - Blob data for &drm_property
  182. * @base: base KMS object
  183. * @dev: DRM device
  184. * @head_global: entry on the global blob list in
  185. * &drm_mode_config.property_blob_list.
  186. * @head_file: entry on the per-file blob list in &drm_file.blobs list.
  187. * @length: size of the blob in bytes, invariant over the lifetime of the object
  188. * @data: actual data, embedded at the end of this structure
  189. *
  190. * Blobs are used to store bigger values than what fits directly into the 64
  191. * bits available for a &drm_property.
  192. *
  193. * Blobs are reference counted using drm_property_blob_get() and
  194. * drm_property_blob_put(). They are created using drm_property_create_blob().
  195. */
  196. struct drm_property_blob {
  197. struct drm_mode_object base;
  198. struct drm_device *dev;
  199. struct list_head head_global;
  200. struct list_head head_file;
  201. size_t length;
  202. void *data;
  203. };
  204. struct drm_prop_enum_list {
  205. int type;
  206. const char *name;
  207. };
  208. #define obj_to_property(x) container_of(x, struct drm_property, base)
  209. #define obj_to_blob(x) container_of(x, struct drm_property_blob, base)
  210. /**
  211. * drm_property_type_is - check the type of a property
  212. * @property: property to check
  213. * @type: property type to compare with
  214. *
  215. * This is a helper function becauase the uapi encoding of property types is
  216. * a bit special for historical reasons.
  217. */
  218. static inline bool drm_property_type_is(struct drm_property *property,
  219. uint32_t type)
  220. {
  221. /* instanceof for props.. handles extended type vs original types: */
  222. if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
  223. return (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) == type;
  224. return property->flags & type;
  225. }
  226. struct drm_property *drm_property_create(struct drm_device *dev,
  227. u32 flags, const char *name,
  228. int num_values);
  229. struct drm_property *drm_property_create_enum(struct drm_device *dev,
  230. u32 flags, const char *name,
  231. const struct drm_prop_enum_list *props,
  232. int num_values);
  233. struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
  234. u32 flags, const char *name,
  235. const struct drm_prop_enum_list *props,
  236. int num_props,
  237. uint64_t supported_bits);
  238. struct drm_property *drm_property_create_range(struct drm_device *dev,
  239. u32 flags, const char *name,
  240. uint64_t min, uint64_t max);
  241. struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
  242. u32 flags, const char *name,
  243. int64_t min, int64_t max);
  244. struct drm_property *drm_property_create_object(struct drm_device *dev,
  245. u32 flags, const char *name,
  246. uint32_t type);
  247. struct drm_property *drm_property_create_bool(struct drm_device *dev,
  248. u32 flags, const char *name);
  249. int drm_property_add_enum(struct drm_property *property,
  250. uint64_t value, const char *name);
  251. void drm_property_destroy(struct drm_device *dev, struct drm_property *property);
  252. struct drm_property_blob *drm_property_create_blob(struct drm_device *dev,
  253. size_t length,
  254. const void *data);
  255. struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
  256. uint32_t id);
  257. int drm_property_replace_global_blob(struct drm_device *dev,
  258. struct drm_property_blob **replace,
  259. size_t length,
  260. const void *data,
  261. struct drm_mode_object *obj_holds_id,
  262. struct drm_property *prop_holds_id);
  263. bool drm_property_replace_blob(struct drm_property_blob **blob,
  264. struct drm_property_blob *new_blob);
  265. struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob);
  266. void drm_property_blob_put(struct drm_property_blob *blob);
  267. /**
  268. * drm_property_find - find property object
  269. * @dev: DRM device
  270. * @file_priv: drm file to check for lease against.
  271. * @id: property object id
  272. *
  273. * This function looks up the property object specified by id and returns it.
  274. */
  275. static inline struct drm_property *drm_property_find(struct drm_device *dev,
  276. struct drm_file *file_priv,
  277. uint32_t id)
  278. {
  279. struct drm_mode_object *mo;
  280. mo = drm_mode_object_find(dev, file_priv, id, DRM_MODE_OBJECT_PROPERTY);
  281. return mo ? obj_to_property(mo) : NULL;
  282. }
  283. #endif