1 | /* |
2 | * Copyright (c) 2000-2016 Apple Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | /* |
29 | Copyright (c) 1998 Apple Computer, Inc. All rights reserved. |
30 | HISTORY |
31 | 1998-10-30 Godfrey van der Linden(gvdl) |
32 | Created |
33 | */ |
34 | #ifndef _LIBKERN_OSOBJECT_H |
35 | #define _LIBKERN_OSOBJECT_H |
36 | |
37 | #include <libkern/c++/OSMetaClass.h> |
38 | |
39 | #if defined(__clang__) |
40 | #pragma clang diagnostic ignored "-Woverloaded-virtual" |
41 | #endif |
42 | |
43 | class OSSymbol; |
44 | class OSString; |
45 | |
46 | |
47 | /*! |
48 | * @header |
49 | * |
50 | * @abstract |
51 | * This header declares the OSObject class, |
52 | * which is the concrete root of the Libkern C++ class hierarchy. |
53 | */ |
54 | |
55 | |
56 | /*! |
57 | * @class OSObject |
58 | * |
59 | * @abstract |
60 | * OSObject is the concrete root class |
61 | * of the Libkern and I/O Kit C++ class hierarchy. |
62 | * |
63 | * @discussion |
64 | * OSObject defines the minimal functionality |
65 | * required of Libkern and I/O Kit C++ classes: |
66 | * tie-in to the run-time type information facility, |
67 | * the dynamic allocation/initialization paradigm, |
68 | * and reference counting. |
69 | * While kernel extensions are free to use their own C++ classes internally, |
70 | * any interaction they have with Libkern or the I/O Kit will require |
71 | * classes ultimately derived from OSObject. |
72 | * |
73 | * <b>Run-Time Type Information</b> |
74 | * |
75 | * OSObject is derived from the abstract root class |
76 | * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link, |
77 | * which declares (and defines many of) the primitives |
78 | * on which the run-time type information facility is based. |
79 | * A parallel inheritance hierarchy of metaclass objects |
80 | * provides run-time introspection, including access to class names, |
81 | * inheritance, and safe type-casting. |
82 | * See @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link |
83 | * for more information. |
84 | * |
85 | * <b>Dynamic Allocation/Initialization</b> |
86 | * |
87 | * The kernel-resident C++ runtime does not support exceptions, |
88 | * so Libkern classes cannot use standard C++ object |
89 | * constructors and destructors, |
90 | * which use exceptions to report errors. |
91 | * To support error-handling during instance creation, then, |
92 | * OSObject separates object allocation from initialization. |
93 | * You can create a new OSObject-derived instance |
94 | * with the <code>new</code> operator, |
95 | * but this does nothing more than allocate memory |
96 | * and initialize the reference count to 1. |
97 | * Following this, you must call a designated initialization function |
98 | * and check its <code>bool</code> return value. |
99 | * If the initialization fails, |
100 | * you must immediately call |
101 | * <code>@link |
102 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
103 | * release@/link</code> |
104 | * on the instance and handle the failure in whatever way is appropriate. |
105 | * Many Libkern and I/O Kit classes define static instance-creation functions |
106 | * (beginning with the word "with") |
107 | * to make construction a one-step process for clients. |
108 | * |
109 | * <b>Reference Counting</b> |
110 | * |
111 | * OSObject provides reference counting services using the |
112 | * <code>@link |
113 | * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() |
114 | * retain@/link</code>, |
115 | * <code>@link |
116 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
117 | * release()@/link</code>, |
118 | * <code>@link |
119 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int) |
120 | * release(int freeWhen)@/link</code> |
121 | * and |
122 | *<code> @link |
123 | * //apple_ref/cpp/instm/OSObject/free/virtualvoid/() |
124 | * free@/link</code> |
125 | * functions. |
126 | * The public interface to the reference counting is |
127 | * <code>@link |
128 | * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/() |
129 | * retain@/link</code>, |
130 | * and |
131 | * <code>@link |
132 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
133 | * release@/link</code>; |
134 | * <code>@link |
135 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int) |
136 | * release(int freeWhen)@/link</code> |
137 | * is provided |
138 | * for objects that have internal retain cycles. |
139 | * |
140 | * In general, a subclass is expected to only override |
141 | * <code>@link |
142 | * //apple_ref/cpp/instm/OSObject/free/virtualvoid/() |
143 | * free@/link</code>. |
144 | * It may also choose to override |
145 | * <code>@link |
146 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int) |
147 | * release(int freeWhen)@/link</code> |
148 | * if the object has a circular retain count, as noted above. |
149 | * |
150 | * <b>Use Restrictions</b> |
151 | * |
152 | * With very few exceptions in the I/O Kit, all Libkern-based C++ |
153 | * classes, functions, and macros are <b>unsafe</b> |
154 | * to use in a primary interrupt context. |
155 | * Consult the I/O Kit documentation related to primary interrupts |
156 | * for more information. |
157 | * |
158 | * <b>Concurrency Protection</b> |
159 | * |
160 | * The basic features of OSObject are thread-safe. |
161 | * Most Libkern subclasses are not, and require locking or other protection |
162 | * if instances are shared between threads. |
163 | * I/O Kit driver objects are either designed for use within thread-safe contexts |
164 | * or designed to inherently be thread-safe. |
165 | * Always check the individual class documentation to see what |
166 | * steps are necessary for concurrent use of instances. |
167 | */ |
168 | class OSObject : public OSMetaClassBase |
169 | { |
170 | OSDeclareAbstractStructors(OSObject) |
171 | #if IOKITSTATS |
172 | friend class IOStatistics; |
173 | #endif |
174 | |
175 | private: |
176 | /* Not to be included in headerdoc. |
177 | * |
178 | * @var retainCount Number of references held on this instance. |
179 | */ |
180 | mutable int retainCount; |
181 | |
182 | protected: |
183 | |
184 | // xx-review: seems not to be used, should we deprecate? |
185 | |
186 | /*! |
187 | * @function release |
188 | * |
189 | * @abstract |
190 | * Releases a reference to an object, |
191 | * freeing it immediately if the reference count |
192 | * drops below the specified threshold. |
193 | * |
194 | * @param freeWhen If decrementing the reference count makes it |
195 | * >= <code>freeWhen</code>, the object is immediately freed. |
196 | * |
197 | * @discussion |
198 | * If the receiver has <code>freeWhen</code> or fewer references |
199 | * after its reference count is decremented, |
200 | * it is immediately freed. |
201 | * |
202 | * This version of <code>release</code> |
203 | * can be used to break certain retain cycles in object graphs. |
204 | * In general, however, it should be avoided. |
205 | */ |
206 | virtual void release(int freeWhen) const APPLE_KEXT_OVERRIDE; |
207 | |
208 | /*! |
209 | * @function taggedRelease |
210 | * |
211 | * @abstract |
212 | * Releases a tagged reference to an object, |
213 | * freeing it immediately if the reference count |
214 | * drops below the specified threshold. |
215 | * |
216 | * @param tag Used for tracking collection references. |
217 | * @param freeWhen If decrementing the reference count makes it |
218 | * >= <code>freeWhen</code>, the object is immediately freed. |
219 | * |
220 | * @discussion |
221 | * Kernel extensions should not use this function. |
222 | * It is for use by OSCollection and subclasses to track |
223 | * inclusion in collections. |
224 | * |
225 | * If the receiver has <code>freeWhen</code> or fewer references |
226 | * after its reference count is decremented, |
227 | * it is immediately freed. |
228 | * |
229 | * This version of <code>release</code> |
230 | * can be used to break certain retain cycles in object graphs. |
231 | * In general, however, it should be avoided. |
232 | */ |
233 | virtual void taggedRelease(const void * tag, const int freeWhen) const APPLE_KEXT_OVERRIDE; |
234 | |
235 | |
236 | /*! |
237 | * @function init |
238 | * |
239 | * @abstract |
240 | * Initializes a newly-allocated object. |
241 | * |
242 | * @result |
243 | * <code>true</code> on success, <code>false</code> on failure. |
244 | * |
245 | * @discussion |
246 | * Classes derived from OSObject must override the primary init method |
247 | * of their parent. |
248 | * In general most implementations call |
249 | * <code><i>super</i>::init()</code> |
250 | * before doing local initialisation. |
251 | * If the superclass call fails then return <code>false</code> immediately. |
252 | * If the subclass encounters a failure then it should return <code>false</code>. |
253 | */ |
254 | virtual bool init(); |
255 | |
256 | |
257 | /*! |
258 | * @function free |
259 | * |
260 | * @abstract |
261 | * Deallocates/releases resources held by the object. |
262 | * |
263 | * @discussion |
264 | * Classes derived from OSObject should override this function |
265 | * to deallocate or release all dynamic resources held by the instance, |
266 | * then call the superclass's implementation. |
267 | * |
268 | * <b>Caution:</b> |
269 | * <ol> |
270 | * <li>You can not assume that you have completed initialization |
271 | * before <code>free</code> is called, |
272 | * so be very careful in your implementation.</li> |
273 | * <li>OSObject's implementation performs the C++ <code>delete</code> |
274 | * of the instance, so be sure that you call the superclass |
275 | * implementation <i>last</i> in your implementation.</li> |
276 | * <li><code>free</code> must not fail; |
277 | * all resources must be deallocated or released on completion.</li> |
278 | * </ol> |
279 | */ |
280 | virtual void free(); |
281 | |
282 | |
283 | /*! |
284 | * @function operator delete |
285 | * |
286 | * @abstract |
287 | * Frees the memory of the object itself. |
288 | * |
289 | * @param mem A pointer to the object's memory. |
290 | * @param size The size of the object's block of memory. |
291 | * |
292 | * @discussion |
293 | * Never use <code>delete</code> on objects derived from OSObject; |
294 | * use |
295 | * <code>@link |
296 | * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() |
297 | * release@/link</code> |
298 | * instead. |
299 | */ |
300 | static void operator delete(void * mem, size_t size); |
301 | |
302 | public: |
303 | |
304 | /*! |
305 | * @function operator new |
306 | * |
307 | * @abstract |
308 | * Allocates memory for an instance of the class. |
309 | * |
310 | * @param size The number of bytes to allocate |
311 | * |
312 | * @result |
313 | * A pointer to block of memory if available, <code>NULL</code> otherwise. |
314 | */ |
315 | static void * operator new(size_t size); |
316 | |
317 | |
318 | /*! |
319 | * @function getRetainCount |
320 | * |
321 | * @abstract |
322 | * Returns the reference count of the object. |
323 | * |
324 | * @result |
325 | * The reference count of the object. |
326 | */ |
327 | virtual int getRetainCount() const APPLE_KEXT_OVERRIDE; |
328 | |
329 | |
330 | /*! |
331 | * @function retain |
332 | * |
333 | * @abstract |
334 | * Retains a reference to the object. |
335 | * |
336 | * @discussion |
337 | * This function increments the reference count of the receiver by 1. |
338 | * If you need to maintain a reference to an object |
339 | * outside the context in which you received it, |
340 | * you should always retain it immediately. |
341 | */ |
342 | virtual void retain() const APPLE_KEXT_OVERRIDE; |
343 | |
344 | |
345 | /*! |
346 | * @function release |
347 | * |
348 | * @abstract |
349 | * Releases a reference to the object, |
350 | * freeing it immediately if the reference count drops to zero. |
351 | * |
352 | * @discussion |
353 | * This function decrements the reference count of the receiver by 1. |
354 | * If the reference count drops to zero, |
355 | * the object is immediately freed using |
356 | * <code>@link |
357 | * //apple_ref/cpp/instm/OSObject/free/virtualvoid/() |
358 | * free@/link</code>. |
359 | */ |
360 | virtual void release() const APPLE_KEXT_OVERRIDE; |
361 | |
362 | |
363 | /*! |
364 | * @function taggedRetain |
365 | * |
366 | * @abstract |
367 | * Retains a reference to the object with an optional |
368 | * tag used for reference-tracking. |
369 | * |
370 | * @param tag Used for tracking collection references. |
371 | * |
372 | * @discussion |
373 | * Kernel extensions should not use this function. |
374 | * It is for use by OSCollection and subclasses to track |
375 | * inclusion in collections. |
376 | * |
377 | * If you need to maintain a reference to an object |
378 | * outside the context in which you received it, |
379 | * you should always retain it immediately. |
380 | */ |
381 | virtual void taggedRetain(const void * tag = 0) const APPLE_KEXT_OVERRIDE; |
382 | |
383 | |
384 | /*! |
385 | * @function taggedRelease |
386 | * |
387 | * @abstract |
388 | * Releases a tagged reference to an object, |
389 | * freeing it immediately if the reference count |
390 | * drops to zero. |
391 | * |
392 | * @param tag Used for tracking collection references. |
393 | * |
394 | * @discussion |
395 | * Kernel extensions should not use this function. |
396 | * It is for use by OSCollection and subclasses to track |
397 | * inclusion in collections. |
398 | */ |
399 | virtual void taggedRelease(const void * tag = 0) const APPLE_KEXT_OVERRIDE; |
400 | // xx-review: used to say, "Remove a reference on this object with this tag, if an attempt is made to remove a reference that isn't associated with this tag the kernel will panic immediately", but I don't see that in the implementation |
401 | |
402 | |
403 | /*! |
404 | * @function serialize |
405 | * |
406 | * @abstract |
407 | * Overridden by subclasses to archive the receiver into the provided |
408 | * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object. |
409 | * |
410 | * @param serializer The OSSerialize object. |
411 | * |
412 | * @result |
413 | * <code>true</code> if serialization succeeds, <code>false</code> if not. |
414 | * |
415 | * @discussion |
416 | * OSObject's implementation writes a string indicating that |
417 | * the class of the object receiving the function call |
418 | * is not serializable. |
419 | * Subclasses that can meaningfully encode themselves |
420 | * in I/O Kit-style property list XML can override this function to do so. |
421 | * See |
422 | * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link |
423 | * for more information. |
424 | */ |
425 | virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE; |
426 | |
427 | #ifdef XNU_KERNEL_PRIVATE |
428 | #if IOTRACKING |
429 | void trackingAccumSize(size_t size); |
430 | #endif |
431 | #endif |
432 | |
433 | // Unused Padding |
434 | OSMetaClassDeclareReservedUnused(OSObject, 0); |
435 | OSMetaClassDeclareReservedUnused(OSObject, 1); |
436 | OSMetaClassDeclareReservedUnused(OSObject, 2); |
437 | OSMetaClassDeclareReservedUnused(OSObject, 3); |
438 | OSMetaClassDeclareReservedUnused(OSObject, 4); |
439 | OSMetaClassDeclareReservedUnused(OSObject, 5); |
440 | OSMetaClassDeclareReservedUnused(OSObject, 6); |
441 | OSMetaClassDeclareReservedUnused(OSObject, 7); |
442 | OSMetaClassDeclareReservedUnused(OSObject, 8); |
443 | OSMetaClassDeclareReservedUnused(OSObject, 9); |
444 | OSMetaClassDeclareReservedUnused(OSObject, 10); |
445 | OSMetaClassDeclareReservedUnused(OSObject, 11); |
446 | OSMetaClassDeclareReservedUnused(OSObject, 12); |
447 | OSMetaClassDeclareReservedUnused(OSObject, 13); |
448 | OSMetaClassDeclareReservedUnused(OSObject, 14); |
449 | OSMetaClassDeclareReservedUnused(OSObject, 15); |
450 | |
451 | }; |
452 | |
453 | #endif /* !_LIBKERN_OSOBJECT_H */ |
454 | |