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 37 #ifndef _TTM_OBJECT_H_ 38 #define _TTM_OBJECT_H_ 39 40 #include <linux/list.h> 41 #include <drm/drm_hashtab.h> 42 #include <linux/kref.h> 43 #include <linux/rcupdate.h> 44 #include <linux/dma-buf.h> 45 #include <drm/ttm/ttm_memory.h> 46 47 /** 48 * enum ttm_ref_type 49 * 50 * Describes what type of reference a ref object holds. 51 * 52 * TTM_REF_USAGE is a simple refcount on a base object. 53 * 54 * TTM_REF_SYNCCPU_READ is a SYNCCPU_READ reference on a 55 * buffer object. 56 * 57 * TTM_REF_SYNCCPU_WRITE is a SYNCCPU_WRITE reference on a 58 * buffer object. 59 * 60 */ 61 62 enum ttm_ref_type { 63 TTM_REF_USAGE, 64 TTM_REF_SYNCCPU_READ, 65 TTM_REF_SYNCCPU_WRITE, 66 TTM_REF_NUM 67 }; 68 69 /** 70 * enum ttm_object_type 71 * 72 * One entry per ttm object type. 73 * Device-specific types should use the 74 * ttm_driver_typex types. 75 */ 76 77 enum ttm_object_type { 78 ttm_fence_type, 79 ttm_buffer_type, 80 ttm_lock_type, 81 ttm_prime_type, 82 ttm_driver_type0 = 256, 83 ttm_driver_type1, 84 ttm_driver_type2, 85 ttm_driver_type3, 86 ttm_driver_type4, 87 ttm_driver_type5 88 }; 89 90 struct ttm_object_file; 91 struct ttm_object_device; 92 93 /** 94 * struct ttm_base_object 95 * 96 * @hash: hash entry for the per-device object hash. 97 * @type: derived type this object is base class for. 98 * @shareable: Other ttm_object_files can access this object. 99 * 100 * @tfile: Pointer to ttm_object_file of the creator. 101 * NULL if the object was not created by a user request. 102 * (kernel object). 103 * 104 * @refcount: Number of references to this object, not 105 * including the hash entry. A reference to a base object can 106 * only be held by a ref object. 107 * 108 * @refcount_release: A function to be called when there are 109 * no more references to this object. This function should 110 * destroy the object (or make sure destruction eventually happens), 111 * and when it is called, the object has 112 * already been taken out of the per-device hash. The parameter 113 * "base" should be set to NULL by the function. 114 * 115 * @ref_obj_release: A function to be called when a reference object 116 * with another ttm_ref_type than TTM_REF_USAGE is deleted. 117 * This function may, for example, release a lock held by a user-space 118 * process. 119 * 120 * This struct is intended to be used as a base struct for objects that 121 * are visible to user-space. It provides a global name, race-safe 122 * access and refcounting, minimal access contol and hooks for unref actions. 123 */ 124 125 struct ttm_base_object { 126 struct rcu_head rhead; 127 struct ttm_object_file *tfile; 128 struct kref refcount; 129 void (*refcount_release) (struct ttm_base_object **base); 130 void (*ref_obj_release) (struct ttm_base_object *base, 131 enum ttm_ref_type ref_type); 132 u32 handle; 133 enum ttm_object_type object_type; 134 u32 shareable; 135 }; 136 137 138 /** 139 * struct ttm_prime_object - Modified base object that is prime-aware 140 * 141 * @base: struct ttm_base_object that we derive from 142 * @mutex: Mutex protecting the @dma_buf member. 143 * @size: Size of the dma_buf associated with this object 144 * @real_type: Type of the underlying object. Needed since we're setting 145 * the value of @base::object_type to ttm_prime_type 146 * @dma_buf: Non ref-coutned pointer to a struct dma_buf created from this 147 * object. 148 * @refcount_release: The underlying object's release method. Needed since 149 * we set @base::refcount_release to our own release method. 150 */ 151 152 struct ttm_prime_object { 153 struct ttm_base_object base; 154 struct mutex mutex; 155 size_t size; 156 enum ttm_object_type real_type; 157 struct dma_buf *dma_buf; 158 void (*refcount_release) (struct ttm_base_object **); 159 }; 160 161 /** 162 * ttm_base_object_init 163 * 164 * @tfile: Pointer to a struct ttm_object_file. 165 * @base: The struct ttm_base_object to initialize. 166 * @shareable: This object is shareable with other applcations. 167 * (different @tfile pointers.) 168 * @type: The object type. 169 * @refcount_release: See the struct ttm_base_object description. 170 * @ref_obj_release: See the struct ttm_base_object description. 171 * 172 * Initializes a struct ttm_base_object. 173 */ 174 175 extern int ttm_base_object_init(struct ttm_object_file *tfile, 176 struct ttm_base_object *base, 177 bool shareable, 178 enum ttm_object_type type, 179 void (*refcount_release) (struct ttm_base_object 180 **), 181 void (*ref_obj_release) (struct ttm_base_object 182 *, 183 enum ttm_ref_type 184 ref_type)); 185 186 /** 187 * ttm_base_object_lookup 188 * 189 * @tfile: Pointer to a struct ttm_object_file. 190 * @key: Hash key 191 * 192 * Looks up a struct ttm_base_object with the key @key. 193 */ 194 195 extern struct ttm_base_object *ttm_base_object_lookup(struct ttm_object_file 196 *tfile, uint32_t key); 197 198 /** 199 * ttm_base_object_lookup_for_ref 200 * 201 * @tdev: Pointer to a struct ttm_object_device. 202 * @key: Hash key 203 * 204 * Looks up a struct ttm_base_object with the key @key. 205 * This function should only be used when the struct tfile associated with the 206 * caller doesn't yet have a reference to the base object. 207 */ 208 209 extern struct ttm_base_object * 210 ttm_base_object_lookup_for_ref(struct ttm_object_device *tdev, uint32_t key); 211 212 /** 213 * ttm_base_object_unref 214 * 215 * @p_base: Pointer to a pointer referencing a struct ttm_base_object. 216 * 217 * Decrements the base object refcount and clears the pointer pointed to by 218 * p_base. 219 */ 220 221 extern void ttm_base_object_unref(struct ttm_base_object **p_base); 222 223 /** 224 * ttm_ref_object_add. 225 * 226 * @tfile: A struct ttm_object_file representing the application owning the 227 * ref_object. 228 * @base: The base object to reference. 229 * @ref_type: The type of reference. 230 * @existed: Upon completion, indicates that an identical reference object 231 * already existed, and the refcount was upped on that object instead. 232 * @require_existed: Fail with -EPERM if an identical ref object didn't 233 * already exist. 234 * 235 * Checks that the base object is shareable and adds a ref object to it. 236 * 237 * Adding a ref object to a base object is basically like referencing the 238 * base object, but a user-space application holds the reference. When the 239 * file corresponding to @tfile is closed, all its reference objects are 240 * deleted. A reference object can have different types depending on what 241 * it's intended for. It can be refcounting to prevent object destruction, 242 * When user-space takes a lock, it can add a ref object to that lock to 243 * make sure the lock is released if the application dies. A ref object 244 * will hold a single reference on a base object. 245 */ 246 extern int ttm_ref_object_add(struct ttm_object_file *tfile, 247 struct ttm_base_object *base, 248 enum ttm_ref_type ref_type, bool *existed, 249 bool require_existed); 250 251 extern bool ttm_ref_object_exists(struct ttm_object_file *tfile, 252 struct ttm_base_object *base); 253 254 /** 255 * ttm_ref_object_base_unref 256 * 257 * @key: Key representing the base object. 258 * @ref_type: Ref type of the ref object to be dereferenced. 259 * 260 * Unreference a ref object with type @ref_type 261 * on the base object identified by @key. If there are no duplicate 262 * references, the ref object will be destroyed and the base object 263 * will be unreferenced. 264 */ 265 extern int ttm_ref_object_base_unref(struct ttm_object_file *tfile, 266 unsigned long key, 267 enum ttm_ref_type ref_type); 268 269 /** 270 * ttm_object_file_init - initialize a struct ttm_object file 271 * 272 * @tdev: A struct ttm_object device this file is initialized on. 273 * @hash_order: Order of the hash table used to hold the reference objects. 274 * 275 * This is typically called by the file_ops::open function. 276 */ 277 278 extern struct ttm_object_file *ttm_object_file_init(struct ttm_object_device 279 *tdev, 280 unsigned int hash_order); 281 282 /** 283 * ttm_object_file_release - release data held by a ttm_object_file 284 * 285 * @p_tfile: Pointer to pointer to the ttm_object_file object to release. 286 * *p_tfile will be set to NULL by this function. 287 * 288 * Releases all data associated by a ttm_object_file. 289 * Typically called from file_ops::release. The caller must 290 * ensure that there are no concurrent users of tfile. 291 */ 292 293 extern void ttm_object_file_release(struct ttm_object_file **p_tfile); 294 295 /** 296 * ttm_object device init - initialize a struct ttm_object_device 297 * 298 * @mem_glob: struct ttm_mem_global for memory accounting. 299 * @hash_order: Order of hash table used to hash the base objects. 300 * @ops: DMA buf ops for prime objects of this device. 301 * 302 * This function is typically called on device initialization to prepare 303 * data structures needed for ttm base and ref objects. 304 */ 305 306 extern struct ttm_object_device * 307 ttm_object_device_init(struct ttm_mem_global *mem_glob, 308 unsigned int hash_order, 309 const struct dma_buf_ops *ops); 310 311 /** 312 * ttm_object_device_release - release data held by a ttm_object_device 313 * 314 * @p_tdev: Pointer to pointer to the ttm_object_device object to release. 315 * *p_tdev will be set to NULL by this function. 316 * 317 * Releases all data associated by a ttm_object_device. 318 * Typically called from driver::unload before the destruction of the 319 * device private data structure. 320 */ 321 322 extern void ttm_object_device_release(struct ttm_object_device **p_tdev); 323 324 #define ttm_base_object_kfree(__object, __base)\ 325 kfree_rcu(__object, __base.rhead) 326 327 extern int ttm_prime_object_init(struct ttm_object_file *tfile, 328 size_t size, 329 struct ttm_prime_object *prime, 330 bool shareable, 331 enum ttm_object_type type, 332 void (*refcount_release) 333 (struct ttm_base_object **), 334 void (*ref_obj_release) 335 (struct ttm_base_object *, 336 enum ttm_ref_type ref_type)); 337 338 static inline enum ttm_object_type 339 ttm_base_object_type(struct ttm_base_object *base) 340 { 341 return (base->object_type == ttm_prime_type) ? 342 container_of(base, struct ttm_prime_object, base)->real_type : 343 base->object_type; 344 } 345 extern int ttm_prime_fd_to_handle(struct ttm_object_file *tfile, 346 int fd, u32 *handle); 347 extern int ttm_prime_handle_to_fd(struct ttm_object_file *tfile, 348 uint32_t handle, uint32_t flags, 349 int *prime_fd); 350 351 #define ttm_prime_object_kfree(__obj, __prime) \ 352 kfree_rcu(__obj, __prime.base.rhead) 353 354 /* 355 * Extra memory required by the base object's idr storage, which is allocated 356 * separately from the base object itself. We estimate an on-average 128 bytes 357 * per idr. 358 */ 359 #define TTM_OBJ_EXTRA_SIZE 128 360 361 struct ttm_base_object * 362 ttm_base_object_noref_lookup(struct ttm_object_file *tfile, uint32_t key); 363 364 /** 365 * ttm_base_object_noref_release - release a base object pointer looked up 366 * without reference 367 * 368 * Releases a base object pointer looked up with ttm_base_object_noref_lookup(). 369 */ 370 static inline void ttm_base_object_noref_release(void) 371 { 372 __acquire(RCU); 373 rcu_read_unlock(); 374 } 375 #endif 376