Commit | Line | Data |
---|---|---|
88071539 TH |
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> | |
a1ce3928 | 41 | #include <drm/drm_hashtab.h> |
88071539 | 42 | #include <linux/kref.h> |
cdad0521 | 43 | #include <linux/rcupdate.h> |
88071539 TH |
44 | #include <ttm/ttm_memory.h> |
45 | ||
46 | /** | |
47 | * enum ttm_ref_type | |
48 | * | |
49 | * Describes what type of reference a ref object holds. | |
50 | * | |
51 | * TTM_REF_USAGE is a simple refcount on a base object. | |
52 | * | |
53 | * TTM_REF_SYNCCPU_READ is a SYNCCPU_READ reference on a | |
54 | * buffer object. | |
55 | * | |
56 | * TTM_REF_SYNCCPU_WRITE is a SYNCCPU_WRITE reference on a | |
57 | * buffer object. | |
58 | * | |
59 | */ | |
60 | ||
61 | enum ttm_ref_type { | |
62 | TTM_REF_USAGE, | |
63 | TTM_REF_SYNCCPU_READ, | |
64 | TTM_REF_SYNCCPU_WRITE, | |
65 | TTM_REF_NUM | |
66 | }; | |
67 | ||
68 | /** | |
69 | * enum ttm_object_type | |
70 | * | |
71 | * One entry per ttm object type. | |
72 | * Device-specific types should use the | |
73 | * ttm_driver_typex types. | |
74 | */ | |
75 | ||
76 | enum ttm_object_type { | |
77 | ttm_fence_type, | |
78 | ttm_buffer_type, | |
79 | ttm_lock_type, | |
80 | ttm_driver_type0 = 256, | |
be1cb868 JB |
81 | ttm_driver_type1, |
82 | ttm_driver_type2, | |
83 | ttm_driver_type3, | |
84 | ttm_driver_type4, | |
85 | ttm_driver_type5 | |
88071539 TH |
86 | }; |
87 | ||
88 | struct ttm_object_file; | |
89 | struct ttm_object_device; | |
90 | ||
91 | /** | |
92 | * struct ttm_base_object | |
93 | * | |
94 | * @hash: hash entry for the per-device object hash. | |
95 | * @type: derived type this object is base class for. | |
96 | * @shareable: Other ttm_object_files can access this object. | |
97 | * | |
98 | * @tfile: Pointer to ttm_object_file of the creator. | |
99 | * NULL if the object was not created by a user request. | |
100 | * (kernel object). | |
101 | * | |
102 | * @refcount: Number of references to this object, not | |
103 | * including the hash entry. A reference to a base object can | |
104 | * only be held by a ref object. | |
105 | * | |
106 | * @refcount_release: A function to be called when there are | |
107 | * no more references to this object. This function should | |
108 | * destroy the object (or make sure destruction eventually happens), | |
109 | * and when it is called, the object has | |
110 | * already been taken out of the per-device hash. The parameter | |
111 | * "base" should be set to NULL by the function. | |
112 | * | |
113 | * @ref_obj_release: A function to be called when a reference object | |
114 | * with another ttm_ref_type than TTM_REF_USAGE is deleted. | |
0d74f86f | 115 | * This function may, for example, release a lock held by a user-space |
88071539 TH |
116 | * process. |
117 | * | |
118 | * This struct is intended to be used as a base struct for objects that | |
119 | * are visible to user-space. It provides a global name, race-safe | |
120 | * access and refcounting, minimal access contol and hooks for unref actions. | |
121 | */ | |
122 | ||
123 | struct ttm_base_object { | |
cdad0521 | 124 | struct rcu_head rhead; |
88071539 TH |
125 | struct drm_hash_item hash; |
126 | enum ttm_object_type object_type; | |
127 | bool shareable; | |
128 | struct ttm_object_file *tfile; | |
129 | struct kref refcount; | |
130 | void (*refcount_release) (struct ttm_base_object **base); | |
131 | void (*ref_obj_release) (struct ttm_base_object *base, | |
132 | enum ttm_ref_type ref_type); | |
133 | }; | |
134 | ||
135 | /** | |
136 | * ttm_base_object_init | |
137 | * | |
138 | * @tfile: Pointer to a struct ttm_object_file. | |
139 | * @base: The struct ttm_base_object to initialize. | |
140 | * @shareable: This object is shareable with other applcations. | |
141 | * (different @tfile pointers.) | |
142 | * @type: The object type. | |
143 | * @refcount_release: See the struct ttm_base_object description. | |
144 | * @ref_obj_release: See the struct ttm_base_object description. | |
145 | * | |
146 | * Initializes a struct ttm_base_object. | |
147 | */ | |
148 | ||
149 | extern int ttm_base_object_init(struct ttm_object_file *tfile, | |
150 | struct ttm_base_object *base, | |
151 | bool shareable, | |
152 | enum ttm_object_type type, | |
153 | void (*refcount_release) (struct ttm_base_object | |
154 | **), | |
155 | void (*ref_obj_release) (struct ttm_base_object | |
156 | *, | |
157 | enum ttm_ref_type | |
158 | ref_type)); | |
159 | ||
160 | /** | |
161 | * ttm_base_object_lookup | |
162 | * | |
163 | * @tfile: Pointer to a struct ttm_object_file. | |
164 | * @key: Hash key | |
165 | * | |
166 | * Looks up a struct ttm_base_object with the key @key. | |
167 | * Also verifies that the object is visible to the application, by | |
168 | * comparing the @tfile argument and checking the object shareable flag. | |
169 | */ | |
170 | ||
171 | extern struct ttm_base_object *ttm_base_object_lookup(struct ttm_object_file | |
172 | *tfile, uint32_t key); | |
173 | ||
174 | /** | |
175 | * ttm_base_object_unref | |
176 | * | |
0d74f86f | 177 | * @p_base: Pointer to a pointer referencing a struct ttm_base_object. |
88071539 TH |
178 | * |
179 | * Decrements the base object refcount and clears the pointer pointed to by | |
180 | * p_base. | |
181 | */ | |
182 | ||
183 | extern void ttm_base_object_unref(struct ttm_base_object **p_base); | |
184 | ||
185 | /** | |
186 | * ttm_ref_object_add. | |
187 | * | |
188 | * @tfile: A struct ttm_object_file representing the application owning the | |
189 | * ref_object. | |
190 | * @base: The base object to reference. | |
191 | * @ref_type: The type of reference. | |
192 | * @existed: Upon completion, indicates that an identical reference object | |
193 | * already existed, and the refcount was upped on that object instead. | |
194 | * | |
195 | * Adding a ref object to a base object is basically like referencing the | |
196 | * base object, but a user-space application holds the reference. When the | |
197 | * file corresponding to @tfile is closed, all its reference objects are | |
198 | * deleted. A reference object can have different types depending on what | |
199 | * it's intended for. It can be refcounting to prevent object destruction, | |
200 | * When user-space takes a lock, it can add a ref object to that lock to | |
201 | * make sure the lock is released if the application dies. A ref object | |
202 | * will hold a single reference on a base object. | |
203 | */ | |
204 | extern int ttm_ref_object_add(struct ttm_object_file *tfile, | |
205 | struct ttm_base_object *base, | |
206 | enum ttm_ref_type ref_type, bool *existed); | |
207 | /** | |
208 | * ttm_ref_object_base_unref | |
209 | * | |
210 | * @key: Key representing the base object. | |
211 | * @ref_type: Ref type of the ref object to be dereferenced. | |
212 | * | |
213 | * Unreference a ref object with type @ref_type | |
214 | * on the base object identified by @key. If there are no duplicate | |
215 | * references, the ref object will be destroyed and the base object | |
216 | * will be unreferenced. | |
217 | */ | |
218 | extern int ttm_ref_object_base_unref(struct ttm_object_file *tfile, | |
219 | unsigned long key, | |
220 | enum ttm_ref_type ref_type); | |
221 | ||
222 | /** | |
223 | * ttm_object_file_init - initialize a struct ttm_object file | |
224 | * | |
225 | * @tdev: A struct ttm_object device this file is initialized on. | |
226 | * @hash_order: Order of the hash table used to hold the reference objects. | |
227 | * | |
228 | * This is typically called by the file_ops::open function. | |
229 | */ | |
230 | ||
231 | extern struct ttm_object_file *ttm_object_file_init(struct ttm_object_device | |
232 | *tdev, | |
233 | unsigned int hash_order); | |
234 | ||
235 | /** | |
236 | * ttm_object_file_release - release data held by a ttm_object_file | |
237 | * | |
238 | * @p_tfile: Pointer to pointer to the ttm_object_file object to release. | |
239 | * *p_tfile will be set to NULL by this function. | |
240 | * | |
241 | * Releases all data associated by a ttm_object_file. | |
242 | * Typically called from file_ops::release. The caller must | |
243 | * ensure that there are no concurrent users of tfile. | |
244 | */ | |
245 | ||
246 | extern void ttm_object_file_release(struct ttm_object_file **p_tfile); | |
247 | ||
248 | /** | |
249 | * ttm_object device init - initialize a struct ttm_object_device | |
250 | * | |
251 | * @hash_order: Order of hash table used to hash the base objects. | |
252 | * | |
253 | * This function is typically called on device initialization to prepare | |
254 | * data structures needed for ttm base and ref objects. | |
255 | */ | |
256 | ||
257 | extern struct ttm_object_device *ttm_object_device_init | |
258 | (struct ttm_mem_global *mem_glob, unsigned int hash_order); | |
259 | ||
260 | /** | |
261 | * ttm_object_device_release - release data held by a ttm_object_device | |
262 | * | |
263 | * @p_tdev: Pointer to pointer to the ttm_object_device object to release. | |
264 | * *p_tdev will be set to NULL by this function. | |
265 | * | |
266 | * Releases all data associated by a ttm_object_device. | |
267 | * Typically called from driver::unload before the destruction of the | |
268 | * device private data structure. | |
269 | */ | |
270 | ||
271 | extern void ttm_object_device_release(struct ttm_object_device **p_tdev); | |
272 | ||
cdad0521 TH |
273 | #define ttm_base_object_kfree(__object, __base)\ |
274 | kfree_rcu(__object, __base.rhead) | |
88071539 | 275 | #endif |