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 <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 62enum 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 77enum 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 90struct ttm_object_file; 91struct 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 125struct ttm_base_object { 126 struct rcu_head rhead; 127 struct drm_hash_item hash; 128 enum ttm_object_type object_type; 129 bool shareable; 130 struct ttm_object_file *tfile; 131 struct kref refcount; 132 void (*refcount_release) (struct ttm_base_object **base); 133 void (*ref_obj_release) (struct ttm_base_object *base, 134 enum ttm_ref_type ref_type); 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 152struct 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 175extern 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 195extern 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 209extern struct ttm_base_object * 210ttm_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 221extern 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 * 233 * Checks that the base object is shareable and adds a ref object to it. 234 * 235 * Adding a ref object to a base object is basically like referencing the 236 * base object, but a user-space application holds the reference. When the 237 * file corresponding to @tfile is closed, all its reference objects are 238 * deleted. A reference object can have different types depending on what 239 * it's intended for. It can be refcounting to prevent object destruction, 240 * When user-space takes a lock, it can add a ref object to that lock to 241 * make sure the lock is released if the application dies. A ref object 242 * will hold a single reference on a base object. 243 */ 244extern int ttm_ref_object_add(struct ttm_object_file *tfile, 245 struct ttm_base_object *base, 246 enum ttm_ref_type ref_type, bool *existed); 247 248extern bool ttm_ref_object_exists(struct ttm_object_file *tfile, 249 struct ttm_base_object *base); 250 251/** 252 * ttm_ref_object_base_unref 253 * 254 * @key: Key representing the base object. 255 * @ref_type: Ref type of the ref object to be dereferenced. 256 * 257 * Unreference a ref object with type @ref_type 258 * on the base object identified by @key. If there are no duplicate 259 * references, the ref object will be destroyed and the base object 260 * will be unreferenced. 261 */ 262extern int ttm_ref_object_base_unref(struct ttm_object_file *tfile, 263 unsigned long key, 264 enum ttm_ref_type ref_type); 265 266/** 267 * ttm_object_file_init - initialize a struct ttm_object file 268 * 269 * @tdev: A struct ttm_object device this file is initialized on. 270 * @hash_order: Order of the hash table used to hold the reference objects. 271 * 272 * This is typically called by the file_ops::open function. 273 */ 274 275extern struct ttm_object_file *ttm_object_file_init(struct ttm_object_device 276 *tdev, 277 unsigned int hash_order); 278 279/** 280 * ttm_object_file_release - release data held by a ttm_object_file 281 * 282 * @p_tfile: Pointer to pointer to the ttm_object_file object to release. 283 * *p_tfile will be set to NULL by this function. 284 * 285 * Releases all data associated by a ttm_object_file. 286 * Typically called from file_ops::release. The caller must 287 * ensure that there are no concurrent users of tfile. 288 */ 289 290extern void ttm_object_file_release(struct ttm_object_file **p_tfile); 291 292/** 293 * ttm_object device init - initialize a struct ttm_object_device 294 * 295 * @mem_glob: struct ttm_mem_global for memory accounting. 296 * @hash_order: Order of hash table used to hash the base objects. 297 * @ops: DMA buf ops for prime objects of this device. 298 * 299 * This function is typically called on device initialization to prepare 300 * data structures needed for ttm base and ref objects. 301 */ 302 303extern struct ttm_object_device * 304ttm_object_device_init(struct ttm_mem_global *mem_glob, 305 unsigned int hash_order, 306 const struct dma_buf_ops *ops); 307 308/** 309 * ttm_object_device_release - release data held by a ttm_object_device 310 * 311 * @p_tdev: Pointer to pointer to the ttm_object_device object to release. 312 * *p_tdev will be set to NULL by this function. 313 * 314 * Releases all data associated by a ttm_object_device. 315 * Typically called from driver::unload before the destruction of the 316 * device private data structure. 317 */ 318 319extern void ttm_object_device_release(struct ttm_object_device **p_tdev); 320 321#define ttm_base_object_kfree(__object, __base)\ 322 kfree_rcu(__object, __base.rhead) 323 324extern int ttm_prime_object_init(struct ttm_object_file *tfile, 325 size_t size, 326 struct ttm_prime_object *prime, 327 bool shareable, 328 enum ttm_object_type type, 329 void (*refcount_release) 330 (struct ttm_base_object **), 331 void (*ref_obj_release) 332 (struct ttm_base_object *, 333 enum ttm_ref_type ref_type)); 334 335static inline enum ttm_object_type 336ttm_base_object_type(struct ttm_base_object *base) 337{ 338 return (base->object_type == ttm_prime_type) ? 339 container_of(base, struct ttm_prime_object, base)->real_type : 340 base->object_type; 341} 342extern int ttm_prime_fd_to_handle(struct ttm_object_file *tfile, 343 int fd, u32 *handle); 344extern int ttm_prime_handle_to_fd(struct ttm_object_file *tfile, 345 uint32_t handle, uint32_t flags, 346 int *prime_fd); 347 348#define ttm_prime_object_kfree(__obj, __prime) \ 349 kfree_rcu(__obj, __prime.base.rhead) 350#endif 351