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