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