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