ttm_object.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376
  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/dma-buf.h>
  39. #include <linux/kref.h>
  40. #include <linux/list.h>
  41. #include <linux/rcupdate.h>
  42. #include <drm/drm_hashtab.h>
  43. #include <drm/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 ttm_object_file *tfile;
  119. struct kref refcount;
  120. void (*refcount_release) (struct ttm_base_object **base);
  121. void (*ref_obj_release) (struct ttm_base_object *base,
  122. enum ttm_ref_type ref_type);
  123. u32 handle;
  124. enum ttm_object_type object_type;
  125. u32 shareable;
  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. */
  179. extern struct ttm_base_object *ttm_base_object_lookup(struct ttm_object_file
  180. *tfile, uint32_t key);
  181. /**
  182. * ttm_base_object_lookup_for_ref
  183. *
  184. * @tdev: Pointer to a struct ttm_object_device.
  185. * @key: Hash key
  186. *
  187. * Looks up a struct ttm_base_object with the key @key.
  188. * This function should only be used when the struct tfile associated with the
  189. * caller doesn't yet have a reference to the base object.
  190. */
  191. extern struct ttm_base_object *
  192. ttm_base_object_lookup_for_ref(struct ttm_object_device *tdev, uint32_t key);
  193. /**
  194. * ttm_base_object_unref
  195. *
  196. * @p_base: Pointer to a pointer referencing a struct ttm_base_object.
  197. *
  198. * Decrements the base object refcount and clears the pointer pointed to by
  199. * p_base.
  200. */
  201. extern void ttm_base_object_unref(struct ttm_base_object **p_base);
  202. /**
  203. * ttm_ref_object_add.
  204. *
  205. * @tfile: A struct ttm_object_file representing the application owning the
  206. * ref_object.
  207. * @base: The base object to reference.
  208. * @ref_type: The type of reference.
  209. * @existed: Upon completion, indicates that an identical reference object
  210. * already existed, and the refcount was upped on that object instead.
  211. * @require_existed: Fail with -EPERM if an identical ref object didn't
  212. * already exist.
  213. *
  214. * Checks that the base object is shareable and adds a ref object to it.
  215. *
  216. * Adding a ref object to a base object is basically like referencing the
  217. * base object, but a user-space application holds the reference. When the
  218. * file corresponding to @tfile is closed, all its reference objects are
  219. * deleted. A reference object can have different types depending on what
  220. * it's intended for. It can be refcounting to prevent object destruction,
  221. * When user-space takes a lock, it can add a ref object to that lock to
  222. * make sure the lock is released if the application dies. A ref object
  223. * will hold a single reference on a base object.
  224. */
  225. extern int ttm_ref_object_add(struct ttm_object_file *tfile,
  226. struct ttm_base_object *base,
  227. enum ttm_ref_type ref_type, bool *existed,
  228. bool require_existed);
  229. extern bool ttm_ref_object_exists(struct ttm_object_file *tfile,
  230. struct ttm_base_object *base);
  231. /**
  232. * ttm_ref_object_base_unref
  233. *
  234. * @key: Key representing the base object.
  235. * @ref_type: Ref type of the ref object to be dereferenced.
  236. *
  237. * Unreference a ref object with type @ref_type
  238. * on the base object identified by @key. If there are no duplicate
  239. * references, the ref object will be destroyed and the base object
  240. * will be unreferenced.
  241. */
  242. extern int ttm_ref_object_base_unref(struct ttm_object_file *tfile,
  243. unsigned long key,
  244. enum ttm_ref_type ref_type);
  245. /**
  246. * ttm_object_file_init - initialize a struct ttm_object file
  247. *
  248. * @tdev: A struct ttm_object device this file is initialized on.
  249. * @hash_order: Order of the hash table used to hold the reference objects.
  250. *
  251. * This is typically called by the file_ops::open function.
  252. */
  253. extern struct ttm_object_file *ttm_object_file_init(struct ttm_object_device
  254. *tdev,
  255. unsigned int hash_order);
  256. /**
  257. * ttm_object_file_release - release data held by a ttm_object_file
  258. *
  259. * @p_tfile: Pointer to pointer to the ttm_object_file object to release.
  260. * *p_tfile will be set to NULL by this function.
  261. *
  262. * Releases all data associated by a ttm_object_file.
  263. * Typically called from file_ops::release. The caller must
  264. * ensure that there are no concurrent users of tfile.
  265. */
  266. extern void ttm_object_file_release(struct ttm_object_file **p_tfile);
  267. /**
  268. * ttm_object device init - initialize a struct ttm_object_device
  269. *
  270. * @mem_glob: struct ttm_mem_global for memory accounting.
  271. * @hash_order: Order of hash table used to hash the base objects.
  272. * @ops: DMA buf ops for prime objects of this device.
  273. *
  274. * This function is typically called on device initialization to prepare
  275. * data structures needed for ttm base and ref objects.
  276. */
  277. extern struct ttm_object_device *
  278. ttm_object_device_init(struct ttm_mem_global *mem_glob,
  279. unsigned int hash_order,
  280. const struct dma_buf_ops *ops);
  281. /**
  282. * ttm_object_device_release - release data held by a ttm_object_device
  283. *
  284. * @p_tdev: Pointer to pointer to the ttm_object_device object to release.
  285. * *p_tdev will be set to NULL by this function.
  286. *
  287. * Releases all data associated by a ttm_object_device.
  288. * Typically called from driver::unload before the destruction of the
  289. * device private data structure.
  290. */
  291. extern void ttm_object_device_release(struct ttm_object_device **p_tdev);
  292. #define ttm_base_object_kfree(__object, __base)\
  293. kfree_rcu(__object, __base.rhead)
  294. extern int ttm_prime_object_init(struct ttm_object_file *tfile,
  295. size_t size,
  296. struct ttm_prime_object *prime,
  297. bool shareable,
  298. enum ttm_object_type type,
  299. void (*refcount_release)
  300. (struct ttm_base_object **),
  301. void (*ref_obj_release)
  302. (struct ttm_base_object *,
  303. enum ttm_ref_type ref_type));
  304. static inline enum ttm_object_type
  305. ttm_base_object_type(struct ttm_base_object *base)
  306. {
  307. return (base->object_type == ttm_prime_type) ?
  308. container_of(base, struct ttm_prime_object, base)->real_type :
  309. base->object_type;
  310. }
  311. extern int ttm_prime_fd_to_handle(struct ttm_object_file *tfile,
  312. int fd, u32 *handle);
  313. extern int ttm_prime_handle_to_fd(struct ttm_object_file *tfile,
  314. uint32_t handle, uint32_t flags,
  315. int *prime_fd);
  316. #define ttm_prime_object_kfree(__obj, __prime) \
  317. kfree_rcu(__obj, __prime.base.rhead)
  318. /*
  319. * Extra memory required by the base object's idr storage, which is allocated
  320. * separately from the base object itself. We estimate an on-average 128 bytes
  321. * per idr.
  322. */
  323. #define TTM_OBJ_EXTRA_SIZE 128
  324. struct ttm_base_object *
  325. ttm_base_object_noref_lookup(struct ttm_object_file *tfile, uint32_t key);
  326. /**
  327. * ttm_base_object_noref_release - release a base object pointer looked up
  328. * without reference
  329. *
  330. * Releases a base object pointer looked up with ttm_base_object_noref_lookup().
  331. */
  332. static inline void ttm_base_object_noref_release(void)
  333. {
  334. __acquire(RCU);
  335. rcu_read_unlock();
  336. }
  337. #endif