ttm_object.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332
  1. /**************************************************************************
  2. *
  3. * Copyright (c) 2006-2009 VMware, Inc., Palo Alto, CA., USA
  4. * All Rights Reserved.
  5. *
  6. * Permission is hereby granted, free of charge, to any person obtaining a
  7. * copy of this software and associated documentation files (the
  8. * "Software"), to deal in the Software without restriction, including
  9. * without limitation the rights to use, copy, modify, merge, publish,
  10. * distribute, sub license, and/or sell copies of the Software, and to
  11. * permit persons to whom the Software is furnished to do so, subject to
  12. * the following conditions:
  13. *
  14. * The above copyright notice and this permission notice (including the
  15. * next paragraph) shall be included in all copies or substantial portions
  16. * of the Software.
  17. *
  18. * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  19. * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  20. * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
  21. * THE COPYRIGHT HOLDERS, AUTHORS AND/OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM,
  22. * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  23. * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
  24. * USE OR OTHER DEALINGS IN THE SOFTWARE.
  25. *
  26. **************************************************************************/
  27. /*
  28. * Authors: Thomas Hellstrom <thellstrom-at-vmware-dot-com>
  29. */
  30. /** @file ttm_object.h
  31. *
  32. * Base- and reference object implementation for the various
  33. * ttm objects. Implements reference counting, minimal security checks
  34. * and release on file close.
  35. */
  36. #ifndef _TTM_OBJECT_H_
  37. #define _TTM_OBJECT_H_
  38. #include <linux/list.h>
  39. #include <drm/drm_hashtab.h>
  40. #include <linux/kref.h>
  41. #include <linux/rcupdate.h>
  42. #include <linux/dma-buf.h>
  43. #include <ttm/ttm_memory.h>
  44. /**
  45. * enum ttm_ref_type
  46. *
  47. * Describes what type of reference a ref object holds.
  48. *
  49. * TTM_REF_USAGE is a simple refcount on a base object.
  50. *
  51. * TTM_REF_SYNCCPU_READ is a SYNCCPU_READ reference on a
  52. * buffer object.
  53. *
  54. * TTM_REF_SYNCCPU_WRITE is a SYNCCPU_WRITE reference on a
  55. * buffer object.
  56. *
  57. */
  58. enum ttm_ref_type {
  59. TTM_REF_USAGE,
  60. TTM_REF_SYNCCPU_READ,
  61. TTM_REF_SYNCCPU_WRITE,
  62. TTM_REF_NUM
  63. };
  64. /**
  65. * enum ttm_object_type
  66. *
  67. * One entry per ttm object type.
  68. * Device-specific types should use the
  69. * ttm_driver_typex types.
  70. */
  71. enum ttm_object_type {
  72. ttm_fence_type,
  73. ttm_buffer_type,
  74. ttm_lock_type,
  75. ttm_prime_type,
  76. ttm_driver_type0 = 256,
  77. ttm_driver_type1,
  78. ttm_driver_type2,
  79. ttm_driver_type3,
  80. ttm_driver_type4,
  81. ttm_driver_type5
  82. };
  83. struct ttm_object_file;
  84. struct ttm_object_device;
  85. /**
  86. * struct ttm_base_object
  87. *
  88. * @hash: hash entry for the per-device object hash.
  89. * @type: derived type this object is base class for.
  90. * @shareable: Other ttm_object_files can access this object.
  91. *
  92. * @tfile: Pointer to ttm_object_file of the creator.
  93. * NULL if the object was not created by a user request.
  94. * (kernel object).
  95. *
  96. * @refcount: Number of references to this object, not
  97. * including the hash entry. A reference to a base object can
  98. * only be held by a ref object.
  99. *
  100. * @refcount_release: A function to be called when there are
  101. * no more references to this object. This function should
  102. * destroy the object (or make sure destruction eventually happens),
  103. * and when it is called, the object has
  104. * already been taken out of the per-device hash. The parameter
  105. * "base" should be set to NULL by the function.
  106. *
  107. * @ref_obj_release: A function to be called when a reference object
  108. * with another ttm_ref_type than TTM_REF_USAGE is deleted.
  109. * This function may, for example, release a lock held by a user-space
  110. * process.
  111. *
  112. * This struct is intended to be used as a base struct for objects that
  113. * are visible to user-space. It provides a global name, race-safe
  114. * access and refcounting, minimal access contol and hooks for unref actions.
  115. */
  116. struct ttm_base_object {
  117. struct rcu_head rhead;
  118. struct drm_hash_item hash;
  119. enum ttm_object_type object_type;
  120. bool shareable;
  121. struct ttm_object_file *tfile;
  122. struct kref refcount;
  123. void (*refcount_release) (struct ttm_base_object **base);
  124. void (*ref_obj_release) (struct ttm_base_object *base,
  125. enum ttm_ref_type ref_type);
  126. };
  127. /**
  128. * struct ttm_prime_object - Modified base object that is prime-aware
  129. *
  130. * @base: struct ttm_base_object that we derive from
  131. * @mutex: Mutex protecting the @dma_buf member.
  132. * @size: Size of the dma_buf associated with this object
  133. * @real_type: Type of the underlying object. Needed since we're setting
  134. * the value of @base::object_type to ttm_prime_type
  135. * @dma_buf: Non ref-coutned pointer to a struct dma_buf created from this
  136. * object.
  137. * @refcount_release: The underlying object's release method. Needed since
  138. * we set @base::refcount_release to our own release method.
  139. */
  140. struct ttm_prime_object {
  141. struct ttm_base_object base;
  142. struct mutex mutex;
  143. size_t size;
  144. enum ttm_object_type real_type;
  145. struct dma_buf *dma_buf;
  146. void (*refcount_release) (struct ttm_base_object **);
  147. };
  148. /**
  149. * ttm_base_object_init
  150. *
  151. * @tfile: Pointer to a struct ttm_object_file.
  152. * @base: The struct ttm_base_object to initialize.
  153. * @shareable: This object is shareable with other applcations.
  154. * (different @tfile pointers.)
  155. * @type: The object type.
  156. * @refcount_release: See the struct ttm_base_object description.
  157. * @ref_obj_release: See the struct ttm_base_object description.
  158. *
  159. * Initializes a struct ttm_base_object.
  160. */
  161. extern int ttm_base_object_init(struct ttm_object_file *tfile,
  162. struct ttm_base_object *base,
  163. bool shareable,
  164. enum ttm_object_type type,
  165. void (*refcount_release) (struct ttm_base_object
  166. **),
  167. void (*ref_obj_release) (struct ttm_base_object
  168. *,
  169. enum ttm_ref_type
  170. ref_type));
  171. /**
  172. * ttm_base_object_lookup
  173. *
  174. * @tfile: Pointer to a struct ttm_object_file.
  175. * @key: Hash key
  176. *
  177. * Looks up a struct ttm_base_object with the key @key.
  178. * Also verifies that the object is visible to the application, by
  179. * comparing the @tfile argument and checking the object shareable flag.
  180. */
  181. extern struct ttm_base_object *ttm_base_object_lookup(struct ttm_object_file
  182. *tfile, uint32_t key);
  183. /**
  184. * ttm_base_object_unref
  185. *
  186. * @p_base: Pointer to a pointer referencing a struct ttm_base_object.
  187. *
  188. * Decrements the base object refcount and clears the pointer pointed to by
  189. * p_base.
  190. */
  191. extern void ttm_base_object_unref(struct ttm_base_object **p_base);
  192. /**
  193. * ttm_ref_object_add.
  194. *
  195. * @tfile: A struct ttm_object_file representing the application owning the
  196. * ref_object.
  197. * @base: The base object to reference.
  198. * @ref_type: The type of reference.
  199. * @existed: Upon completion, indicates that an identical reference object
  200. * already existed, and the refcount was upped on that object instead.
  201. *
  202. * Adding a ref object to a base object is basically like referencing the
  203. * base object, but a user-space application holds the reference. When the
  204. * file corresponding to @tfile is closed, all its reference objects are
  205. * deleted. A reference object can have different types depending on what
  206. * it's intended for. It can be refcounting to prevent object destruction,
  207. * When user-space takes a lock, it can add a ref object to that lock to
  208. * make sure the lock is released if the application dies. A ref object
  209. * will hold a single reference on a base object.
  210. */
  211. extern int ttm_ref_object_add(struct ttm_object_file *tfile,
  212. struct ttm_base_object *base,
  213. enum ttm_ref_type ref_type, bool *existed);
  214. /**
  215. * ttm_ref_object_base_unref
  216. *
  217. * @key: Key representing the base object.
  218. * @ref_type: Ref type of the ref object to be dereferenced.
  219. *
  220. * Unreference a ref object with type @ref_type
  221. * on the base object identified by @key. If there are no duplicate
  222. * references, the ref object will be destroyed and the base object
  223. * will be unreferenced.
  224. */
  225. extern int ttm_ref_object_base_unref(struct ttm_object_file *tfile,
  226. unsigned long key,
  227. enum ttm_ref_type ref_type);
  228. /**
  229. * ttm_object_file_init - initialize a struct ttm_object file
  230. *
  231. * @tdev: A struct ttm_object device this file is initialized on.
  232. * @hash_order: Order of the hash table used to hold the reference objects.
  233. *
  234. * This is typically called by the file_ops::open function.
  235. */
  236. extern struct ttm_object_file *ttm_object_file_init(struct ttm_object_device
  237. *tdev,
  238. unsigned int hash_order);
  239. /**
  240. * ttm_object_file_release - release data held by a ttm_object_file
  241. *
  242. * @p_tfile: Pointer to pointer to the ttm_object_file object to release.
  243. * *p_tfile will be set to NULL by this function.
  244. *
  245. * Releases all data associated by a ttm_object_file.
  246. * Typically called from file_ops::release. The caller must
  247. * ensure that there are no concurrent users of tfile.
  248. */
  249. extern void ttm_object_file_release(struct ttm_object_file **p_tfile);
  250. /**
  251. * ttm_object device init - initialize a struct ttm_object_device
  252. *
  253. * @mem_glob: struct ttm_mem_global for memory accounting.
  254. * @hash_order: Order of hash table used to hash the base objects.
  255. * @ops: DMA buf ops for prime objects of this device.
  256. *
  257. * This function is typically called on device initialization to prepare
  258. * data structures needed for ttm base and ref objects.
  259. */
  260. extern struct ttm_object_device *
  261. ttm_object_device_init(struct ttm_mem_global *mem_glob,
  262. unsigned int hash_order,
  263. const struct dma_buf_ops *ops);
  264. /**
  265. * ttm_object_device_release - release data held by a ttm_object_device
  266. *
  267. * @p_tdev: Pointer to pointer to the ttm_object_device object to release.
  268. * *p_tdev will be set to NULL by this function.
  269. *
  270. * Releases all data associated by a ttm_object_device.
  271. * Typically called from driver::unload before the destruction of the
  272. * device private data structure.
  273. */
  274. extern void ttm_object_device_release(struct ttm_object_device **p_tdev);
  275. #define ttm_base_object_kfree(__object, __base)\
  276. kfree_rcu(__object, __base.rhead)
  277. extern int ttm_prime_object_init(struct ttm_object_file *tfile,
  278. size_t size,
  279. struct ttm_prime_object *prime,
  280. bool shareable,
  281. enum ttm_object_type type,
  282. void (*refcount_release)
  283. (struct ttm_base_object **),
  284. void (*ref_obj_release)
  285. (struct ttm_base_object *,
  286. enum ttm_ref_type ref_type));
  287. static inline enum ttm_object_type
  288. ttm_base_object_type(struct ttm_base_object *base)
  289. {
  290. return (base->object_type == ttm_prime_type) ?
  291. container_of(base, struct ttm_prime_object, base)->real_type :
  292. base->object_type;
  293. }
  294. extern int ttm_prime_fd_to_handle(struct ttm_object_file *tfile,
  295. int fd, u32 *handle);
  296. extern int ttm_prime_handle_to_fd(struct ttm_object_file *tfile,
  297. uint32_t handle, uint32_t flags,
  298. int *prime_fd);
  299. #define ttm_prime_object_kfree(__obj, __prime) \
  300. kfree_rcu(__obj, __prime.base.rhead)
  301. #endif