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#ifndef _LIBKERN_OSMETACLASS_H
29#define _LIBKERN_OSMETACLASS_H
30
31#include <sys/types.h>
32
33#include <libkern/OSReturn.h>
34#include <kern/debug.h>
35#include <ptrauth.h>
36#ifdef KERNEL_PRIVATE
37#include <kern/zalloc.h>
38#include <kern/kalloc.h>
39#endif /* KERNEL_PRIVATE */
40
41/*
42 * LIBKERN_ macros below can be used to describe the ownership semantics
43 * of functions handling subclasses of OSObject.
44 * The attributes propagate with inheritance, but can be overriden.
45 * New versions of the Clang Static Analyzer can use this knowledge to
46 * check the code for leaks or uses-after-free.
47 */
48
49/*
50 * By default, methods returning OSObjects are assumed to have the following
51 * owneship semantics:
52 * - Methods which start with "get" are "Get" and which are not returning
53 * a subclass of OSIterator are assumed to be getters.
54 * They return at "+0" and the caller is not responsible for releasing the
55 * returned object.
56 *
57 * - All other methods are assumed to return at "+1", and the caller is
58 * responsible for releasing the returned object.
59 *
60 * The semantics implied by the naming convention described above can be
61 * overriden using either LIBKERN_RETURNS_RETAINED or LIBKERN_RETURNS_NOT_RETAINED
62 * attribute applied to a function.
63 * In the former case, it stipulates that the function is returning at "+1",
64 * and in the latter case "+0".
65 *
66 * LIBKERN_RETURNS_RETAINED and LIBKERN_RETURNS_NOT_RETAINED attributes
67 * can be also applied to out parameters, in which case they specify
68 * that an out parameter is written into at +1 or +0 respectively.
69 * For out parameters of non-void functions an assumption is
70 * that an out parameter is written into iff the return value is non-zero
71 * unless the function returns a typedef to kern_return_t,
72 * in which case it is assumed to be written into on zero value
73 * (kIOReturnSuccess).
74 * This can be customized using the attributes
75 * LIBKERN_RETURNS_RETAINED_ON_ZERO and LIBKERN_RETURNS_RETAINED_ON_NONZERO.
76 */
77#if __has_attribute(os_returns_retained)
78#define LIBKERN_RETURNS_RETAINED __attribute__((os_returns_retained))
79#else
80#define LIBKERN_RETURNS_RETAINED
81#endif
82#if __has_attribute(os_returns_not_retained)
83#define LIBKERN_RETURNS_NOT_RETAINED __attribute__((os_returns_not_retained))
84#else
85#define LIBKERN_RETURNS_NOT_RETAINED
86#endif
87
88/*
89 * LIBKERN_CONSUMED attribute can be applied to parameters.
90 * It specifies that this function call would consume the reference to the
91 * annotated parameter.
92 */
93#if __has_attribute(os_consumed)
94#define LIBKERN_CONSUMED __attribute__((os_consumed))
95#else
96#define LIBKERN_CONSUMED
97#endif
98
99/*
100 * LIBKERN_CONSUMES_THIS attribute can be applied to methods.
101 * It specifies that this method call consumes a reference to "this" (e.g.
102 * by storing a reference to "this" in a passed parameter).
103 */
104#if __has_attribute(os_consumes_this)
105#define LIBKERN_CONSUMES_THIS __attribute__((os_consumes_this))
106#else
107#define LIBKERN_CONSUMES_THIS
108#endif
109
110/*
111 * LIBKERN_RETURNS_RETAINED_ON_ZERO is an attribute applicable to out
112 * parameters.
113 * It specifies that an out parameter at +1 is written into an argument iff
114 * the function returns a zero return value.
115 */
116#if __has_attribute(os_returns_retained_on_zero)
117#define LIBKERN_RETURNS_RETAINED_ON_ZERO __attribute__((os_returns_retained_on_zero))
118#else
119#define LIBKERN_RETURNS_RETAINED_ON_ZERO
120#endif
121
122/*
123 * LIBKERN_RETURNS_RETAINED_ON_NON_ZERO is an attribute applicable to out
124 * parameters.
125 * It specifies that an out parameter at +1 is written into an argument iff
126 * the function returns a non-zero return value.
127 */
128#if __has_attribute(os_returns_retained_on_non_zero)
129#define LIBKERN_RETURNS_RETAINED_ON_NONZERO __attribute__((os_returns_retained_on_non_zero))
130#else
131#define LIBKERN_RETURNS_RETAINED_ON_NONZERO
132#endif
133
134class OSMetaClass;
135class OSObject;
136class OSString;
137class OSSymbol;
138class OSDictionary;
139class OSSerialize;
140#ifdef XNU_KERNEL_PRIVATE
141class OSOrderedSet;
142class OSCollection;
143class OSKext;
144#endif /* XNU_KERNEL_PRIVATE */
145struct IORPC;
146class OSInterface
147{
148};
149
150/*!
151 * @header
152 *
153 * @abstract
154 * This header declares the OSMetaClassBase and OSMetaClass classes,
155 * which together form the basis of the Libkern and I/O Kit C++ class hierarchy
156 * and run-time type information facility.
157 */
158
159
160/*! @parseOnly */
161#define APPLE_KEXT_COMPATIBILITY
162
163#ifdef XNU_KERNEL_PRIVATE
164
165#if !XNU_TARGET_OS_OSX
166#define APPLE_KEXT_VTABLE_PADDING 0
167#else /* !XNU_TARGET_OS_OSX */
168#define APPLE_KEXT_VTABLE_PADDING 1
169#endif /* !XNU_TARGET_OS_OSX */
170
171#else /* XNU_KERNEL_PRIVATE */
172
173/* No xnu-private defines outside of xnu */
174
175#include <TargetConditionals.h>
176#if TARGET_OS_IPHONE && !TARGET_OS_SIMULATOR
177#define APPLE_KEXT_VTABLE_PADDING 0
178#else /* TARGET_OS_IPHONE && !TARGET_OS_SIMULATOR */
179#define APPLE_KEXT_VTABLE_PADDING 1
180#endif /* TARGET_OS_IPHONE && !TARGET_OS_SIMULATOR */
181
182#endif /* XNU_KERNEL_PRIVATE */
183
184#ifdef XNU_KERNEL_PRIVATE
185#if XNU_TARGET_OS_OSX && defined(__arm64__)
186#define APPLE_KEXT_ALIGN_CONTAINERS 1
187#else /* XNU_TARGET_OS_OSX && defined(__arm64__) */
188#define APPLE_KEXT_ALIGN_CONTAINERS (0 == APPLE_KEXT_VTABLE_PADDING)
189#endif /* XNU_TARGET_OS_OSX && defined(__arm64__) */
190
191#else /* XNU_KERNEL_PRIVATE */
192
193#if TARGET_OS_OSX && defined(__arm64__)
194#define APPLE_KEXT_ALIGN_CONTAINERS 1
195#else /* TARGET_OS_OSX && defined(__arm64__) */
196#define APPLE_KEXT_ALIGN_CONTAINERS (0 == APPLE_KEXT_VTABLE_PADDING)
197#endif /* TARGET_OS_OSX && defined(__arm64__) */
198
199#endif /* XNU_KERNEL_PRIVATE */
200
201#if defined(__LP64__)
202/*! @parseOnly */
203#define APPLE_KEXT_LEGACY_ABI 0
204#elif defined(__arm__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 2))
205#define APPLE_KEXT_LEGACY_ABI 0
206#else
207#define APPLE_KEXT_LEGACY_ABI 1
208#endif
209
210#if defined(__LP64__)
211/*! @parseOnly */
212#define APPLE_KEXT_COMPATIBILITY_VIRTUAL
213#else
214// private method made virtual only for binary compatibility
215#define APPLE_KEXT_COMPATIBILITY_VIRTUAL virtual
216#endif
217
218/*! @parseOnly */
219#define APPLE_KEXT_DEPRECATED __attribute__((deprecated))
220
221
222/*
223 * <rdar://problem/44872498> AppleUSBAudio builds xnu's libkern headers in user space
224 */
225#if !defined(BUILD_FOR_USERSPACE) && (__cplusplus >= 201103L)
226#define APPLE_KEXT_OVERRIDE override
227#if defined(__LP64__)
228#define APPLE_KEXT_COMPATIBILITY_OVERRIDE
229#else
230#define APPLE_KEXT_COMPATIBILITY_OVERRIDE APPLE_KEXT_OVERRIDE
231#endif
232#else
233#define APPLE_KEXT_OVERRIDE
234#define APPLE_KEXT_COMPATIBILITY_OVERRIDE
235#endif
236
237#define APPLE_KEXT_WSHADOW_PUSH _Pragma("clang diagnostic push") \
238 _Pragma("clang diagnostic ignored \"-Wunknown-warning-option\"") \
239 _Pragma("clang diagnostic ignored \"-Wshadow-field\"")
240
241#define APPLE_KEXT_WSHADOW_POP _Pragma("clang diagnostic pop")
242
243
244/*!
245 * @class OSMetaClassBase
246 *
247 * @abstract
248 * OSMetaClassBase is the abstract bootstrap class
249 * for the Libkern and I/O Kit run-time type information system.
250 *
251 * @discussion
252 * OSMetaClassBase is the abstract C++ root class
253 * underlying the entire Libkern and I/O Kit class hierarchy.
254 * It defines the run-time type information system,
255 * including dynamic class allocation and safe type-casting,
256 * as well as the abstract interface for reference counting
257 * and a few other utility functions.
258 * OSMetaClassBase is the immediate superclass of
259 * @link //apple_ref/doc/class/OSObject OSObject@/link and
260 * @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link;
261 * no other class should derive from OSMetaClassBase.
262 *
263 * For more information, see
264 * <i>@link //apple_ref/doc/uid/TP40002799
265 * I/O Kit Device Driver Design Guidelines@/link</i>.
266 *
267 * <b>Use by Kernel Extensions</b>
268 *
269 * Kernel Extensions should never interact directly with OSMetaClassBase,
270 * but they will find useful several macros that tie in
271 * to the run-time type information system, specifically:
272 * <ul>
273 * <li><code>@link OSTypeAlloc OSTypeAlloc@/link</code> - allocation of new instances</li>
274 * <li><code>@link OSDynamicCast OSDynamicCast@/link</code> - safe type casting</li>
275 * <li><code>@link OSCheckTypeInst OSCheckTypeInst@/link</code> -
276 * checking for inheritance/derivation</li>
277 * <li><code>@link OSMemberFunctionCast OSMemberFunctionCast@/link</code> -
278 * casting C++ member functions to C function pointers
279 * for registration as callbacks</li>
280 * </ul>
281 *
282 * See @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link
283 * for more run-time type information interfaces.
284 *
285 * <b>Use Restrictions</b>
286 *
287 * OSMetaClassBase should not be subclassed by kernel extensions,
288 * nor should kernel extensions call its run-time type functions directly.
289 *
290 * The run-time type functions and macros are <b>not safe</b>
291 * to call in a primary interrupt context.
292 *
293 * <b>Concurrency Protection</b>
294 *
295 * The run-time type macros and functions of OSMetaClassBase are thread-safe.
296 */
297
298class OSMetaClassBase
299{
300public:
301
302
303/*!
304 * @define OSTypeAlloc
305 * @hidecontents
306 *
307 * @abstract
308 * Allocates an instance of the named object class.
309 *
310 * @param type The name of the desired class to be created,
311 * as a raw token, <i>not</i> a string or macro.
312 *
313 * @result
314 * A pointer to the new, uninitialized object on success;
315 * <code>NULL</code> on failure.
316 *
317 * @discussion
318 * See also
319 * <code>@link
320 * //apple_ref/cpp/clm/OSMetaClass/allocClassWithName/staticOSObject*\/(constchar*)
321 * OSMetaClass::allocClassWithName(const char *)@/link</code>
322 * and
323 * <code>@link
324 * //apple_ref/cpp/instm/OSMetaClass/alloc/virtualOSObject*\/()
325 * OSMetaClass::alloc@/link</code>.
326 *
327 * The OSTypeAlloc macro is used to avoid binary compatibility difficulties
328 * presented by the C++ <code>new</code> operator.
329 */
330#define OSTypeAlloc(type) ((type *) ((type::metaClass)->alloc()))
331
332
333/*!
334 * @define OSTypeID
335 * @hidecontents
336 *
337 * @abstract
338 * Returns the type ID (metaclass) of a class based on its name.
339 *
340 * @param type The name of the desired class, as a raw token,
341 * <i>not</i> a string or macro.
342 *
343 * @result
344 * The unique type ID (metaclass) for the class.
345 *
346 * @discussion
347 * It is typically more useful to determine whether a class is derived
348 * from another; see
349 * <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code>
350 * and
351 * <code>@link //apple_ref/cpp/macro/OSCheckTypeInst OSCheckTypeInst@/link</code>.
352 */
353#define OSTypeID(type) (type::metaClass)
354#define OSMTypeID(type) (const_cast<OSMetaClass *>(type::metaClass))
355
356
357/*!
358 * @define OSTypeIDInst
359 * @hidecontents
360 *
361 * @abstract
362 * Returns the type ID (metaclass) for the class of an object instance.
363 *
364 * @param typeinst An instance of an OSObject subclass.
365 *
366 * @result
367 * The type ID of that object's class; that is, its metaclass.
368 *
369 * @discussion
370 * It is typically more useful to determine whether an object is derived
371 * from a particular class; see
372 * <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code>
373 * and
374 * <code>@link //apple_ref/cpp/macro/OSCheckTypeInst OSCheckTypeInst@/link</code>.
375 */
376#define OSTypeIDInst(typeinst) ((typeinst)->getMetaClass())
377
378
379/*!
380 * @define OSDynamicCast
381 * @hidecontents
382 *
383 * @abstract
384 * Safe type-casting for Libkern C++ objects.
385 *
386 * @param type The name of the desired class type, as a raw token,
387 * <i>not</i> a string or macro.
388 * It is assumed you intend to cast to a pointer
389 * to an object of this type.
390 * Type qualifiers, such as <code>const</code>,
391 * are not recognized and will cause
392 * a (usually obscure) compile error.
393 * @param inst A pointer to the object instance to be cast.
394 * May be <code>NULL</code>.
395 *
396 * @result
397 * <code>inst</code> if it is non-<code>NULL</code>
398 * and derived from <code>type</code>;
399 * otherwise <code>NULL</code>.
400 *
401 * @discussion
402 * <code>OSDynamicCast</code> is a rough equivalent
403 * to the standard C++ RTTI <code>dynamic_cast&lt;T&gt;</code> operator.
404 * Your code should use this instead of raw C type-casting,
405 * and check the resulting value.
406 * If the result is non-<code>NULL</code>,
407 * the object is safe to use as the type-cast class;
408 * if the result is <code>NULL</code>,
409 * the object does not derive from the type-cast class
410 * and your code should take appropriate steps to handle the error.
411 */
412#define OSDynamicCast(type, inst) \
413 ((type *) OSMetaClassBase::safeMetaCast((inst), OSTypeID(type)))
414
415/*!
416 * @define OSRequiredCast
417 * @hidecontents
418 *
419 * @abstract
420 * Safe type-casting for Libkern C++ objects; panics on failure.
421 * The input parameters are the same as for the {@code OSDynamicCast} macro.
422 *
423 * @result {@code inst} if it is NULL or derived from {@code type};
424 * otherwise triggers a kernel panic.
425 *
426 * @discussion
427 * This macro should be used in place of C-style casts or
428 * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
429 * when the caller is absolutely sure that the passed
430 * argument is a subclass of a required type.
431 * It is equivalent to using {@code OSDynamicCast} and crashing with a kernel
432 * panic on cast failure.
433 */
434#define OSRequiredCast(type, inst) \
435 ((type *) OSMetaClassBase::requiredMetaCast((inst), OSTypeID(type)))
436
437/*!
438 * @define OSCheckTypeInst
439 * @hidecontents
440 *
441 * @abstract
442 * Checks whether two objects are type-compatible.
443 *
444 * @param typeinst The reference object.
445 * @param inst The object to check for type compatibility.
446 *
447 * @result
448 * <code>true</code> if both <code>inst</code> and
449 * <code>typeinst</code> are non-<code>NULL</code>
450 * and <code>inst</code> is derived from the class of <code>typeinst</code>;
451 * otherwise <code>false</code>.
452 */
453#define OSCheckTypeInst(typeinst, inst) \
454 OSMetaClassBase::checkTypeInst(inst, typeinst)
455
456#define OSSafeRelease(inst) \
457 do { int OSSafeRelease __attribute__ ((deprecated("Use OSSafeReleaseNULL"))); (OSSafeRelease); \
458 if (inst) (inst)->release(); } while (0)
459
460/*! @function OSSafeReleaseNULL
461 * @abstract Release an object if not <code>NULL</code>, then set it to <code>NULL</code>.
462 * @param inst Instance of an OSObject, may be <code>NULL</code>.
463 */
464#define OSSafeReleaseNULL(inst) do { if (inst != NULL) (inst)->release(); (inst) = NULL; } while (0)
465
466 typedef void (*_ptf_t)(void);
467
468#if defined(__arm__) || defined(__arm64__)
469
470 static _ptf_t _ptmf2ptf(const OSMetaClassBase * self, void (OSMetaClassBase::*func)(void));
471
472#elif defined(__i386__) || defined(__x86_64__)
473
474// Slightly less arcane and slightly less evil code to do
475// the same for kexts compiled with the standard Itanium C++
476// ABI
477
478 static inline _ptf_t
479 _ptmf2ptf(const OSMetaClassBase *self, void (OSMetaClassBase::*func)(void))
480 {
481 union {
482 void (OSMetaClassBase::*fIn)(void);
483 uintptr_t fVTOffset;
484 _ptf_t fPFN;
485 } map;
486
487 map.fIn = func;
488
489 if (map.fVTOffset & 1) {
490 // virtual
491 union {
492 const OSMetaClassBase *fObj;
493 _ptf_t **vtablep;
494 } u;
495 u.fObj = self;
496
497 // Virtual member function so dereference vtable
498 return *(_ptf_t *)(((uintptr_t)*u.vtablep) + map.fVTOffset - 1);
499 } else {
500 // Not virtual, i.e. plain member func
501 return map.fPFN;
502 }
503 }
504
505#else
506#error Unknown architecture.
507#endif /* __arm__ */
508
509
510/*!
511 * @define OSMemberFunctionCast
512 * @hidecontents
513 *
514 * @abstract
515 * Converts a C++ member function pointer, relative to an instance,
516 * to a C-style pointer to function.
517 *
518 * @param cptrtype The function type declaration to cast to
519 * (typically provided as a <code>typedef</code> by I/O KitKit classes).
520 * @param self The <code>this</code> pointer of the object whose function
521 * you wish to cache.
522 * @param func The pointer to the member function itself,
523 * something like <code>&Class::function</code>.
524 * It should be an explicit member function pointer constant,
525 * rather than a variable.
526 * Don't pass a <code>NULL</code> member function pointer.
527 * Instead, directly use a <code>NULL</code> function pointer.
528 *
529 * @result
530 * A pointer to a function of the given type referencing <code>self</code>.
531 *
532 * @discussion
533 * This function is used to generate pointers to C++ functions for instances,
534 * such that they can be registered as callbacks with I/O Kit objects.
535 *
536 * No warnings are generated.
537 *
538 * This function will panic if an attempt is made to call it
539 * with a multiply-inheriting class.
540 */
541#if __has_builtin(__builtin_load_member_function_pointer)
542#define OSMemberFunctionCast(cptrtype, self, func) \
543 ((cptrtype) __builtin_load_member_function_pointer(*self, func) ? : \
544 (cptrtype) OSMetaClassBase:: \
545 _ptmf2ptf(self, (void (OSMetaClassBase::*)(void)) func))
546#else
547#define OSMemberFunctionCast(cptrtype, self, func) \
548 (cptrtype) OSMetaClassBase:: \
549 _ptmf2ptf(self, (void (OSMetaClassBase::*)(void)) func)
550#endif
551
552protected:
553 OSMetaClassBase();
554 virtual
555 ~OSMetaClassBase();
556
557private:
558// Disable copy constructors of OSMetaClassBase based objects
559/* Not to be included in headerdoc.
560 *
561 * @function operator =
562 *
563 * @abstract
564 * Disable implicit copy constructor by making private
565 *
566 * @param src Reference to source object that isn't allowed to be copied.
567 */
568 void operator =(OSMetaClassBase &src);
569
570/* Not to be included in headerdoc.
571 *
572 * @function OSMetaClassBase
573 *
574 * @abstract
575 * Disable implicit copy constructor by making private
576 *
577 * @param src Reference to source object that isn't allowed to be copied.
578 */
579 OSMetaClassBase(OSMetaClassBase &src);
580
581public:
582
583// xx-review: the original comment for this makes it sound to me like we don't
584// xx-review: catch over-releasing an object...?
585
586/*!
587 * @function release
588 *
589 * @abstract
590 * Abstract declaration of
591 * <code>@link
592 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
593 * release(int freeWhen)@/link</code>.
594 *
595 * @discussion
596 * See
597 * <code>@link
598 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
599 * release(int freeWhen)@/link</code>.
600 */
601 virtual void release(int freeWhen) const = 0;
602
603
604/*!
605 * @function getRetainCount
606 *
607 * @abstract
608 * Abstract declaration of
609 * <code>@link
610 * //apple_ref/cpp/instm/OSObject/getRetainCount/virtualint/()
611 * getRetainCount()@/link</code>.
612 *
613 * @discussion
614 * See
615 * <code>@link
616 * //apple_ref/cpp/instm/OSObject/getRetainCount/virtualint/()
617 * OSObject::getRetainCount()@/link</code>.
618 */
619 virtual int getRetainCount() const = 0;
620
621
622/*!
623 * @function retain
624 *
625 * @abstract
626 * Abstract declaration of
627 * <code>@link
628 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
629 * retain()@/link</code>.
630 *
631 * @discussion
632 * See
633 * <code>@link
634 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
635 * OSObject::retain()@/link</code>.
636 */
637 virtual void retain() const = 0;
638
639
640/*!
641 * @function release
642 *
643 * @abstract
644 * Abstract declaration of
645 * <code>@link
646 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
647 * release@/link</code>.
648 *
649 * @discussion
650 * See
651 * <code>@link
652 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
653 * OSObject::release@/link</code>.
654 */
655 virtual void release() const = 0;
656
657
658/*!
659 * @function serialize
660 *
661 * @abstract
662 * Abstract declaration of
663 * <code>@link
664 * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
665 * serialize@/link</code>.
666 *
667 * @discussion
668 * See
669 * <code>@link
670 * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
671 * OSObject::serialize@/link</code>.
672 */
673 virtual bool serialize(OSSerialize * serializer) const = 0;
674
675
676/*!
677 * @function getMetaClass
678 *
679 * @abstract
680 * Returns the OSMetaClass representing
681 * an OSMetaClassBase subclass.
682 *
683 * @discussion
684 * OSObject overrides this abstract member function
685 * to return the OSMetaClass object that represents
686 * each class for run-time typing.
687 */
688 virtual const OSMetaClass * getMetaClass() const = 0;
689
690
691/*!
692 * @function isEqualTo
693 *
694 * @abstract
695 * Checks whether another object is equal to the receiver.
696 *
697 * @param anObject The object to copmare to the receiver.
698 *
699 * @result
700 * <code>true</code> if the objects are equal, <code>false</code> otherwise.
701 *
702 * @discussion
703 * OSMetaClassBase implements this as a direct pointer comparison,
704 * since it has no other information to judge equality by.
705 * Subclasses generally override this function
706 * to do a more meaningful comparison.
707 * For example, OSString implements it to return
708 * <code>true</code> if <code>anObject</code>
709 * is derived from OSString and represents the same C string.
710 */
711 virtual bool isEqualTo(const OSMetaClassBase * anObject) const;
712
713
714/*!
715 * @function metaCast
716 *
717 * @abstract
718 * Casts this object is to the class managed by the given OSMetaClass.
719 *
720 * @param toMeta A pointer to a constant OSMetaClass
721 * for the desired target type.
722 *
723 * @result
724 * <code>this</code> if the object is derived
725 * from the class managed by <code>toMeta</code>,
726 * otherwise <code>NULL</code>.
727 *
728 * @discussion
729 * It is far more convenient to use
730 * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
731 */
732 OSMetaClassBase * metaCast(const OSMetaClass * toMeta) const;
733
734
735/*!
736 * @function metaCast
737 *
738 * @abstract
739 * Casts this object is to the class managed by the named OSMetaClass.
740 *
741 * @param toMeta An OSSymbol naming the desired target type.
742 *
743 * @result
744 * <code>this</code> if the object is derived
745 * from the class named by <code>toMeta</code>,
746 * otherwise <code>NULL</code>.
747 *
748 * @discussion
749 * It is far more convenient to use
750 * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
751 */
752 OSMetaClassBase * metaCast(const OSSymbol * toMeta) const;
753
754
755/*!
756 * @function metaCast
757 *
758 * @abstract
759 * Casts this object is to the class managed by the named OSMetaClass.
760 *
761 * @param toMeta An OSString naming the desired target type.
762 * @result
763 * <code>this</code> if the object is derived
764 * from the class named by <code>toMeta</code>,
765 * otherwise <code>NULL</code>.
766 *
767 * @discussion
768 * It is far more convenient to use
769 * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
770 */
771 OSMetaClassBase * metaCast(const OSString * toMeta) const;
772
773
774/*!
775 * @function metaCast
776 *
777 * @abstract
778 * Casts this object is to the class managed by the named OSMetaClass.
779 *
780 * @param toMeta A C string naming the desired target type.
781 * @result
782 * <code>this</code> if the object is derived
783 * from the class named by <code>toMeta</code>,
784 * otherwise <code>NULL</code>.
785 *
786 * @discussion
787 * It is far more convenient to use
788 * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
789 */
790 OSMetaClassBase * metaCast(const char * toMeta) const;
791
792// Helper inlines for run-time type preprocessor macros
793/*!
794 * @function safeMetaCast
795 *
796 * @abstract
797 * Casts an object is to the class managed by the given OSMetaClass.
798 *
799 * @param anObject A pointer to the object to be cast.
800 * @param toMeta A pointer to a constant OSMetaClass
801 * for the desired target type.
802 *
803 * @result
804 * <code>anObject</code> if the object is derived
805 * from the class managed by <code>toMeta</code>,
806 * otherwise <code>NULL</code>.
807 *
808 * @discussion
809 * It is far more convenient to use
810 * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
811 */
812 static OSMetaClassBase * safeMetaCast(
813 const OSMetaClassBase * anObject,
814 const OSMetaClass * toMeta);
815
816/*!
817 * @function requiredMetaCast
818 *
819 * @abstract
820 * Casts an object to the class managed by the given OSMetaClass or
821 * fails with a kernel panic if the cast does not succeed.
822 *
823 * @param anObject A pointer to the object to be cast.
824 * @param toMeta A pointer to a constant OSMetaClass
825 * for the desired target type.
826 *
827 * @result
828 * <code>anObject</code> if the object is derived
829 * from the class managed by <code>toMeta</code>,
830 * <code>NULL</code> if <code>anObject</code> was <code>NULL</code>,
831 * kernel panic otherwise.
832 *
833 * @discussion
834 * It is far more convenient to use
835 * <code>@link OSRequiredCast OSRequiredCast@/link</code>.
836 */
837 static OSMetaClassBase *requiredMetaCast(
838 const OSMetaClassBase * anObject,
839 const OSMetaClass * toMeta);
840
841/*!
842 * @function checkTypeInst
843 *
844 * @abstract
845 * Checks whether an object instance is of the same class
846 * as another object instance (or a subclass of that class).
847 *
848 * @param inst A pointer to the object to check.
849 * @param typeinst A pointer to an object of the class being checked.
850 *
851 * @result
852 * <code>true</code> if the object is derived
853 * from the class of <code>typeinst</code>
854 * or a subclass of that class,
855 * otherwise <code>false</code>.
856 *
857 * @discussion
858 * It is far more convenient to use
859 * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
860 */
861 static bool checkTypeInst(
862 const OSMetaClassBase * inst,
863 const OSMetaClassBase * typeinst);
864
865 static void initialize(void);
866
867public:
868
869/*!
870 * @function taggedRetain
871 *
872 * @abstract
873 * Abstract declaration of
874 * <code>@link
875 * //apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*)
876 * taggedRetain(const void *)@/link</code>.
877 *
878 * @discussion
879 * See
880 * <code>@link
881 * //apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*)
882 * OSObject::taggedRetain(const void *)@/link</code>.
883 */
884// WAS: virtual void _RESERVEDOSMetaClassBase0();
885 virtual void taggedRetain(const void * tag = NULL) const = 0;
886
887
888/*!
889 * @function taggedRelease
890 *
891 * @abstract
892 * Abstract declaration of
893 * <code>@link
894 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*)
895 * taggedRelease(const void *)@/link</code>.
896 *
897 * @discussion
898 * See
899 * <code>@link
900 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*)
901 * OSObject::taggedRelease(const void *)@/link</code>.
902 */
903// WAS: virtual void _RESERVEDOSMetaClassBase1();
904 virtual void taggedRelease(const void * tag = NULL) const = 0;
905
906protected:
907/*!
908 * @function taggedRelease
909 *
910 * @abstract
911 * Abstract declaration of
912 * <code>@link
913 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
914 * taggedRelease(const void *, const int freeWhen)@/link</code>.
915 *
916 * @discussion
917 * See
918 * <code>@link
919 * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
920 * OSObject::taggedRelease(const void *, const int freeWhen)@/link</code>.
921 */
922// WAS: virtual void _RESERVEDOSMetaClassBase2();
923 virtual void taggedRelease(
924 const void * tag,
925 const int freeWhen) const = 0;
926
927public:
928 virtual kern_return_t
929 Dispatch(const IORPC rpc);
930
931 kern_return_t
932 Invoke(const IORPC rpc);
933
934private:
935#if APPLE_KEXT_VTABLE_PADDING
936// Virtual Padding
937#if defined(__arm64__) || defined(__arm__)
938 virtual void _RESERVEDOSMetaClassBase0();
939 virtual void _RESERVEDOSMetaClassBase1();
940 virtual void _RESERVEDOSMetaClassBase2();
941 virtual void _RESERVEDOSMetaClassBase3();
942#endif /* defined(__arm64__) || defined(__arm__) */
943 virtual void _RESERVEDOSMetaClassBase4();
944 virtual void _RESERVEDOSMetaClassBase5();
945 virtual void _RESERVEDOSMetaClassBase6();
946 virtual void _RESERVEDOSMetaClassBase7();
947#endif /* APPLE_KEXT_VTABLE_PADDING */
948} APPLE_KEXT_COMPATIBILITY;
949
950
951#ifdef XNU_KERNEL_PRIVATE
952typedef bool (*OSMetaClassInstanceApplierFunction)(const OSObject * instance,
953 void * context);
954#endif /* XNU_KERNEL_PRIVATE */
955
956/*!
957 * @class OSMetaClass
958 *
959 * @abstract
960 * OSMetaClass manages run-time type information
961 * for Libkern and I/O Kit C++ classes.
962 *
963 * @discussion OSMetaClass manages run-time type information
964 * for Libkern and I/O Kit C++ classes.
965 * An instance of OSMetaClass exists for (nearly) every such C++ class,
966 * keeping track of inheritance relationships, class lookup by name,
967 * instance counts, and more.
968 * OSMetaClass operates almost entirely behind the scenes,
969 * and kernel extensions should rarely, if ever,
970 * have to interact directly with OSMetaClass.
971 *
972 * <b>Use by Kernel Extensions</b>
973 *
974 * While kernel extensions rarey interact directly with OSMetaClass at run time,
975 * they must register their classes with the metaclass system
976 * using the macros declared here.
977 * The class declaration should use one of these two macros
978 * before its first member function declaration:
979 * <ul>
980 * <li><code>@link OSDeclareDefaultStructors OSDeclareDefaultStructors@/link</code> -
981 * for classes with no abstract member function declarations</li>
982 * <li><code>@link OSDeclareAbstractStructors OSDeclareAbstractStructors@/link</code> -
983 * for classes with at least one abstract member function declaration</li>
984 * <li><code>@link OSDeclareFinalStructors OSDeclareFinalStructors@/link</code> -
985 * for classes that should not be subclassable by another kext</li>
986 * </ul>
987 *
988 * The class implementation should then use one of these macros:
989 * <ul>
990 * <li><code>@link OSDefineMetaClassAndStructors
991 * OSDefineMetaClassAndStructors@/link</code> -
992 * for classes with no abstract member function declarations</li>
993 * <li><code>@link OSDefineMetaClassAndAbstractStructors
994 * OSDefineMetaClassAndAbstractStructors@/link</code> -
995 * for classes with at least one abstract member function declaration</li>
996 * <li><code>@link OSDefineMetaClassAndFinalStructors
997 * OSDefineMetaClassAndFinalStructors@/link</code> -
998 * for classes that should not be subclassable by another kext</li>
999 * </ul>
1000 *
1001 * Classes in kernel extensions that are intended for use as libraries
1002 * may need to reserve vtable slots to preserve binary compatibility
1003 * as new functions are added. They may do so with these macros:
1004 * <ul>
1005 * <li><code>@link OSMetaClassDeclareReservedUnused
1006 * OSMetaClassDeclareReservedUnused@/link</code> -
1007 * reserves a vtable slot</li>
1008 * <li><code>@link OSMetaClassDefineReservedUnused
1009 * OSMetaClassDefineReservedUnused@/link</code> -
1010 * defines the reserved vtable slot as an unimplemented function</li>
1011 * <li><code>@link OSMetaClassDeclareReservedUsed
1012 * OSMetaClassDeclareReservedUsed@/link</code> -
1013 * documents that a formerly reserved slot is now used</li>
1014 * <li><code>@link OSMetaClassDefineReservedUsed
1015 * OSMetaClassDefineReservedUsed@/link</code> -
1016 * documents that a formerly reserved slot is now used</li>
1017 * </ul>
1018 *
1019 * <b>Use Restrictions</b>
1020 *
1021 * OSMetaClass should not be explicitly subclassed by kernel extensions
1022 * (the declare/define macros do that),
1023 * nor should kernel extensions call its run-time type functions directly.
1024 *
1025 * OSMetaClass functions should be considered
1026 * <b>unsafe</b> to call in a primary interrupt context.
1027 *
1028 * <b>Concurrency Protection</b>
1029 *
1030 * Kernel extensions should in general not interact
1031 * with OSMetaClass objects directly,
1032 * instead using the run-time type macros.
1033 * Much of OSMetaClass's interface is intended for use
1034 * by the run-time type information system,
1035 * which handles concurrency and locking internally.
1036 */
1037class OSMetaClass : public OSMetaClassBase
1038{
1039 friend class OSKext;
1040#if IOKITSTATS
1041 friend class IOStatistics;
1042#endif
1043
1044private:
1045// Can never be allocated must be created at compile time
1046 static void * operator new(size_t size);
1047
1048/* Reserved for future use. (Internal use only) */
1049 struct ExpansionData *reserved;
1050
1051/* superClass Handle to the superclass's meta class. */
1052 const OSMetaClass *superClassLink;
1053
1054/* className OSSymbol of the class' name. */
1055 const OSSymbol *className;
1056
1057/* classSize How big is a single instance of this class. */
1058 unsigned int classSize;
1059
1060/* instanceCount Roughly number of instances of the object,
1061 * +1 for each direct subclass with a nonzero refcount.
1062 * Used primarily as a code-in-use flag.
1063 */
1064 mutable unsigned int instanceCount;
1065
1066/* Not to be included in headerdoc.
1067 *
1068 * @function OSMetaClass
1069 *
1070 * @abstract
1071 * The default private constructor.
1072 */
1073 OSMetaClass();
1074
1075// Called by postModLoad
1076/* Not to be included in headerdoc.
1077 *
1078 * @function logError
1079 *
1080 * @abstract
1081 * Logs an error string for an <code>OSReturn</code> value
1082 * using <code>printf</code>.
1083 *
1084 * @param result The <code>OSReturn</code> value for which to log a message.
1085 *
1086 * @discussion
1087 * This function is used to log errors loading kernel extensions.
1088 * Kernel extensions themselves should not call it.
1089 */
1090 static void logError(OSReturn result);
1091
1092public:
1093
1094/*!
1095 * @function getMetaClassWithName
1096 *
1097 * @abstract
1098 * Look up a metaclass in the run-time type information system.
1099 *
1100 * @param name The name of the desired class's metaclass.
1101 *
1102 * @result
1103 * A pointer to the metaclass object if found, <code>NULL</code> otherwise.
1104 */
1105 static const OSMetaClass * getMetaClassWithName(const OSSymbol * name);
1106
1107#if XNU_KERNEL_PRIVATE
1108
1109/*!
1110 * @function copyMetaClassWithName
1111 *
1112 * @abstract
1113 * Look up a metaclass in the run-time type information system.
1114 *
1115 * @param name The name of the desired class's metaclass.
1116 *
1117 * @result
1118 * A pointer to the metaclass object if found, <code>NULL</code> otherwise.
1119 * The metaclass will be protected from unloading until releaseMetaClass()
1120 * is called.
1121 */
1122 static const OSMetaClass * copyMetaClassWithName(const OSSymbol * name);
1123/*!
1124 * @function releaseMetaClass
1125 *
1126 * @abstract
1127 * Releases reference obtained from copyMetaClassWithName().
1128 *
1129 * @discussion
1130 * The metaclass will be protected from unloading until releaseMetaClass()
1131 * is called.
1132 */
1133 void releaseMetaClass() const;
1134
1135#endif /* XNU_KERNEL_PRIVATE */
1136
1137protected:
1138/*!
1139 * @function retain
1140 *
1141 * @abstract
1142 * Implements the abstract <code>retain</code> function to do nothing.
1143 *
1144 * @discussion
1145 * Since an OSMetaClass instance must remain in existence
1146 * for as long as its kernel extension is loaded,
1147 * OSMetaClass does not use reference-counting.
1148 */
1149 virtual void retain() const;
1150
1151
1152/*!
1153 * @function release
1154 *
1155 * @abstract
1156 * Implements the abstract <code>release</code> function to do nothing.
1157 *
1158 * @discussion
1159 * Since an OSMetaClass instance must remain in existence
1160 * for as long as its kernel extension is loaded,
1161 * OSMetaClass does not use reference-counting.
1162 */
1163 virtual void release() const;
1164
1165
1166/*!
1167 * @function release
1168 *
1169 * @abstract
1170 * Implements the abstract <code>release(int freeWhen)</code>
1171 * function to do nothing.
1172 *
1173 * @param freeWhen Unused.
1174 *
1175 * @discussion
1176 * Since an OSMetaClass instance must remain in existence
1177 * for as long as its kernel extension is loaded,
1178 * OSMetaClass does not use reference-counting.
1179 */
1180 virtual void release(int freeWhen) const;
1181
1182
1183/*!
1184 * @function taggedRetain
1185 *
1186 * @abstract
1187 * Implements the abstract <code>taggedRetain(const void *)</code>
1188 * function to do nothing.
1189 *
1190 * @param tag Unused.
1191 *
1192 * @discussion
1193 * Since an OSMetaClass instance must remain in existence
1194 * for as long as its kernel extension is loaded,
1195 * OSMetaClass does not use reference-counting.
1196 */
1197 virtual void taggedRetain(const void * tag = NULL) const;
1198
1199
1200/*!
1201 * @function taggedRelease
1202 *
1203 * @abstract
1204 * Implements the abstract <code>taggedRelease(const void *)</code>
1205 * function to do nothing.
1206 *
1207 * @param tag Unused.
1208 *
1209 * @discussion
1210 * Since an OSMetaClass instance must remain in existence
1211 * for as long as its kernel extension is loaded,
1212 * OSMetaClass does not use reference-counting.
1213 */
1214 virtual void taggedRelease(const void * tag = NULL) const;
1215
1216
1217/*!
1218 * @function taggedRelease
1219 *
1220 * @abstract
1221 * Implements the abstract <code>taggedRelease(const void *, cont int)</code>
1222 * function to do nothing.
1223 *
1224 * @param tag Unused.
1225 * @param freeWhen Unused.
1226 *
1227 * @discussion
1228 * Since an OSMetaClass instance must remain in existence
1229 * for as long as its kernel extension is loaded,
1230 * OSMetaClass does not use reference-counting.
1231 */
1232 virtual void taggedRelease(
1233 const void * tag,
1234 const int freeWhen) const;
1235
1236
1237/*!
1238 * @function getRetainCount
1239 *
1240 * @abstract
1241 * Implements the abstract <code>getRetainCount</code>
1242 * function to return 0.
1243 *
1244 * @result
1245 * Always returns 0.
1246 *
1247 * @discussion
1248 * Since an OSMetaClass instance must remain in existence
1249 * for as long as its kernel extension is loaded,
1250 * OSMetaClass does not use reference-counting.
1251 */
1252 virtual int getRetainCount() const;
1253
1254
1255/* Not to be included in headerdoc.
1256 *
1257 * @function getMetaClass
1258 *
1259 * @abstract
1260 * Returns the meta-metaclass.
1261 *
1262 * @result
1263 * The metaclass of the OSMetaClass object.
1264 */
1265 virtual const OSMetaClass * getMetaClass() const;
1266
1267
1268/*!
1269 * @function OSMetaClass
1270 *
1271 * @abstract
1272 * Constructor for OSMetaClass objects.
1273 *
1274 * @param className A C string naming the C++ class
1275 * that this OSMetaClass represents.
1276 * @param superclass The OSMetaClass object representing the superclass
1277 * of this metaclass's class.
1278 * @param classSize The allocation size of the represented C++ class.
1279 *
1280 * @discussion
1281 * This constructor is protected and cannot be used
1282 * to instantiate OSMetaClass directly, as OSMetaClass is an abstract class.
1283 * This function is called during kext loading
1284 * to queue C++ classes for registration.
1285 * See <code>@link preModLoad preModLoad@/link</code> and
1286 * <code>@link postModLoad postModLoad@/link</code>.
1287 */
1288 OSMetaClass(const char * className,
1289 const OSMetaClass * superclass,
1290 unsigned int classSize);
1291
1292#ifdef KERNEL_PRIVATE
1293/*!
1294 * @function OSMetaClass
1295 *
1296 * @abstract
1297 * Constructor for OSMetaClass objects.
1298 *
1299 * @param className A C string naming the C++ class
1300 * that this OSMetaClass represents.
1301 * @param superclass The OSMetaClass object representing the superclass
1302 * of this metaclass's class.
1303 * @param classSize The allocation size of the represented C++ class.
1304 * @param zone Pointer to return the created zone.
1305 * @param zone_name Name of zone to create
1306 * @param zflags Zone creation flags
1307 *
1308 * @discussion
1309 * This constructor is protected and cannot be used
1310 * to instantiate OSMetaClass directly, as OSMetaClass is an abstract class.
1311 * This function is called during kext loading
1312 * to queue C++ classes for registration.
1313 * See <code>@link preModLoad preModLoad@/link</code> and
1314 * <code>@link postModLoad postModLoad@/link</code>.
1315 */
1316 OSMetaClass(const char * className,
1317 const OSMetaClass * superclass,
1318 unsigned int classSize,
1319 zone_t * zone,
1320 const char * zone_name,
1321 zone_create_flags_t zflags);
1322#endif
1323
1324/*!
1325 * @function ~OSMetaClass
1326 *
1327 * @abstract
1328 * Destructor for OSMetaClass objects.
1329 *
1330 * @discussion
1331 * This function is called when the kernel extension that implements
1332 * the metaclass's class is unloaded.
1333 * The destructor removes all references to the class
1334 * from the run-time type information system.
1335 */
1336 virtual
1337 ~OSMetaClass();
1338
1339// Needs to be overriden as NULL as all OSMetaClass objects are allocated
1340// statically at compile time, don't accidently try to free them.
1341 void
1342 operator delete(void *, size_t)
1343 {
1344 }
1345
1346public:
1347 static const OSMetaClass * const metaClass;
1348
1349/*!
1350 * @function preModLoad
1351 *
1352 * @abstract
1353 * Prepares the run-time type system
1354 * for the creation of new metaclasses
1355 * during loading of a kernel extension (module).
1356 *
1357 * @param kextID The bundle ID of the kext being loaded.
1358 *
1359 * @result
1360 * An opaque handle to the load context
1361 * for the kernel extension on success;
1362 * <code>NULL</code> on failure.
1363 *
1364 * @discussion
1365 * <i>Not for use by kernel extensions.</i>
1366 *
1367 * Prepares the run-time type information system to record and register
1368 * metaclasses created by static constructors until a subsequent call to
1369 * <code>@link postModLoad postModLoad@/link</code>.
1370 * <code>preModLoad</code> takes a lock to ensure processing of a single
1371 * load operation at a time; the lock is released by
1372 * <code>@link postModLoad postModLoad@/link</code>.
1373 * Any OSMetaClass constructed between these two function calls
1374 * will be associated with <code>kextID</code>.
1375 */
1376 static void * preModLoad(const char * kextID);
1377
1378
1379/*!
1380 * @function checkModLoad
1381 *
1382 * @abstract
1383 * Checks whether the current kext load operation can proceed.
1384 *
1385 * @param loadHandle The opaque handle returned
1386 * by <code>@link preModLoad preModLoad@/link</code>.
1387 * @result
1388 * <code>true</code> if no errors are outstanding
1389 * and the system is ready to process more metaclasses.
1390 *
1391 * @discussion
1392 * <i>Not for use by kernel extensions.</i>
1393 */
1394 static bool checkModLoad(void * loadHandle);
1395
1396
1397/*!
1398 * @function postModLoad
1399 *
1400 * @abstract
1401 * Registers the metaclasses created during loading of a kernel extension.
1402 *
1403 * @param loadHandle The opaque handle returned
1404 * by <code>@link preModLoad preModLoad@/link</code>.
1405 * @result
1406 * The error code of the first error encountered,
1407 * or
1408 * <code>@link
1409 * //apple_ref/cpp/macro/kOSReturnSuccess
1410 * kOSReturnSuccess@/link</code>
1411 * if no error occurred.
1412 *
1413 * @discussion
1414 * <i>Not for use by kernel extensions.</i>
1415 *
1416 * Called after all static constructors in a kernel extension
1417 * have created metaclasses,
1418 * this function checks for duplicate class names,
1419 * then registers the new metaclasses under the kext ID
1420 * that @link preModLoad preModLoad@/link was called with,
1421 * so that they can be dynamically allocated
1422 * and have their instance counts tracked.
1423 * <code>postModLoad</code> releases the lock taken by
1424 * <code>@link preModLoad preModLoad@/link</code>.
1425 */
1426 static OSReturn postModLoad(void * loadHandle);
1427
1428/*!
1429 * @function modHasInstance
1430 *
1431 * @abstract
1432 * Returns whether any classes defined by the named
1433 * kernel extension (or their subclasses) have existing instances.
1434 *
1435 * @param kextID The bundle ID of the kernel extension to check.
1436 *
1437 * @result
1438 * <code>true</code> if the kext is found and
1439 * if any class defined by that kext
1440 * has a nonzero instance count,
1441 * <code>false</code> otherwise.
1442 *
1443 * @discussion
1444 * This function is called before a kernel extension's static destructors
1445 * are invoked, prior to unloading the extension.
1446 * If any classes stil have instances or subclasses with instances,
1447 * those classes are logged
1448 * (using <code>@link reportModInstances reportModInstances@/link</code>) and
1449 * the kernel extension is not be unloaded.
1450 */
1451 static bool modHasInstance(const char * kextID);
1452
1453
1454/*!
1455 * @function reportModInstances
1456 *
1457 * @abstract
1458 * Logs the instance counts for classes
1459 * defined by a kernel extension.
1460 *
1461 * @param kextID The bundle ID of the kernel extension to report on.
1462 *
1463 * @discussion
1464 * This function prints the names and instance counts
1465 * of any class defined by <code>kextID</code>
1466 * that has a nonzero instance count.
1467 * It's called by <code>@link modHasInstance modHasInstance@/link</code>
1468 * to help diagnose problems unloading kernel extensions.
1469 */
1470 static void reportModInstances(const char * kextID);
1471
1472
1473/*!
1474 * @function considerUnloads
1475 *
1476 * @abstract
1477 * Schedule automatic unloading of unused kernel extensions.
1478 *
1479 * @discussion
1480 * This function schedules a check for kernel extensions
1481 * that can be automatically unloaded,
1482 * canceling any currently scheduled check.
1483 * At that time, any such kexts with no Libkern C++ instances
1484 * and no external references are unloaded.
1485 *
1486 * The I/O Kit calls this function when matching goes idle.
1487 *
1488 * Kernel extensions that define subclasses of
1489 * @link //apple_ref/doc/class/IOService IOService@/link
1490 * are eligible for automatic unloading.
1491 *
1492 * (On releases of Mac OS X prior to Snow Leopard (10.6),
1493 * any kernel extension defining any Libkern C++ class
1494 * was eligible for automatic unloading,
1495 * but that unload did not call the module stop routine.
1496 * Non-I/O Kit kernel extensions that define Libkern C++ subclasses
1497 * should be sure to have OSBundleLibraries declarations that ensure
1498 * they will not load on releases prior to Snow Leopard.)
1499 */
1500 static void considerUnloads();
1501
1502#if XNU_KERNEL_PRIVATE
1503 static bool removeClasses(OSCollection * metaClasses);
1504#endif /* XNU_KERNEL_PRIVATE */
1505
1506/*!
1507 * @function allocClassWithName
1508 *
1509 * @abstract
1510 * Allocates an instance of a named OSObject-derived class.
1511 *
1512 * @param name The name of the desired class.
1513 *
1514 * @result
1515 * A pointer to the newly-allocated, uninitialized object on success;
1516 * <code>NULL</code> on failure.
1517 *
1518 * @discussion
1519 * Kernel extensions should not need to use this function
1520 * directly, instead using static instance-creation functions
1521 * defined by classes.
1522 *
1523 * This function consults the run-time type information system
1524 * to find the metaclass for the named class.
1525 * If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code>
1526 * function and returns the result.
1527 */
1528 static OSObject * allocClassWithName(const OSSymbol * name);
1529
1530
1531/*!
1532 * function allocClassWithName
1533 *
1534 * @abstract
1535 * Allocates an instance of a named OSObject-derived class.
1536 *
1537 * @param name The name of the desired class.
1538 *
1539 * @result
1540 * A pointer to the newly-allocated, uninitialized object on success;
1541 * <code>NULL</code> on failure.
1542 *
1543 * @discussion
1544 * Kernel extensions should not need to use this function
1545 * directly, instead using static instance-creation functions
1546 * defined by classes.
1547 *
1548 * This function consults the run-time type information system
1549 * to find the metaclass for the named class.
1550 * If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code>
1551 * function and returns the result.
1552 */
1553 static OSObject * allocClassWithName(const OSString * name);
1554
1555
1556/*!
1557 * function allocClassWithName
1558 *
1559 * @abstract
1560 * Allocates an instance of a named OSObject-derived class.
1561 *
1562 * @param name The name of the desired class.
1563 *
1564 * @result
1565 * A pointer to the newly-allocated, uninitialized object on success;
1566 * <code>NULL</code> on failure.
1567 *
1568 * @discussion
1569 * Kernel extensions should not need to use this function
1570 * directly, instead using static instance-creation functions
1571 * defined by classes.
1572 *
1573 * This function consults the run-time type information system
1574 * to find the metaclass for the named class.
1575 * If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code>
1576 * function and returns the result.
1577 */
1578 static OSObject * allocClassWithName(const char * name);
1579
1580
1581/*!
1582 * @function checkMetaCastWithName
1583 *
1584 * @abstract
1585 * Search the metaclass inheritance hierarchy by name for an object instance.
1586 *
1587 * @param className The name of the desired class or superclass.
1588 * @param object The object whose metaclass begins the search.
1589 *
1590 * @result
1591 * <code>object</code> if it's derived from <code>className</code>;
1592 * <code>NULL</code> otherwise.
1593 *
1594 * @discussion
1595 * This function is the basis of the Libkern run-time type-checking system.
1596 * Kernel extensions should not use it directly,
1597 * instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or
1598 * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
1599 */
1600 static OSMetaClassBase * checkMetaCastWithName(
1601 const OSSymbol * className,
1602 const OSMetaClassBase * object);
1603
1604/*!
1605 * @function checkMetaCastWithName
1606 *
1607 * @abstract
1608 * Search the metaclass inheritance hierarchy by name for an object instance.
1609 *
1610 * @param className The name of the desired class or superclass.
1611 * @param object The object whose metaclass begins the search.
1612 *
1613 * @result
1614 * <code>object</code> if it's derived from <code>className</code>;
1615 * <code>NULL</code> otherwise.
1616 *
1617 * @discussion
1618 * Kernel extensions should not use this function directly,
1619 * instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or
1620 * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
1621 */
1622 static OSMetaClassBase * checkMetaCastWithName(
1623 const OSString * className,
1624 const OSMetaClassBase * object);
1625
1626/*!
1627 * @function checkMetaCastWithName
1628 *
1629 * @abstract
1630 * Search the metaclass inheritance hierarchy by name for an object instance.
1631 *
1632 * @param className The name of the desired class or superclass.
1633 * @param object The object whose metaclass begins the search.
1634 *
1635 * @result
1636 * <code>object</code> if it's derived from <code>className</code>;
1637 * <code>NULL</code> otherwise.
1638 *
1639 * @discussion
1640 * Kernel extensions should not use this function directly,
1641 * instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or
1642 * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
1643 */
1644 static OSMetaClassBase * checkMetaCastWithName(
1645 const char * className,
1646 const OSMetaClassBase * object);
1647
1648
1649/*!
1650 * @function instanceConstructed
1651 *
1652 * @abstract
1653 * Counts the instances of the class managed by this metaclass.
1654 *
1655 * @discussion
1656 * <i>Not for use by kernel extensions.</i>
1657 *
1658 * Every non-abstract class that inherits from OSObject
1659 * has a default constructor that calls it's own metaclass's
1660 * <code>instanceConstructed</code> function.
1661 * This constructor is defined by the
1662 * <code>@link
1663 * OSDefineMetaClassAndStructors
1664 * OSDefineMetaClassAndStructors@/link</code>
1665 * macro that all OSObject subclasses must use.
1666 *
1667 * If a class's instance count goes from 0 to 1--that is,
1668 * upon the creation of the first instance of that class--the
1669 * superclass's instance count is also incremented.
1670 * This propagates reference counts up the inheritance chain so that
1671 * superclasses are counted as "in use" when subclasses have instances.
1672 */
1673 void instanceConstructed() const;
1674
1675
1676/*!
1677 * @function instanceDestructed
1678 *
1679 * @abstract
1680 * Counts the instances of the class managed by this metaclass.
1681 *
1682 * @discussion
1683 * Every non-abstract class that inherits from OSObject
1684 * has a default destructor that calls it's own metaclass's
1685 * <code>instanceDestructed</code> function.
1686 * This constructor is defined by the
1687 * @link OSDefineMetaClassAndStructors OSDefineMetaClassAndStructors@/link
1688 * macro that all OSObject subclasses must use.
1689 *
1690 * If a class's instance count goes from 1 to 0--that is,
1691 * upon the destruction of the last instance of that class--the
1692 * superclass's instance count is also decremented.
1693 * This reduces "in use" counts from superclasses when their subclasses
1694 * no longer have instances.
1695 */
1696 void instanceDestructed() const;
1697
1698
1699/*!
1700 * @function checkMetaCast
1701 *
1702 * @abstract
1703 * Check whether a given object is an instance of the receiving
1704 * metaclass's class or one derived from it.
1705 *
1706 * @param object The object to check for inheritance.
1707 *
1708 * @result
1709 * <code>object</code> if it is derived from the receiver's class,
1710 * <code>NULL</code> if not.
1711 */
1712 OSMetaClassBase * checkMetaCast(const OSMetaClassBase * object) const;
1713
1714
1715/*!
1716 * @function getInstanceCount
1717 *
1718 * @abstract
1719 * Returns the number of existing instances of the metaclass's class.
1720 *
1721 * @result
1722 * The number of existing instances of the metaclass's class,
1723 * plus 1 for each subclass with any instance.
1724 */
1725 unsigned int getInstanceCount() const;
1726
1727
1728/*!
1729 * @function getSuperClass
1730 *
1731 * @abstract
1732 * Returns the super-metaclass of the receiver.
1733 *
1734 * @result
1735 * Returns a pointer to the super-metaclass of the receiving
1736 * OSMetaClass, or <code>NULL</code> for OSObject's metaclass.
1737 */
1738 const OSMetaClass * getSuperClass() const;
1739
1740/*!
1741 * @function getKmodName
1742 *
1743 * @abstract
1744 * Returns the bundle identifier of the kernel extension
1745 * that defines this metaclass.
1746 *
1747 * @result
1748 * The bundle identifier of the kernel extension that defines this metaclass.
1749 *
1750 * @discussion
1751 * "Kmod" is an older term for kernel extension.
1752 */
1753 const OSSymbol * getKmodName() const;
1754
1755
1756/*!
1757 * @function getClassName
1758 *
1759 * @abstract
1760 * Returns the name of the C++ class managed by this metaclass.
1761 *
1762 * @result
1763 * Returns the name of the C++ class managed by this metaclass.
1764 */
1765 const char * getClassName() const;
1766 const OSSymbol * getClassNameSymbol() const;
1767
1768
1769/*!
1770 * @function getClassSize
1771 *
1772 * @abstract
1773 * Returns the allocation size of the C++ class managed by this metaclass.
1774 *
1775 * @result
1776 * The allocation size of the C++ class managed by this metaclass.
1777 */
1778 unsigned int getClassSize() const;
1779
1780
1781/*!
1782 * @function alloc
1783 *
1784 * @abstract
1785 * Allocates an instance of the C++ class managed by this metaclass.
1786 *
1787 * @result
1788 * A pointer to the newly allocated, uninitialized instance,
1789 * with a retain count of 1; <code>NULL</code> on allocation failure.
1790 *
1791 * @discussion
1792 * This function is automatically created by the metaclass-registration macros
1793 * to enable dynamic instance allocation.
1794 */
1795 virtual OSObject * alloc() const = 0;
1796
1797#ifdef XNU_KERNEL_PRIVATE
1798 OSKext * getKext() const;
1799 void addInstance(const OSObject * instance, bool super = false) const;
1800 void removeInstance(const OSObject * instance, bool super = false) const;
1801 void applyToInstances(OSMetaClassInstanceApplierFunction applier,
1802 void * context) const;
1803 static void applyToInstancesOfClassName(
1804 const OSSymbol * name,
1805 OSMetaClassInstanceApplierFunction applier,
1806 void * context);
1807private:
1808 static void applyToInstances(OSOrderedSet * set,
1809 OSMetaClassInstanceApplierFunction applier,
1810 void * context);
1811public:
1812#endif /* XNU_KERNEL_PRIVATE */
1813
1814/* Not to be included in headerdoc.
1815 *
1816 * @define OSDeclareCommonStructors
1817 * @hidecontents
1818 *
1819 * @abstract
1820 * Helper macro for for the standard metaclass-registration macros.
1821 * DO NOT USE.
1822 *
1823 * @param className The name of the C++ class, as a raw token,
1824 * <i>not</i> a string or macro.
1825 */
1826
1827#define _OS_ADD_METAMETHODS(b) _OS_ADD_METAMETHODS_ ## b
1828#define _OS_ADD_METAMETHODS_
1829#define _OS_ADD_METAMETHODS_dispatch \
1830 virtual kern_return_t Dispatch(const IORPC rpc) APPLE_KEXT_OVERRIDE;
1831
1832#define _OS_ADD_METHODS(className, b) _OS_ADD_METHODS_ ## b(className)
1833#define _OS_ADD_METHODS_(className)
1834#define _OS_ADD_METHODS_dispatch(className) \
1835 className ## _Methods \
1836 className ## _KernelMethods
1837
1838#define SUPERDISPATCH ((OSDispatchMethod)&super::_Dispatch)
1839
1840#define OSDeclareCommonStructors(className, dispatch) \
1841 private: \
1842 static const OSMetaClass * const superClass; \
1843 public: \
1844 static const OSMetaClass * const metaClass; \
1845 static class MetaClass : public OSMetaClass { \
1846 public: \
1847 MetaClass(); \
1848 virtual OSObject *alloc() const APPLE_KEXT_OVERRIDE; \
1849 _OS_ADD_METAMETHODS(dispatch); \
1850 } gMetaClass; \
1851 friend class className ::MetaClass; \
1852 virtual const OSMetaClass * getMetaClass() const APPLE_KEXT_OVERRIDE; \
1853 protected: \
1854 className (const OSMetaClass *); \
1855 virtual ~ className () APPLE_KEXT_OVERRIDE; \
1856 _OS_ADD_METHODS(className, dispatch)
1857
1858#define _OS_ADD_OPERATOR_PROTO \
1859 public: \
1860 static void *operator new(size_t size); \
1861 protected: \
1862 static void operator delete(void *mem, size_t size);
1863
1864/*!
1865 * @define OSDeclareDefaultStructors
1866 * @hidecontents
1867 *
1868 * @abstract
1869 * Declares run-time type information and functions
1870 * for a final (non-subclassable) Libkern C++ class.
1871 *
1872 * @param className The name of the C++ class, as a raw token,
1873 * <i>not</i> a string or macro.
1874 *
1875 * @discussion
1876 * Concrete Libkern C++ classes should "call" this macro
1877 * immediately after the opening brace in a class declaration.
1878 * It leaves the current privacy state as <code>protected:</code>.
1879 */
1880#define _OSDeclareDefaultStructors(className, dispatch) \
1881 OSDeclareCommonStructors(className, dispatch); \
1882 public: \
1883 className (void); \
1884 _OS_ADD_OPERATOR_PROTO \
1885 protected:
1886
1887#define OSDeclareDefaultStructors(className) \
1888 _OSDeclareDefaultStructors(className, )
1889
1890#define OSDeclareDefaultStructorsWithDispatch(className) \
1891 _OSDeclareDefaultStructors(className, dispatch)
1892
1893
1894/*!
1895 * @define OSDeclareAbstractStructors
1896 * @hidecontents
1897 *
1898 * @abstract
1899 * Declares run-time type information and functions
1900 * for an abstract Libkern C++ class.
1901 *
1902 * @param className The name of the C++ class, as a raw token,
1903 * <i>not</i> a string or macro.
1904 *
1905 * @discussion
1906 * Abstract Libkern C++ classes--those with at least one
1907 * pure virtual method--should "call" this macro
1908 * immediately after the opening brace in a class declaration.
1909 * It leaves the current privacy state as <code>protected:</code>.
1910 */
1911#define _OSDeclareAbstractStructors(className, dispatch) \
1912 OSDeclareCommonStructors(className, dispatch) \
1913 private: \
1914 /* Make primary constructor private in abstract */ \
1915 className (void); \
1916 protected: \
1917
1918#define OSDeclareAbstractStructors(className) \
1919 _OSDeclareAbstractStructors(className, ) \
1920 _OS_ADD_OPERATOR_PROTO
1921
1922#define OSDeclareAbstractStructorsWithDispatch(className) \
1923 _OSDeclareAbstractStructors(className, dispatch) \
1924 _OS_ADD_OPERATOR_PROTO
1925
1926#define OSDeclareAbstractStructorsWithDispatchAndNoOperators( \
1927 className) \
1928 _OSDeclareAbstractStructors(className, dispatch)
1929
1930
1931/*!
1932 * @define OSDeclareFinalStructors
1933 * @hidecontents
1934 *
1935 * @abstract
1936 * Declares run-time type information and functions
1937 * for a concrete Libkern C++ class.
1938 *
1939 * @param className The name of the C++ class, as a raw token,
1940 * <i>not</i> a string or macro.
1941 *
1942 * @discussion
1943 * Final Libkern C++ classes--those that do not allow subclassing--should
1944 * "call" this macro immediately after the opening brace in a class declaration.
1945 * (Final classes in the kernel may actually have subclasses in the kernel,
1946 * but kexts cannot define any subclasses of a final class.)
1947 * It leaves the current privacy state as <code>protected:</code>.
1948 *
1949 * <b>Note:</b> If the class is exported by a pseudokext (symbol set),
1950 * the final symbol generated by this macro must be exported
1951 * for the final-class attribute to be enforced.
1952 *
1953 * <b>Warning:</b> Changing a class from "Default" to "Final" will break
1954 * binary compatibility.
1955 */
1956#define _OSDeclareFinalStructors(className, dispatch) \
1957 _OSDeclareDefaultStructors(className, dispatch) \
1958 private: \
1959 void __OSFinalClass(void); \
1960 protected:
1961
1962#define OSDeclareFinalStructors(className) \
1963 _OSDeclareFinalStructors(className, )
1964
1965#define OSDeclareFinalStructorsWithDispatch(className) \
1966 _OSDeclareFinalStructors(className, dispatch)
1967
1968
1969/* Not to be included in headerdoc.
1970 *
1971 * @define OSDefineMetaClassWithInit
1972 * @hidecontents
1973 *
1974 * @abstract
1975 * Helper macro for for the standard metaclass-registration macros.
1976 * DO NOT USE.
1977 *
1978 * @param className The name of the C++ class, as a raw token,
1979 * <i>not</i> a string or macro.
1980 * @param superclassName The name of the superclass of the C++ class,
1981 * as a raw token,
1982 * <i>not</i> a string or macro.
1983 * @param init A function to call in the constructor
1984 * of the class's OSMetaClass.
1985 *
1986 * @discussion
1987 * <b>Note:</b> Needs to be followed by
1988 * <code>OSMetaClassConstructorInit</code> or
1989 * <code>OSMetaClassConstructorInitWithZone</code> for initialization
1990 * of class's <code>OSMetaClass</code> constructor.
1991 */
1992#define OSMetaClassConstructorInit(className, superclassName, \
1993 init) \
1994 /* The ::MetaClass constructor */ \
1995 className ::MetaClass::MetaClass() \
1996 : OSMetaClass(#className, className::superClass, \
1997 sizeof(className)) \
1998 { init; }
1999
2000#ifdef XNU_KERNEL_PRIVATE
2001#define declareZone(className) \
2002 static SECURITY_READ_ONLY_LATE(zone_t) className ## _zone;
2003#elif KERNEL_PRIVATE /* XNU_KERNEL_PRIVATE */
2004#define declareZone(className) \
2005 static zone_t className ## _zone;
2006#endif /* KERNEL_PRIVATE */
2007
2008#ifdef KERNEL_PRIVATE
2009#define OSMetaClassConstructorInitWithZone(className, \
2010 superclassName, init, zflags) \
2011 declareZone(className) \
2012 /* The ::MetaClass constructor */ \
2013 className ::MetaClass::MetaClass() \
2014 : OSMetaClass(#className, className::superClass, \
2015 sizeof(className), \
2016 &(className ## _zone), \
2017 "iokit." #className, zflags) \
2018 { init; }
2019#endif /* KERNEL_PRIVATE */
2020
2021#define OSDefineMetaClassWithInit(className, superclassName, \
2022 init) \
2023 /* Class global data */ \
2024 className ::MetaClass className ::gMetaClass; \
2025 const OSMetaClass * const className ::metaClass = \
2026 & className ::gMetaClass; \
2027 const OSMetaClass * const className ::superClass = \
2028 & superclassName ::gMetaClass; \
2029 /* Class member functions */ \
2030 className :: className(const OSMetaClass *meta) \
2031 : superclassName (meta) { } \
2032 className ::~ className() { } \
2033 const OSMetaClass * className ::getMetaClass() const \
2034 { return &gMetaClass; }
2035
2036
2037/* Not to be included in headerdoc.
2038 *
2039 * @define OSDefineAbstractStructors
2040 * @hidecontents
2041 *
2042 * @abstract
2043 * Helper macro for for the standard metaclass-registration macros.
2044 * DO NOT USE.
2045 *
2046 * @param className The name of the C++ class, as a raw token,
2047 * <i>not</i> a string or macro.
2048 * @param superclassName The name of the superclass of the C++ class,
2049 * as a raw token,
2050 * <i>not</i> a string or macro.
2051 */
2052#define OSDefineAbstractStructors(className, superclassName) \
2053 OSObject * className ::MetaClass::alloc() const { return NULL; }
2054
2055
2056/* Not to be included in headerdoc.
2057 *
2058 * @define OSDefineDefaultStructors
2059 * @hidecontents
2060 *
2061 * @abstract
2062 * Helper macro for for the standard metaclass-registration macros.
2063 * DO NOT USE.
2064 *
2065 * @param className The name of the C++ class, as a raw token,
2066 * <i>not</i> a string or macro.
2067 * @param superclassName The name of the superclass of the C++ class,
2068 * as a raw token,
2069 * <i>not</i> a string or macro.
2070 */
2071#define OSDefineBasicStructors(className, superclassName) \
2072 OSObject * className ::MetaClass::alloc() const \
2073 { return new className; } \
2074 className :: className () : superclassName (&gMetaClass) \
2075 { gMetaClass.instanceConstructed(); }
2076
2077#ifdef KERNEL_PRIVATE
2078#define OSDefineOperatorMethods(className) \
2079 static KALLOC_TYPE_DEFINE(className ## _ktv, className, \
2080 KT_DEFAULT); \
2081 void * className::operator new(size_t size) { \
2082 return OSObject_typed_operator_new(className ## _ktv, \
2083 size); \
2084 } \
2085 void className::operator delete(void *mem, size_t size) { \
2086 return OSObject_typed_operator_delete(className ## _ktv, \
2087 mem, size); \
2088 }
2089#else
2090#define OSDefineOperatorMethods(className) \
2091 void * className::operator new(size_t size) { \
2092 return OSObject::operator new(size); \
2093 } \
2094 void className::operator delete(void *mem, size_t size) { \
2095 return OSObject::operator delete(mem, size); \
2096 }
2097#endif
2098
2099#ifdef KERNEL_PRIVATE
2100#define OSDefineOperatorMethodsWithZone(className) \
2101 void * className :: operator new(size_t size) { \
2102 if (className ## _zone) { \
2103 return zalloc_flags(className ## _zone, \
2104 (zalloc_flags_t) (Z_WAITOK | Z_ZERO));\
2105 } else { \
2106 return OSObject::operator new(size); \
2107 } \
2108 } \
2109 void className :: operator delete(void *mem, size_t size) { \
2110 if (className ## _zone) { \
2111 kern_os_zfree(className ## _zone, mem, size); \
2112 } else { \
2113 return OSObject::operator delete(mem, size); \
2114 } \
2115 }
2116#endif /* KERNEL_PRIVATE */
2117
2118#define OSDefineDefaultStructors(className, superclassName) \
2119 OSDefineBasicStructors(className, superclassName) \
2120 OSDefineOperatorMethods(className)
2121
2122
2123/* Not to be included in headerdoc.
2124 *
2125 * @define OSDefineDefaultStructors
2126 * @hidecontents
2127 *
2128 * @abstract
2129 * Helper macro for for the standard metaclass-registration macros.
2130 * DO NOT USE.
2131 *
2132 * @param className The name of the C++ class, as a raw token,
2133 * <i>not</i> a string or macro.
2134 * @param superclassName The name of the superclass of the C++ class,
2135 * as a raw token,
2136 * <i>not</i> a string or macro.
2137 */
2138#define OSDefineFinalStructors(className, superclassName) \
2139 OSDefineBasicStructors(className, superclassName) \
2140 void className ::__OSFinalClass(void) { }
2141
2142
2143/* Not to be included in headerdoc.
2144 *
2145 * @define OSDefineMetaClassAndStructorsWithInit
2146 * @hidecontents
2147 *
2148 * @abstract
2149 * Helper macro for for the standard metaclass-registration macros.
2150 * DO NOT USE.
2151 *
2152 * @param className The name of the C++ class, as a raw token,
2153 * <i>not</i> a string or macro.
2154 * @param superclassName The name of the superclass of the C++ class,
2155 * as a raw token,
2156 * <i>not</i> a string or macro.
2157 * @param init A function to call in the constructor
2158 * of the class's OSMetaClass.
2159 */
2160#define OSDefineMetaClassAndStructorsWithInit(className, \
2161 superclassName, init) \
2162 OSDefineMetaClassWithInit(className, superclassName, init) \
2163 OSMetaClassConstructorInit(className, superclassName, init) \
2164 OSDefineDefaultStructors(className, superclassName)
2165
2166#ifdef KERNEL_PRIVATE
2167/* Not to be included in headerdoc.
2168 *
2169 * @define OSDefineMetaClassAndStructorsWithInitWithZone
2170 * @hidecontents
2171 *
2172 * @abstract
2173 * Helper macro for for the standard metaclass-registration macros.
2174 * DO NOT USE.
2175 *
2176 * @param className The name of the C++ class, as a raw token,
2177 * <i>not</i> a string or macro.
2178 * @param superclassName The name of the superclass of the C++ class,
2179 * as a raw token,
2180 * <i>not</i> a string or macro.
2181 * @param init A function to call in the constructor
2182 * of the class's OSMetaClass.
2183 * @param zflags Zone creation flags.
2184 *
2185 * @discussion
2186 * In addition to what
2187 * <code>OSDefineMetaClassAndStructorsWithInit</code> does this
2188 * macro implements operator new and delete to use zalloc rather
2189 * than kalloc. Objects of this class get will reside in their
2190 * own zone rather than share VA with other objects.
2191 */
2192#define OSDefineMetaClassAndStructorsWithInitAndZone(className, \
2193 superclassName, init, zflags) \
2194 OSDefineMetaClassWithInit(className, superclassName, init) \
2195 OSMetaClassConstructorInitWithZone(className, \
2196 superclassName, init, zflags) \
2197 OSDefineBasicStructors(className, superclassName) \
2198 OSDefineOperatorMethodsWithZone(className)
2199#endif /* KERNEL_PRIVATE */
2200
2201/* Not to be included in headerdoc.
2202 *
2203 * @define OSDefineMetaClassAndAbstractStructorsWithInit
2204 * @hidecontents
2205 *
2206 * @abstract
2207 * Helper macro for for the standard metaclass-registration macros.
2208 * DO NOT USE.
2209 *
2210 * @param className The name of the C++ class, as a raw token,
2211 * <i>not</i> a string or macro.
2212 * @param superclassName The name of the superclass of the C++ class,
2213 * as a raw token,
2214 * <i>not</i> a string or macro.
2215 * @param init A function to call in the constructor
2216 * of the class's OSMetaClass.
2217 */
2218#define OSDefineMetaClassAndAbstractStructorsWithInit( \
2219 className, superclassName, init) \
2220 OSDefineMetaClassWithInit(className, superclassName, init) \
2221 OSMetaClassConstructorInit(className, superclassName, init) \
2222 OSDefineAbstractStructors(className, superclassName) \
2223 OSDefineOperatorMethods(className)
2224
2225
2226/* Not to be included in headerdoc.
2227 *
2228 * @define OSDefineMetaClassAndFinalStructorsWithInit
2229 * @hidecontents
2230 *
2231 * @abstract
2232 * Helper macro for for the standard metaclass-registration macros.
2233 * DO NOT USE.
2234 *
2235 * @param className The name of the C++ class, as a raw token,
2236 * <i>not</i> a string or macro.
2237 * @param superclassName The name of the superclass of the C++ class,
2238 * as a raw token,
2239 * <i>not</i> a string or macro.
2240 * @param init A function to call in the constructor
2241 * of the class's OSMetaClass.
2242 */
2243#define OSDefineMetaClassAndFinalStructorsWithInit(className, \
2244 superclassName, init) \
2245 OSDefineMetaClassWithInit(className, superclassName, init) \
2246 OSMetaClassConstructorInit(className, superclassName, init) \
2247 OSDefineFinalStructors(className, superclassName) \
2248 OSDefineOperatorMethods(className)
2249
2250#ifdef KERNEL_PRIVATE
2251/* Not to be included in headerdoc.
2252 *
2253 * @define OSDefineMetaClassAndFinalStructorsWithInitAndZone
2254 * @hidecontents
2255 *
2256 * @abstract
2257 * Helper macro for for the standard metaclass-registration macros.
2258 * DO NOT USE.
2259 *
2260 * @param className The name of the C++ class, as a raw token,
2261 * <i>not</i> a string or macro.
2262 * @param superclassName The name of the superclass of the C++ class,
2263 * as a raw token,
2264 * <i>not</i> a string or macro.
2265 * @param init A function to call in the constructor
2266 * of the class's OSMetaClass.
2267 * @param zflags Zone creation flags.
2268 *
2269 * @discussion
2270 * In addition to what
2271 * <code><OSDefineMetaClassAndFinalStructorsWithInit/code> does this
2272 * macro implements operator new and delete to use zalloc rather
2273 * than kalloc. Objects of this class get will reside in their
2274 * own zone rather than share VA with other objects.
2275 */
2276#define OSDefineMetaClassAndFinalStructorsWithInitAndZone( \
2277 className, superclassName, init, zflags) \
2278 OSDefineMetaClassWithInit(className, superclassName, init) \
2279 OSMetaClassConstructorInitWithZone(className, \
2280 superclassName, init, zflags) \
2281 OSDefineFinalStructors(className, superclassName) \
2282 OSDefineOperatorMethodsWithZone(className)
2283#endif
2284
2285/* Helpers */
2286
2287/* Not to be included in headerdoc.
2288 *
2289 * @define OSDefineMetaClass
2290 * @hidecontents
2291 *
2292 * @abstract
2293 * Helper macro for for the standard metaclass-registration macros.
2294 * DO NOT USE.
2295 *
2296 * @param className The name of the C++ class, as a raw token,
2297 * <i>not</i> a string or macro.
2298 * @param superclassName The name of the superclass of the C++ class,
2299 * as a raw token,
2300 * <i>not</i> a string or macro.
2301 * @param init A function to call in the constructor
2302 * of the class's OSMetaClass.
2303 */
2304#define OSDefineMetaClass(className, superclassName) \
2305 OSDefineMetaClassWithInit(className, superclassName, ) \
2306 OSMetaClassConstructorInit(className, superclassName, ) \
2307 OSDefineOperatorMethods(className)
2308
2309
2310/*!
2311 * @define OSDefineMetaClassAndStructors
2312 * @hidecontents
2313 *
2314 * @abstract
2315 * Defines an OSMetaClass and associated routines
2316 * for a concrete Libkern C++ class.
2317 *
2318 * @param className The name of the C++ class, as a raw token,
2319 * <i>not</i> a string or macro.
2320 * @param superclassName The name of the superclass of the C++ class,
2321 * as a raw token,
2322 * <i>not</i> a string or macro.
2323 *
2324 * @discussion
2325 * Concrete Libkern C++ classes should "call" this macro
2326 * at the beginning of their implementation files,
2327 * before any function implementations for the class.
2328 */
2329#define OSDefineMetaClassAndStructors(className, superclassName) \
2330 OSDefineMetaClassAndStructorsWithInit(className, \
2331 superclassName, )
2332
2333#ifdef KERNEL_PRIVATE
2334/*!
2335 * @define OSDefineMetaClassAndStructorsWithZone
2336 * @hidecontents
2337 *
2338 * @abstract
2339 * Defines an OSMetaClass and associated routines
2340 * for a concrete Libkern C++ class.
2341 *
2342 * @param className The name of the C++ class, as a raw token,
2343 * <i>not</i> a string or macro.
2344 * @param superclassName The name of the superclass of the C++ class,
2345 * as a raw token,
2346 * <i>not</i> a string or macro.
2347 * @param zflags Zone creation flags.
2348 *
2349 * @discussion
2350 * In addition to what
2351 * <code><OSDefineMetaClassAndStructorsWithInit/code> does this
2352 * macro implements operator new and delete to use zalloc rather
2353 * than kalloc. Objects of this class get will reside in their
2354 * own zone rather than share VA with other objects.
2355 */
2356#define OSDefineMetaClassAndStructorsWithZone(className, \
2357 superclassName, zflags) \
2358 OSDefineMetaClassAndStructorsWithInitAndZone(className, \
2359 superclassName, , zflags)
2360#endif
2361
2362/*!
2363 * @define OSDefineMetaClassAndAbstractStructors
2364 * @hidecontents
2365 *
2366 * @abstract
2367 * Defines an OSMetaClass and associated routines
2368 * for an abstract Libkern C++ class.
2369 *
2370 * @param className The name of the C++ class, as a raw token,
2371 * <i>not</i> a string or macro.
2372 * @param superclassName The name of the superclass of the C++ class,
2373 * as a raw token,
2374 * <i>not</i> a string or macro.
2375 *
2376 * @discussion
2377 * Abstract Libkern C++ classes--those with at least one
2378 * pure virtual method--should "call" this macro
2379 * at the beginning of their implementation files,
2380 * before any function implementations for the class.
2381 */
2382#define OSDefineMetaClassAndAbstractStructors(className, \
2383 superclassName) \
2384 OSDefineMetaClassAndAbstractStructorsWithInit (className, \
2385 superclassName, )
2386
2387
2388/*!
2389 * @define OSDefineMetaClassAndFinalStructors
2390 * @hidecontents
2391 *
2392 * @abstract
2393 * Defines an OSMetaClass and associated routines
2394 * for concrete Libkern C++ class.
2395 *
2396 * @param className The name of the C++ class, as a raw token,
2397 * <i>not</i> a string or macro.
2398 * @param superclassName The name of the superclass of the C++ class,
2399 * as a raw token,
2400 * <i>not</i> a string or macro.
2401 *
2402 * @discussion
2403 * Final Libkern C++ classes--those that do not allow
2404 * subclassing--should "call" this macro at the beginning
2405 * of their implementation files,
2406 * before any function implementations for the class.
2407 * (Final classes in the kernel may actually have subclasses in the kernel,
2408 * but kexts cannot define any subclasses of a final class.)
2409 *
2410 * <b>Note:</b> If the class is exported by a pseudokext (symbol set),
2411 * the final symbol generated by this macro must be exported
2412 * for the final-class attribute to be enforced.
2413 *
2414 * <b>Warning:</b> Changing a class from "Default" to "Final" will break
2415 * binary compatibility.
2416 */
2417#define OSDefineMetaClassAndFinalStructors(className, \
2418 superclassName) \
2419 OSDefineMetaClassAndFinalStructorsWithInit(className, \
2420 superclassName, )
2421
2422#ifdef KERNEL_PRIVATE
2423/*!
2424 * @define OSDefineMetaClassAndFinalStructorsWithZone
2425 * @hidecontents
2426 *
2427 * @abstract
2428 * Defines an OSMetaClass and associated routines
2429 * for concrete Libkern C++ class.
2430 *
2431 * @param className The name of the C++ class, as a raw token,
2432 * <i>not</i> a string or macro.
2433 * @param superclassName The name of the superclass of the C++ class,
2434 * as a raw token,
2435 * <i>not</i> a string or macro.
2436 * @param zflags Zone creation flags.
2437 *
2438 * @discussion
2439 * In addition to what
2440 * <code>OSDefineMetaClassAndFinalStructors</code> does this
2441 * macro implements operator new and delete to use zalloc rather
2442 * than kalloc. Objects of this class get will reside in their
2443 * own zone rather than share VA with other objects.
2444 */
2445#define OSDefineMetaClassAndFinalStructorsWithZone(className, \
2446 superclassName, zflags) \
2447 OSDefineMetaClassAndFinalStructorsWithInitAndZone( \
2448 className, superclassName, , zflags)
2449#endif /* KERNEL_PRIVATE */
2450
2451
2452// Dynamic vtable patchup support routines and types
2453 void reservedCalled(int ind) const;
2454
2455
2456/*!
2457 * @define OSMetaClassDeclareReservedUnused
2458 * @hidecontents
2459 *
2460 * @abstract
2461 * Reserves vtable space for new virtual functions
2462 * in a Libkern C++ class.
2463 *
2464 * @param className The name of the C++ class, as a raw token,
2465 * <i>not</i> a string or macro.
2466 * @param index The numeric index of the vtable slot,
2467 * as a raw constant, beginning from 0.
2468 *
2469 * @discussion
2470 * Libkern C++ classes in kernel extensions that can be used as libraries
2471 * can provide for backward compatibility by declaring a number
2472 * of reserved vtable slots
2473 * that can be replaced with new functions as they are added.
2474 * Each reserved declaration must be accompanied in the implementation
2475 * by a corresponding reference to
2476 * <code>@link OSMetaClassDefineReservedUnused
2477 * OSMetaClassDefineReservedUnused@/link</code>.
2478 *
2479 * When replacing a reserved slot, change the macro from "Unused"
2480 * to "Used" to document the fact that the slot used to be reserved,
2481 * and declare the new function immediately after the "Used" macro
2482 * to preserve vtable ordering.
2483 * See
2484 * <code>@link OSMetaClassDeclareReservedUsed
2485 * OSMetaClassDeclareReservedUsed@/link</code>.
2486 */
2487#if APPLE_KEXT_VTABLE_PADDING
2488#define OSMetaClassDeclareReservedUnused(className, index) \
2489 virtual void _RESERVED ## className ## index ()
2490#else
2491#define OSMetaClassDeclareReservedUnused(className, index)
2492#endif
2493
2494
2495/*!
2496 * @define OSMetaClassDeclareReservedUsed
2497 * @hidecontents
2498 *
2499 * @abstract
2500 * Documents use of reserved vtable space for new virtual functions
2501 * in a Libkern C++ class.
2502 *
2503 * @param className The name of the C++ class, as a raw token,
2504 * <i>not</i> a string or macro.
2505 * @param index The numeric index of the vtable slot,
2506 * as a raw constant, beginning from 0.
2507 *
2508 * @discussion
2509 * This macro evaluates to nothing, and is used to document reserved
2510 * vtable slots as they are filled.
2511 * See
2512 * <code>@link OSMetaClassDeclareReservedUnused
2513 * OSMetaClassDeclareReservedUnused@/link</code>.
2514 */
2515#define OSMetaClassDeclareReservedUsed(className, index)
2516#define OSMetaClassDeclareReservedUsedARM(className, x86index, armindex)
2517
2518
2519/*!
2520 * @define OSMetaClassDefineReservedUnused
2521 * @hidecontents
2522 *
2523 * @abstract
2524 * Defines a reserved vtable slot for a Libkern C++ class.
2525 *
2526 * @param className The name of the C++ class, as a raw token,
2527 * <i>not</i> a string or macro.
2528 * @param index The numeric index of the vtable slot,
2529 * as a raw constant, beginning from 0.
2530 *
2531 * @discussion
2532 * Libkern C++ classes in kernel extensions that can be used as libraries
2533 * can provide for backward compatibility by declaring a number
2534 * of reserved vtable slots
2535 * that can be replaced with new functions as they are added.
2536 * Each reserved defintion accompanies
2537 * a corresponding declaration created with
2538 * <code>@link OSMetaClassDeclareReservedUnused
2539 * OSMetaClassDeclareReservedUnused@/link</code>.
2540 *
2541 * This macro is used in the implementation file
2542 * to provide a placeholder definition for the reserved vtable slot,
2543 * as a function that calls <code>panic</code> with an error message.
2544 *
2545 * When replacing a reserved slot, change the macro from "Unused"
2546 * to "Used" to document the fact that the slot used to be reserved,
2547 * and declare the new function immediately after the "Used" macro
2548 * to preserve vtable ordering.
2549 * See
2550 * <code>@link OSMetaClassDefineReservedUsed
2551 * OSMetaClassDefineReservedUsed@/link</code>.
2552 */
2553#if APPLE_KEXT_VTABLE_PADDING
2554#define OSMetaClassDefineReservedUnused(className, index) \
2555void className ::_RESERVED ## className ## index () \
2556 { gMetaClass.reservedCalled(index); }
2557#else
2558#define OSMetaClassDefineReservedUnused(className, index)
2559#endif
2560
2561
2562/*!
2563 * @define OSMetaClassDefineReservedUsed
2564 * @hidecontents
2565 *
2566 * @abstract
2567 * Reserves vtable space for new virtual functions in a Libkern C++ class.
2568 *
2569 * @param className The name of the C++ class, as a raw token,
2570 * <i>not</i> a string or macro.
2571 * @param index The numeric index of the vtable slot,
2572 * as a raw constant, beginning from 0.
2573 *
2574 * @discussion
2575 * This macro evaluates to nothing, and is used to document reserved
2576 * vtable slots as they are filled.
2577 * See
2578 * <code>@link OSMetaClassDefineReservedUnused
2579 * OSMetaClassDefineReservedUnused@/link</code>.
2580 */
2581#define OSMetaClassDefineReservedUsed(className, index)
2582#define OSMetaClassDefineReservedUsedARM(className, x86index, armindex)
2583
2584/*
2585 * OSMetaClassDeclareReservedUsedX86 needs to be placed with the unused vtable
2586 * slots since it will unused on arm targets.
2587 */
2588#if defined(__arm64__) || defined(__arm__)
2589#define OSMetaClassDeclareReservedUsedX86 OSMetaClassDeclareReservedUnused
2590#define OSMetaClassDefineReservedUsedX86 OSMetaClassDefineReservedUnused
2591#else
2592#define OSMetaClassDeclareReservedUsedX86 OSMetaClassDeclareReservedUsed
2593#define OSMetaClassDefineReservedUsedX86 OSMetaClassDefineReservedUsed
2594
2595#endif
2596
2597// I/O Kit debug internal routines.
2598 static void printInstanceCounts();
2599 static void serializeClassDictionary(OSDictionary * dict);
2600#ifdef XNU_KERNEL_PRIVATE
2601#if IOTRACKING
2602public:
2603 static void * trackedNew(size_t size);
2604 static void trackedDelete(void * mem, size_t size);
2605 void trackedInstance(OSObject * instance) const;
2606 void trackedFree(OSObject * instance) const;
2607 void trackedAccumSize(OSObject * instance, size_t size) const;
2608 struct IOTrackingQueue * getTracking() const;
2609#endif /* IOTRACKING */
2610#endif /* XNU_KERNEL_PRIVATE */
2611
2612private:
2613// Obsolete APIs
2614 static OSDictionary * getClassDictionary();
2615 virtual bool serialize(OSSerialize * serializer) const;
2616
2617// Virtual Padding functions for MetaClass's
2618 OSMetaClassDeclareReservedUnused(OSMetaClass, 0);
2619 OSMetaClassDeclareReservedUnused(OSMetaClass, 1);
2620 OSMetaClassDeclareReservedUnused(OSMetaClass, 2);
2621 OSMetaClassDeclareReservedUnused(OSMetaClass, 3);
2622 OSMetaClassDeclareReservedUnused(OSMetaClass, 4);
2623 OSMetaClassDeclareReservedUnused(OSMetaClass, 5);
2624 OSMetaClassDeclareReservedUnused(OSMetaClass, 6);
2625 OSMetaClassDeclareReservedUnused(OSMetaClass, 7);
2626};
2627
2628#endif /* !_LIBKERN_OSMETACLASS_H */
2629