/*
- * Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
+ * Copyright (c) 2000-2016 Apple Inc. All rights reserved.
*
- * @APPLE_LICENSE_HEADER_START@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
- * The contents of this file constitute Original Code as defined in and
- * are subject to the Apple Public Source License Version 1.1 (the
- * "License"). You may not use this file except in compliance with the
- * License. Please obtain a copy of the License at
- * http://www.apple.com/publicsource and read it before using this file.
+ * This file contains Original Code and/or Modifications of Original Code
+ * as defined in and that are subject to the Apple Public Source License
+ * Version 2.0 (the 'License'). You may not use this file except in
+ * compliance with the License. The rights granted to you under the License
+ * may not be used to create, or enable the creation or redistribution of,
+ * unlawful or unlicensed copies of an Apple operating system, or to
+ * circumvent, violate, or enable the circumvention or violation of, any
+ * terms of an Apple operating system software license agreement.
*
- * This Original Code and all software distributed under the License are
- * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+ * Please obtain a copy of the License at
+ * http://www.opensource.apple.com/apsl/ and read it before using this file.
+ *
+ * The Original Code and all software distributed under the License are
+ * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
- * License for the specific language governing rights and limitations
- * under the License.
+ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+ * Please see the License for the specific language governing rights and
+ * limitations under the License.
*
- * @APPLE_LICENSE_HEADER_END@
+ * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
#ifndef _LIBKERN_OSMETACLASS_H
#define _LIBKERN_OSMETACLASS_H
class OSSymbol;
class OSDictionary;
class OSSerialize;
+#ifdef XNU_KERNEL_PRIVATE
+class OSOrderedSet;
+class OSCollection;
+#endif /* XNU_KERNEL_PRIVATE */
+
-#if __GNUC__ < 3
+/*!
+ * @header
+ *
+ * @abstract
+ * This header declares the OSMetaClassBase and OSMetaClass classes,
+ * which together form the basis of the Libkern and I/O Kit C++ class hierarchy
+ * and run-time type information facility.
+ */
+
+
+/*! @parseOnly */
#define APPLE_KEXT_COMPATIBILITY
+
+#ifdef XNU_KERNEL_PRIVATE
+
+#ifdef CONFIG_EMBEDDED
+#define APPLE_KEXT_VTABLE_PADDING 0
+#else /* CONFIG_EMBEDDED */
+/*! @parseOnly */
+#define APPLE_KEXT_VTABLE_PADDING 1
+#endif /* CONFIG_EMBEDDED */
+
+#else /* XNU_KERNEL_PRIVATE */
+#include <TargetConditionals.h>
+
+#if TARGET_OS_EMBEDDED
+#define APPLE_KEXT_VTABLE_PADDING 0
+#else /* TARGET_OS_EMBEDDED */
+/*! @parseOnly */
+#define APPLE_KEXT_VTABLE_PADDING 1
+#endif /* TARGET_OS_EMBEDDED */
+
+#endif /* XNU_KERNEL_PRIVATE */
+
+#define APPLE_KEXT_ALIGN_CONTAINERS (0 == APPLE_KEXT_VTABLE_PADDING)
+
+#if defined(__LP64__)
+/*! @parseOnly */
+#define APPLE_KEXT_LEGACY_ABI 0
+#elif defined(__arm__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 2))
+#define APPLE_KEXT_LEGACY_ABI 0
#else
-#define APPLE_KEXT_COMPATIBILITY __attribute__ ((apple_kext_compatibility))
+#define APPLE_KEXT_LEGACY_ABI 1
#endif
+#if defined(__LP64__)
+/*! @parseOnly */
+#define APPLE_KEXT_COMPATIBILITY_VIRTUAL
+#else
+// private method made virtual only for binary compatibility
+#define APPLE_KEXT_COMPATIBILITY_VIRTUAL virtual
+#endif
+
+/*! @parseOnly */
+#define APPLE_KEXT_DEPRECATED __attribute__((deprecated))
+
+
+#if __cplusplus >= 201103L
+#define APPLE_KEXT_OVERRIDE override
+#if defined(__LP64__)
+#define APPLE_KEXT_COMPATIBILITY_OVERRIDE
+#else
+#define APPLE_KEXT_COMPATIBILITY_OVERRIDE APPLE_KEXT_OVERRIDE
+#endif
+#else
+#define APPLE_KEXT_OVERRIDE
+#define APPLE_KEXT_COMPATIBILITY_OVERRIDE
+#endif
+
+
+/*!
+ * @class OSMetaClassBase
+ *
+ * @abstract
+ * OSMetaClassBase is the abstract bootstrap class
+ * for the Libkern and I/O Kit run-time type information system.
+ *
+ * @discussion
+ * OSMetaClassBase is the abstract C++ root class
+ * underlying the entire Libkern and I/O Kit class hierarchy.
+ * It defines the run-time type information system,
+ * including dynamic class allocation and safe type-casting,
+ * as well as the abstract interface for reference counting
+ * and a few other utility functions.
+ * OSMetaClassBase is the immediate superclass of
+ * @link //apple_ref/doc/class/OSObject OSObject@/link and
+ * @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link;
+ * no other class should derive from OSMetaClassBase.
+ *
+ * For more information, see
+ * <i>@link //apple_ref/doc/uid/TP40002799
+ * I/O Kit Device Driver Design Guidelines@/link</i>.
+ *
+ * <b>Use by Kernel Extensions</b>
+ *
+ * Kernel Extensions should never interact directly with OSMetaClassBase,
+ * but they will find useful several macros that tie in
+ * to the run-time type information system, specifically:
+ * <ul>
+ * <li><code>@link OSTypeAlloc OSTypeAlloc@/link</code> - allocation of new instances</li>
+ * <li><code>@link OSDynamicCast OSDynamicCast@/link</code> - safe type casting</li>
+ * <li><code>@link OSCheckTypeInst OSCheckTypeInst@/link</code> -
+ * checking for inheritance/derivation</li>
+ * <li><code>@link OSMemberFunctionCast OSMemberFunctionCast@/link</code> -
+ * casting C++ member functions to C function pointers
+ * for registration as callbacks</li>
+ * </ul>
+ *
+ * See @link //apple_ref/doc/class/OSMetaClass OSMetaClass@/link
+ * for more run-time type information interfaces.
+ *
+ * <b>Use Restrictions</b>
+ *
+ * OSMetaClassBase should not be subclassed by kernel extensions,
+ * nor should kernel extensions call its run-time type functions directly.
+ *
+ * The run-time type functions and macros are <b>not safe</b>
+ * to call in a primary interrupt context.
+ *
+ * <b>Concurrency Protection</b>
+ *
+ * The run-time type macros and functions of OSMetaClassBase are thread-safe.
+ */
class OSMetaClassBase
{
public:
-/*! @function OSTypeAlloc
- @abstract Allocate an instance of the desired object.
- @discussion The OSTypeAlloc macro can be used to break the binary compatibility difficulties presented by new. The problem is that C++ compiles the knowledge of the size of the class into the cade calling new. If you use the alloc code however the class size is determined by the callee not the caller.
- @param type Name of the desired type to be created.
- @result 'this' if object cas been successfully created.
-*/
-#define OSTypeAlloc(type) ((type *) ((type::metaClass)->alloc()))
-
-/*! @function OSTypeID
- @abstract Given the name of a class return it's typeID
- @param type Name of the desired type, eg. OSObject.
- @result A unique Type ID for the class.
-*/
-#define OSTypeID(type) (type::metaClass)
-
-/*! @function OSTypeIDInst
- @abstract Given a pointer to an object return it's typeID
- @param typeinst An instance of an OSObject subclass.
- @result The typeID, ie. OSMetaClass *.
-*/
-#define OSTypeIDInst(typeinst) ((typeinst)->getMetaClass())
-
-/*! @function OSDynamicCast
- @abstract Roughly analogous to (type *) inst, but check if valid first.
- @discussion OSDynamicCast is an attempt to implement a rudimentary equivalent to rtti's dynamic_cast<T> operator. Embedded-C++ doesn't allow the use of rtti. OSDynamicCast is build on the OSMetaClass mechanism. Note it is safe to call this with a 0 parameter.
- @param type name of desired class name. Notice that it is assumed that you desire to cast to a pointer to an object of this type. Also type qualifiers, like const, are not recognized and will cause an, usually obscure, compile error.
- @param inst Pointer to object that you wish to attempt to type cast. May be 0.
- @result inst if object non-zero and it is of the desired type, otherwise 0.
-*/
-#define OSDynamicCast(type, inst) \
+
+
+ /*!
+ * @define OSTypeAlloc
+ * @hidecontents
+ *
+ * @abstract
+ * Allocates an instance of the named object class.
+ *
+ * @param type The name of the desired class to be created,
+ * as a raw token, <i>not</i> a string or macro.
+ *
+ * @result
+ * A pointer to the new, uninitialized object on success;
+ * <code>NULL</code> on failure.
+ *
+ * @discussion
+ * See also
+ * <code>@link
+ * //apple_ref/cpp/clm/OSMetaClass/allocClassWithName/staticOSObject*\/(constchar*)
+ * OSMetaClass::allocClassWithName(const char *)@/link</code>
+ * and
+ * <code>@link
+ * //apple_ref/cpp/instm/OSMetaClass/alloc/virtualOSObject*\/()
+ * OSMetaClass::alloc@/link</code>.
+ *
+ * The OSTypeAlloc macro is used to avoid binary compatibility difficulties
+ * presented by the C++ <code>new</code> operator.
+ */
+#define OSTypeAlloc(type) ((type *) ((type::metaClass)->alloc()))
+
+
+ /*!
+ * @define OSTypeID
+ * @hidecontents
+ *
+ * @abstract
+ * Returns the type ID (metaclass) of a class based on its name.
+ *
+ * @param type The name of the desired class, as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @result
+ * The unique type ID (metaclass) for the class.
+ *
+ * @discussion
+ * It is typically more useful to determine whether a class is derived
+ * from another; see
+ * <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code>
+ * and
+ * <code>@link //apple_ref/cpp/macro/OSCheckTypeInst OSCheckTypeInst@/link</code>.
+ */
+#define OSTypeID(type) (type::metaClass)
+
+
+ /*!
+ * @define OSTypeIDInst
+ * @hidecontents
+ *
+ * @abstract
+ * Returns the type ID (metaclass) for the class of an object instance.
+ *
+ * @param typeinst An instance of an OSObject subclass.
+ *
+ * @result
+ * The type ID of that object's class; that is, its metaclass.
+ *
+ * @discussion
+ * It is typically more useful to determine whether an object is derived
+ * from a particular class; see
+ * <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code>
+ * and
+ * <code>@link //apple_ref/cpp/macro/OSCheckTypeInst OSCheckTypeInst@/link</code>.
+ */
+#define OSTypeIDInst(typeinst) ((typeinst)->getMetaClass())
+
+
+ /*!
+ * @define OSDynamicCast
+ * @hidecontents
+ *
+ * @abstract
+ * Safe type-casting for Libkern C++ objects.
+ *
+ * @param type The name of the desired class type, as a raw token,
+ * <i>not</i> a string or macro.
+ * It is assumed you intend to cast to a pointer
+ * to an object of this type.
+ * Type qualifiers, such as <code>const</code>,
+ * are not recognized and will cause
+ * a (usually obscure) compile error.
+ * @param inst A pointer to the object instance to be cast.
+ * May be <code>NULL</code>.
+ *
+ * @result
+ * <code>inst</code> if it is non-<code>NULL</code>
+ * and derived from <code>type</code>;
+ * otherwise <code>NULL</code>.
+ *
+ * @discussion
+ * <code>OSDynamicCast</code> is a rough equivalent
+ * to the standard C++ RTTI <code>dynamic_cast<T></code> operator.
+ * Your code should use this instead of raw C type-casting,
+ * and check the resulting value.
+ * If the result is non-<code>NULL</code>,
+ * the object is safe to use as the type-cast class;
+ * if the result is <code>NULL</code>,
+ * the object does not derive from the type-cast class
+ * and your code should take appropriate steps to handle the error.
+ */
+#define OSDynamicCast(type, inst) \
((type *) OSMetaClassBase::safeMetaCast((inst), OSTypeID(type)))
-/*! @function OSCheckTypeInst
- @abstract Is the target object a subclass of the reference object?
- @param typeinst Reference instance of an object, desired type.
- @param inst Instance of object to check for type compatibility.
- @result false if typeinst or inst are 0 or inst is not a subclass of typeinst's class. true otherwise.
-*/
+
+ /*!
+ * @define OSCheckTypeInst
+ * @hidecontents
+ *
+ * @abstract
+ * Checks whether two objects are type-compatible.
+ *
+ * @param typeinst The reference object.
+ * @param inst The object to check for type compatibility.
+ *
+ * @result
+ * <code>true</code> if both <code>inst</code> and
+ * <code>typeinst</code> are non-<code>NULL</code>
+ * and <code>inst</code> is derived from the class of <code>typeinst</code>;
+ * otherwise <code>false</code>.
+ */
#define OSCheckTypeInst(typeinst, inst) \
OSMetaClassBase::checkTypeInst(inst, typeinst)
-
+
+#define OSSafeRelease(inst) \
+ do { int OSSafeRelease __attribute__ ((deprecated("Use OSSafeReleaseNULL"))); (OSSafeRelease); \
+ if (inst) (inst)->release(); } while (0)
+
+/*! @function OSSafeReleaseNULL
+ * @abstract Release an object if not <code>NULL</code>, then set it to <code>NULL</code>.
+ * @param inst Instance of an OSObject, may be <code>NULL</code>.
+ */
+#define OSSafeReleaseNULL(inst) do { if (inst) (inst)->release(); (inst) = NULL; } while (0)
+
+typedef void (*_ptf_t)(void);
+
+#if APPLE_KEXT_LEGACY_ABI
// Arcane evil code interprets a C++ pointer to function as specified in the
// -fapple-kext ABI, i.e. the gcc-2.95 generated code. IT DOES NOT ALLOW
// the conversion of functions that are from MULTIPLY inherited classes.
-typedef void (*_ptf_t)(void);
-
static inline _ptf_t
_ptmf2ptf(const OSMetaClassBase *self, void (OSMetaClassBase::*func)(void))
{
union {
- void (OSMetaClassBase::*fIn)(void);
- struct { // Pointer to member function 2.95
- unsigned short fToff;
- short fVInd;
- union {
- _ptf_t fPFN;
- short fVOff;
- } u;
- } fptmf2;
+ void (OSMetaClassBase::*fIn)(void);
+ struct { // Pointer to member function 2.95
+ unsigned short fToff;
+ short fVInd;
+ union {
+ _ptf_t fPFN;
+ short fVOff;
+ } u;
+ } fptmf2;
} map;
map.fIn = func;
- if (map.fptmf2.fToff)
- panic("Multiple inheritance is not supported");
- else if (map.fptmf2.fVInd < 0) {
- // Not virtual, i.e. plain member func
- return map.fptmf2.u.fPFN;
+ if (map.fptmf2.fToff) {
+ panic("Multiple inheritance is not supported");
+ return 0;
+ } else if (map.fptmf2.fVInd < 0) {
+ // Not virtual, i.e. plain member func
+ return map.fptmf2.u.fPFN;
} else {
- union {
- const OSMetaClassBase *fObj;
- _ptf_t **vtablep;
- } u;
- u.fObj = self;
-
- // Virtual member function so dereference vtable
- return (*u.vtablep)[map.fptmf2.fVInd - 1];
+ union {
+ const OSMetaClassBase *fObj;
+ _ptf_t **vtablep;
+ } u;
+ u.fObj = self;
+
+ // Virtual member function so dereference vtable
+ return (*u.vtablep)[map.fptmf2.fVInd - 1];
}
}
-/*! @function OSMemberFunctionCast
- @abstract Convert a pointer to a member function to a c-style pointer to function. No warnings are generated.
- @param type The type of pointer function desired.
- @param self The this pointer of the object whose function you wish to cache.
- @param func The pointer to member function itself, something like &Base::func.
- @result A pointer to function of the given type. This function will panic if an attempt is made to call it with a multiply inherited class.
-*/
+#else /* !APPLE_KEXT_LEGACY_ABI */
+#if defined(__arm__) || defined(__arm64__)
+typedef long int ptrdiff_t;
+/*
+ * Ugly reverse engineered ABI. Where does it come from? Nobody knows.
+ * <rdar://problem/5641129> gcc 4.2-built ARM kernel panics with multiple inheritance (no, really)
+ */
+static inline _ptf_t
+_ptmf2ptf(const OSMetaClassBase *self, void (OSMetaClassBase::*func)(void))
+{
+ struct ptmf_t {
+ _ptf_t fPFN;
+ ptrdiff_t delta;
+ };
+ union {
+ void (OSMetaClassBase::*fIn)(void);
+ struct ptmf_t pTMF;
+ } map;
+
+
+ map.fIn = func;
+
+ if (map.pTMF.delta & 1) {
+ // virtual
+ union {
+ const OSMetaClassBase *fObj;
+ _ptf_t **vtablep;
+ } u;
+ u.fObj = self;
+
+ // Virtual member function so dereference table
+ return *(_ptf_t *)(((uintptr_t)*u.vtablep) + (uintptr_t)map.pTMF.fPFN);
+ } else {
+ // Not virtual, i.e. plain member func
+ return map.pTMF.fPFN;
+ }
+}
+#elif defined(__i386__) || defined(__x86_64__)
+
+// Slightly less arcane and slightly less evil code to do
+// the same for kexts compiled with the standard Itanium C++
+// ABI
-#define OSMemberFunctionCast(cptrtype, self, func) \
- (cptrtype) OSMetaClassBase:: \
- _ptmf2ptf(self, (void (OSMetaClassBase::*)(void)) func)
+static inline _ptf_t
+_ptmf2ptf(const OSMetaClassBase *self, void (OSMetaClassBase::*func)(void))
+{
+ union {
+ void (OSMetaClassBase::*fIn)(void);
+ uintptr_t fVTOffset;
+ _ptf_t fPFN;
+ } map;
+
+ map.fIn = func;
+
+ if (map.fVTOffset & 1) {
+ // virtual
+ union {
+ const OSMetaClassBase *fObj;
+ _ptf_t **vtablep;
+ } u;
+ u.fObj = self;
+
+ // Virtual member function so dereference vtable
+ return *(_ptf_t *)(((uintptr_t)*u.vtablep) + map.fVTOffset - 1);
+ } else {
+ // Not virtual, i.e. plain member func
+ return map.fPFN;
+ }
+}
+
+#else
+#error Unknown architecture.
+#endif /* __arm__ */
+
+#endif /* !APPLE_KEXT_LEGACY_ABI */
+
+ /*!
+ * @define OSMemberFunctionCast
+ * @hidecontents
+ *
+ * @abstract
+ * Converts a C++ member function pointer, relative to an instance,
+ * to a C-style pointer to function.
+ *
+ * @param cptrtype The function type declaration to cast to
+ * (typically provided as a <code>typedef</code> by I/O KitKit classes).
+ * @param self The <code>this</code> pointer of the object whose function
+ * you wish to cache.
+ * @param func The pointer to the member function itself,
+ * something like <code>&Class::function</code>.
+ *
+ * @result
+ * A pointer to a function of the given type referencing <code>self</code>.
+ *
+ * @discussion
+ * This function is used to generate pointers to C++ functions for instances,
+ * such that they can be registered as callbacks with I/O Kit objects.
+ *
+ * No warnings are generated.
+ *
+ * This function will panic if an attempt is made to call it
+ * with a multiply-inheriting class.
+ */
+#define OSMemberFunctionCast(cptrtype, self, func) \
+ (cptrtype) OSMetaClassBase:: \
+ _ptmf2ptf(self, (void (OSMetaClassBase::*)(void)) func)
protected:
OSMetaClassBase();
private:
// Disable copy constructors of OSMetaClassBase based objects
-/*! @function operator =
- @abstract Disable implicit copy constructor by making private
- @param src Reference to source object that isn't allowed to be copied
-*/
+ /* Not to be included in headerdoc.
+ *
+ * @function operator =
+ *
+ * @abstract
+ * Disable implicit copy constructor by making private
+ *
+ * @param src Reference to source object that isn't allowed to be copied.
+ */
void operator =(OSMetaClassBase &src);
-/*! @function OSMetaClassBase
- @abstract Disable implicit copy constructor by making private
- @param src Reference to source object that isn't allowed to be copied
-*/
+ /* Not to be included in headerdoc.
+ *
+ * @function OSMetaClassBase
+ *
+ * @abstract
+ * Disable implicit copy constructor by making private
+ *
+ * @param src Reference to source object that isn't allowed to be copied.
+ */
OSMetaClassBase(OSMetaClassBase &src);
public:
-/*! @function release
- @abstract Primary implementation of the release mechanism.
- @discussion If $link retainCount <= the when argument then call $link free(). This indirect implementation of $link release allows the developer to break reference circularity. An example of this sort of problem is a parent/child mutual reference, either the parent or child can implement: void release() { release(2); } thus breaking the cirularity.
- @param when When retainCount == when then call free(). */
- virtual void release(int when) const = 0;
-
-/*! @function getRetainCount
- @abstract How many times has this object been retained?
- @result Current retain count
-*/
+
+// xx-review: the original comment for this makes it sound to me like we don't
+// xx-review: catch over-releasing an object...?
+
+ /*!
+ * @function release
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
+ * release(int freeWhen)@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/release/virtualvoid/(int)
+ * release(int freeWhen)@/link</code>.
+ */
+ virtual void release(int freeWhen) const = 0;
+
+
+ /*!
+ * @function getRetainCount
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/getRetainCount/virtualint/()
+ * getRetainCount()@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/getRetainCount/virtualint/()
+ * OSObject::getRetainCount()@/link</code>.
+ */
virtual int getRetainCount() const = 0;
-/*! @function retain
- @abstract Retain a reference in this object.
-*/
+
+ /*!
+ * @function retain
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
+ * retain()@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
+ * OSObject::retain()@/link</code>.
+ */
virtual void retain() const = 0;
-/*! @function release
- @abstract Release a reference to this object
-*/
+
+
+ /*!
+ * @function release
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
+ * release@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
+ * OSObject::release@/link</code>.
+ */
virtual void release() const = 0;
-/*! @function serialize
- @abstract
- @discussion
- @param s
- @result
-*/
- virtual bool serialize(OSSerialize *s) const = 0;
+ /*!
+ * @function serialize
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
+ * serialize@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/serialize/virtualbool/(OSSerialize*)
+ * OSObject::serialize@/link</code>.
+ */
+ virtual bool serialize(OSSerialize * serializer) const = 0;
+
+
+ /*!
+ * @function getMetaClass
+ *
+ * @abstract
+ * Returns the OSMetaClass representing
+ * an OSMetaClassBase subclass.
+ *
+ * @discussion
+ * OSObject overrides this abstract member function
+ * to return the OSMetaClass object that represents
+ * each class for run-time typing.
+ */
virtual const OSMetaClass * getMetaClass() const = 0;
-/*! @function isEqualTo
- @abstract Is this == anObj?
- @discussion OSMetaClassBase::isEqualTo implements this as a shallow pointer comparison. The OS container classes do a more meaningful comparison. Your mileage may vary.
- @param anObj Object to compare 'this' to.
- @result true if the objects are equivalent, false otherwise.
-*/
- virtual bool isEqualTo(const OSMetaClassBase *anObj) const;
-
-/*! @function metaCast
- @abstract Check to see if this object is or inherits from the given type.
- @discussion This function is the guts of the OSMetaClass system. IODynamicCast, qv, is implemented using this function.
- @param toMeta Pointer to a constant OSMetaClass for the desired target type.
- @result 'this' if object is of desired type, otherwise 0.
-*/
- OSMetaClassBase *metaCast(const OSMetaClass *toMeta) const;
-
-
-/*! @function metaCast
- @abstract See OSMetaClassBase::metaCast(const OSMetaClass *)
- @param toMeta OSSymbol of the desired class' name.
- @result 'this' if object is of desired type, otherwise 0.
-*/
- OSMetaClassBase *metaCast(const OSSymbol *toMeta) const;
-
-/*! @function metaCast
- @abstract See OSMetaClassBase::metaCast(const OSMetaClass *)
- @param toMeta OSString of the desired class' name.
- @result 'this' if object is of desired type, otherwise 0.
-*/
- OSMetaClassBase *metaCast(const OSString *toMeta) const;
-
-/*! @function metaCast
- @abstract See OSMetaClassBase::metaCast(const OSMetaClass *)
- @param toMeta const char * C String of the desired class' name.
- @result 'this' if object is of desired type, otherwise 0.
-*/
- OSMetaClassBase *metaCast(const char *toMeta) const;
-
- // Helper inlines for runtime type preprocessor macros
- static OSMetaClassBase *
- safeMetaCast(const OSMetaClassBase *me, const OSMetaClass *toType);
-
- static bool
- checkTypeInst(const OSMetaClassBase *inst, const OSMetaClassBase *typeinst);
+
+ /*!
+ * @function isEqualTo
+ *
+ * @abstract
+ * Checks whether another object is equal to the receiver.
+ *
+ * @param anObject The object to copmare to the receiver.
+ *
+ * @result
+ * <code>true</code> if the objects are equal, <code>false</code> otherwise.
+ *
+ * @discussion
+ * OSMetaClassBase implements this as a direct pointer comparison,
+ * since it has no other information to judge equality by.
+ * Subclasses generally override this function
+ * to do a more meaningful comparison.
+ * For example, OSString implements it to return
+ * <code>true</code> if <code>anObject</code>
+ * is derived from OSString and represents the same C string.
+ */
+ virtual bool isEqualTo(const OSMetaClassBase * anObject) const;
+
+
+ /*!
+ * @function metaCast
+ *
+ * @abstract
+ * Casts this object is to the class managed by the given OSMetaClass.
+ *
+ * @param toMeta A pointer to a constant OSMetaClass
+ * for the desired target type.
+ *
+ * @result
+ * <code>this</code> if the object is derived
+ * from the class managed by <code>toMeta</code>,
+ * otherwise <code>NULL</code>.
+ *
+ * @discussion
+ * It is far more convenient to use
+ * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
+ */
+ OSMetaClassBase * metaCast(const OSMetaClass * toMeta) const;
+
+
+ /*!
+ * @function metaCast
+ *
+ * @abstract
+ * Casts this object is to the class managed by the named OSMetaClass.
+ *
+ * @param toMeta An OSSymbol naming the desired target type.
+ *
+ * @result
+ * <code>this</code> if the object is derived
+ * from the class named by <code>toMeta</code>,
+ * otherwise <code>NULL</code>.
+ *
+ * @discussion
+ * It is far more convenient to use
+ * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
+ */
+ OSMetaClassBase * metaCast(const OSSymbol * toMeta) const;
+
+
+ /*!
+ * @function metaCast
+ *
+ * @abstract
+ * Casts this object is to the class managed by the named OSMetaClass.
+ *
+ * @param toMeta An OSString naming the desired target type.
+ * @result
+ * <code>this</code> if the object is derived
+ * from the class named by <code>toMeta</code>,
+ * otherwise <code>NULL</code>.
+ *
+ * @discussion
+ * It is far more convenient to use
+ * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
+ */
+ OSMetaClassBase * metaCast(const OSString * toMeta) const;
+
+
+ /*!
+ * @function metaCast
+ *
+ * @abstract
+ * Casts this object is to the class managed by the named OSMetaClass.
+ *
+ * @param toMeta A C string naming the desired target type.
+ * @result
+ * <code>this</code> if the object is derived
+ * from the class named by <code>toMeta</code>,
+ * otherwise <code>NULL</code>.
+ *
+ * @discussion
+ * It is far more convenient to use
+ * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
+ */
+ OSMetaClassBase * metaCast(const char * toMeta) const;
+
+ // Helper inlines for run-time type preprocessor macros
+ /*!
+ * @function safeMetaCast
+ *
+ * @abstract
+ * Casts an object is to the class managed by the given OSMetaClass.
+ *
+ * @param anObject A pointer to the object to be cast.
+ * @param toMeta A pointer to a constant OSMetaClass
+ * for the desired target type.
+ *
+ * @result
+ * <code>anObject</code> if the object is derived
+ * from the class managed by <code>toMeta</code>,
+ * otherwise <code>NULL</code>.
+ *
+ * @discussion
+ * It is far more convenient to use
+ * <code>@link OSDynamicCast OSDynamicCast@/link</code>.
+ */
+ static OSMetaClassBase * safeMetaCast(
+ const OSMetaClassBase * anObject,
+ const OSMetaClass * toMeta);
+
+ /*!
+ * @function checkTypeInst
+ *
+ * @abstract
+ * Checks whether an object instance is of the same class
+ * as another object instance (or a subclass of that class).
+ *
+ * @param inst A pointer to the object to check.
+ * @param typeinst A pointer to an object of the class being checked.
+ *
+ * @result
+ * <code>true</code> if the object is derived
+ * from the class of <code>typeinst</code>
+ * or a subclass of that class,
+ * otherwise <code>false</code>.
+ *
+ * @discussion
+ * It is far more convenient to use
+ * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
+ */
+ static bool checkTypeInst(
+ const OSMetaClassBase * inst,
+ const OSMetaClassBase * typeinst);
+
+ static void initialize(void);
public:
-/*! @function taggedRetain
- @abstract Retain a tagged reference in this object.
-*/
+ /*!
+ * @function taggedRetain
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*)
+ * taggedRetain(const void *)@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/taggedRetain/virtualvoid/(constvoid*)
+ * OSObject::taggedRetain(const void *)@/link</code>.
+ */
// WAS: virtual void _RESERVEDOSMetaClassBase0();
- virtual void taggedRetain(const void *tag = 0) const = 0;
-
-/*! @function taggedRelease
- @abstract Release a tagged reference to this object
-*/
+ virtual void taggedRetain(const void * tag = 0) const = 0;
+
+
+ /*!
+ * @function taggedRelease
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*)
+ * taggedRelease(const void *)@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*)
+ * OSObject::taggedRelease(const void *)@/link</code>.
+ */
// WAS: virtual void _RESERVEDOSMetaClassBase1();
- virtual void taggedRelease(const void *tag = 0) const = 0;
+ virtual void taggedRelease(const void * tag = 0) const = 0;
protected:
-/*! @function taggedRelease
- @abstract Release a tagged reference to this object and free if retainCount == when on entry
-*/
+ /*!
+ * @function taggedRelease
+ *
+ * @abstract
+ * Abstract declaration of
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
+ * taggedRelease(const void *, const int freeWhen)@/link</code>.
+ *
+ * @discussion
+ * See
+ * <code>@link
+ * //apple_ref/cpp/instm/OSObject/taggedRelease/virtualvoid/(constvoid*,constint)
+ * OSObject::taggedRelease(const void *, const int freeWhen)@/link</code>.
+ */
// WAS: virtual void _RESERVEDOSMetaClassBase2();
- virtual void taggedRelease(const void *tag, const int when) const = 0;
+ virtual void taggedRelease(
+ const void * tag,
+ const int freeWhen) const = 0;
private:
+#if APPLE_KEXT_VTABLE_PADDING
// Virtual Padding
virtual void _RESERVEDOSMetaClassBase3();
virtual void _RESERVEDOSMetaClassBase4();
virtual void _RESERVEDOSMetaClassBase5();
virtual void _RESERVEDOSMetaClassBase6();
virtual void _RESERVEDOSMetaClassBase7();
+#endif
} APPLE_KEXT_COMPATIBILITY;
+
+#ifdef XNU_KERNEL_PRIVATE
+typedef bool (*OSMetaClassInstanceApplierFunction)(const OSObject * instance,
+ void * context);
+#endif /* XNU_KERNEL_PRIVATE */
+
/*!
- @class OSMetaClass : OSMetaClassBase
- @abstract An instance of a OSMetaClass represents one class then the kernel's runtime type information system is aware of.
-*/
+ * @class OSMetaClass
+ *
+ * @abstract
+ * OSMetaClass manages run-time type information
+ * for Libkern and I/O Kit C++ classes.
+ *
+ * @discussion OSMetaClass manages run-time type information
+ * for Libkern and I/O Kit C++ classes.
+ * An instance of OSMetaClass exists for (nearly) every such C++ class,
+ * keeping track of inheritance relationships, class lookup by name,
+ * instance counts, and more.
+ * OSMetaClass operates almost entirely behind the scenes,
+ * and kernel extensions should rarely, if ever,
+ * have to interact directly with OSMetaClass.
+ *
+ * <b>Use by Kernel Extensions</b>
+ *
+ * While kernel extensions rarey interact directly with OSMetaClass at run time,
+ * they must register their classes with the metaclass system
+ * using the macros declared here.
+ * The class declaration should use one of these two macros
+ * before its first member function declaration:
+ * <ul>
+ * <li><code>@link OSDeclareDefaultStructors OSDeclareDefaultStructors@/link</code> -
+ * for classes with no abstract member function declarations</li>
+ * <li><code>@link OSDeclareAbstractStructors OSDeclareAbstractStructors@/link</code> -
+ * for classes with at least one abstract member function declaration</li>
+ * <li><code>@link OSDeclareFinalStructors OSDeclareFinalStructors@/link</code> -
+ * for classes that should not be subclassable by another kext</li>
+ * </ul>
+ *
+ * The class implementation should then use one of these macros:
+ * <ul>
+ * <li><code>@link OSDefineMetaClassAndStructors
+ * OSDefineMetaClassAndStructors@/link</code> -
+ * for classes with no abstract member function declarations</li>
+ * <li><code>@link OSDefineMetaClassAndAbstractStructors
+ * OSDefineMetaClassAndAbstractStructors@/link</code> -
+ * for classes with at least one abstract member function declaration</li>
+ * <li><code>@link OSDefineMetaClassAndFinalStructors
+ * OSDefineMetaClassAndFinalStructors@/link</code> -
+ * for classes that should not be subclassable by another kext</li>
+ * </ul>
+ *
+ * Classes in kernel extensions that are intended for use as libraries
+ * may need to reserve vtable slots to preserve binary compatibility
+ * as new functions are added. They may do so with these macros:
+ * <ul>
+ * <li><code>@link OSMetaClassDeclareReservedUnused
+ * OSMetaClassDeclareReservedUnused@/link</code> -
+ * reserves a vtable slot</li>
+ * <li><code>@link OSMetaClassDefineReservedUnused
+ * OSMetaClassDefineReservedUnused@/link</code> -
+ * defines the reserved vtable slot as an unimplemented function</li>
+ * <li><code>@link OSMetaClassDeclareReservedUsed
+ * OSMetaClassDeclareReservedUsed@/link</code> -
+ * documents that a formerly reserved slot is now used</li>
+ * <li><code>@link OSMetaClassDefineReservedUsed
+ * OSMetaClassDefineReservedUsed@/link</code> -
+ * documents that a formerly reserved slot is now used</li>
+ * </ul>
+ *
+ * <b>Use Restrictions</b>
+ *
+ * OSMetaClass should not be explicitly subclassed by kernel extensions
+ * (the declare/define macros do that),
+ * nor should kernel extensions call its run-time type functions directly.
+ *
+ * OSMetaClass functions should be considered
+ * <b>unsafe</b> to call in a primary interrupt context.
+ *
+ * <b>Concurrency Protection</b>
+ *
+ * Kernel extensions should in general not interact
+ * with OSMetaClass objects directly,
+ * instead using the run-time type macros.
+ * Much of OSMetaClass's interface is intended for use
+ * by the run-time type information system,
+ * which handles concurrency and locking internally.
+ */
class OSMetaClass : private OSMetaClassBase
{
+ friend class OSKext;
+#if IOKITSTATS
+ friend class IOStatistics;
+#endif
private:
// Can never be allocated must be created at compile time
- static void *operator new(size_t size);
+ static void * operator new(size_t size);
- struct ExpansionData { };
-
-/*! @var reserved Reserved for future use. (Internal use only) */
- ExpansionData *reserved;
+ /* Reserved for future use. (Internal use only) */
+ struct ExpansionData *reserved;
-/*! @var superClass Handle to the superclass' meta class. */
+ /* superClass Handle to the superclass's meta class. */
const OSMetaClass *superClassLink;
-/*! @var className OSSymbol of the class' name. */
+ /* className OSSymbol of the class' name. */
const OSSymbol *className;
-/*! @var classSize How big is a single instancde of this class. */
+ /* classSize How big is a single instance of this class. */
unsigned int classSize;
-/*! @var instanceCount Roughly number of instances of the object. Used primarily as a code in use flag. */
+ /* instanceCount Roughly number of instances of the object,
+ * +1 for each direct subclass with a nonzero refcount.
+ * Used primarily as a code-in-use flag.
+ */
mutable unsigned int instanceCount;
-/*! @function OSMetaClass
- @abstract Private the default constructor */
+ /* Not to be included in headerdoc.
+ *
+ * @function OSMetaClass
+ *
+ * @abstract
+ * The default private constructor.
+ */
OSMetaClass();
// Called by postModLoad
-/*! @function logError
- @abstract Given an error code log an error string using printf */
+ /* Not to be included in headerdoc.
+ *
+ * @function logError
+ *
+ * @abstract
+ * Logs an error string for an <code>OSReturn</code> value
+ * using <code>printf</code>.
+ *
+ * @param result The <code>OSReturn</code> value for which to log a message.
+ *
+ * @discussion
+ * This function is used to log errors loading kernel extensions.
+ * Kernel extensions themselves should not call it.
+ */
static void logError(OSReturn result);
public:
-/*! @function getMetaClassWithName
- @abstract Lookup a meta-class in the runtime type information system
- @param name Name of the desired class's meta-class.
- @result pointer to a meta-class object if found, 0 otherwise. */
-
- static const OSMetaClass *getMetaClassWithName(const OSSymbol *name);
+ /*!
+ * @function getMetaClassWithName
+ *
+ * @abstract
+ * Look up a metaclass in the run-time type information system.
+ *
+ * @param name The name of the desired class's metaclass.
+ *
+ * @result
+ * A pointer to the metaclass object if found, <code>NULL</code> otherwise.
+ */
+ static const OSMetaClass * getMetaClassWithName(const OSSymbol * name);
+
+#if XNU_KERNEL_PRIVATE
+
+ /*!
+ * @function copyMetaClassWithName
+ *
+ * @abstract
+ * Look up a metaclass in the run-time type information system.
+ *
+ * @param name The name of the desired class's metaclass.
+ *
+ * @result
+ * A pointer to the metaclass object if found, <code>NULL</code> otherwise.
+ * The metaclass will be protected from unloading until releaseMetaClass()
+ * is called.
+ */
+ static const OSMetaClass * copyMetaClassWithName(const OSSymbol * name);
+ /*!
+ * @function releaseMetaClass
+ *
+ * @abstract
+ * Releases reference obtained from copyMetaClassWithName().
+ *
+ * @discussion
+ * The metaclass will be protected from unloading until releaseMetaClass()
+ * is called.
+ */
+ void releaseMetaClass() const;
+
+#endif /* XNU_KERNEL_PRIVATE */
protected:
-/*! @function retain
- @abstract Implement abstract but should no dynamic allocation is allowed */
+ /*!
+ * @function retain
+ *
+ * @abstract
+ * Implements the abstract <code>retain</code> function to do nothing.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
virtual void retain() const;
-/*! @function release
- @abstract Implement abstract but should no dynamic allocation is allowed */
- virtual void release() const;
-
-/*! @function release
- @abstract Implement abstract but should no dynamic allocation is allowed
- @param when ignored. */
- virtual void release(int when) const;
-/*! @function taggedRetain
- @abstract Retain a tagged reference in this object.
-*/
- virtual void taggedRetain(const void *tag = 0) const;
-
-/*! @function release
- @abstract Release a tagged reference to this object
-*/
- virtual void taggedRelease(const void *tag = 0) const;
+ /*!
+ * @function release
+ *
+ * @abstract
+ * Implements the abstract <code>release</code> function to do nothing.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
+ virtual void release() const;
-/*! @function release
- @abstract Release a tagged reference to this object
-*/
- virtual void taggedRelease(const void *tag, const int when) const;
-/*! @function getRetainCount
- @abstract Implement abstract but should no dynamic allocation is allowed */
+ /*!
+ * @function release
+ *
+ * @abstract
+ * Implements the abstract <code>release(int freeWhen)</code>
+ * function to do nothing.
+ *
+ * @param freeWhen Unused.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
+ virtual void release(int freeWhen) const;
+
+
+ /*!
+ * @function taggedRetain
+ *
+ * @abstract
+ * Implements the abstract <code>taggedRetain(const void *)</code>
+ * function to do nothing.
+ *
+ * @param tag Unused.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
+ virtual void taggedRetain(const void * tag = 0) const;
+
+
+ /*!
+ * @function taggedRelease
+ *
+ * @abstract
+ * Implements the abstract <code>taggedRelease(const void *)</code>
+ * function to do nothing.
+ *
+ * @param tag Unused.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
+ virtual void taggedRelease(const void * tag = 0) const;
+
+
+ /*!
+ * @function taggedRelease
+ *
+ * @abstract
+ * Implements the abstract <code>taggedRelease(const void *, cont int)</code>
+ * function to do nothing.
+ *
+ * @param tag Unused.
+ * @param freeWhen Unused.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
+ virtual void taggedRelease(
+ const void * tag,
+ const int freeWhen) const;
+
+
+ /*!
+ * @function getRetainCount
+ *
+ * @abstract
+ * Implements the abstract <code>getRetainCount</code>
+ * function to return 0.
+ *
+ * @result
+ * Always returns 0.
+ *
+ * @discussion
+ * Since an OSMetaClass instance must remain in existence
+ * for as long as its kernel extension is loaded,
+ * OSMetaClass does not use reference-counting.
+ */
virtual int getRetainCount() const;
+
+ /* Not to be included in headerdoc.
+ *
+ * @function getMetaClass
+ *
+ * @abstract
+ * Returns the meta-metaclass.
+ *
+ * @result
+ * The metaclass of the OSMetaClass object.
+ */
virtual const OSMetaClass * getMetaClass() const;
-/*! @function OSMetaClass
- @abstract Constructor for OSMetaClass objects
- @discussion This constructor is protected and cannot not be used to instantiate an OSMetaClass object, i.e. OSMetaClass is an abstract class. This function stores the currently constructing OSMetaClass instance away for later processing. See preModLoad and postModLoad.
- @param inClassName cString of the name of the class this meta-class represents.
- @param inSuperClassName cString of the name of the super class.
- @param inClassSize sizeof the class. */
- OSMetaClass(const char *inClassName,
- const OSMetaClass *inSuperClass,
- unsigned int inClassSize);
-
-/*! @function ~OSMetaClass
- @abstract Destructor for OSMetaClass objects
- @discussion If this function is called it means that the object code that implemented this class is actually in the process of unloading. The destructor removes all reference's to the subclass from the runtime type information system. */
+
+ /*!
+ * @function OSMetaClass
+ *
+ * @abstract
+ * Constructor for OSMetaClass objects.
+ *
+ * @param className A C string naming the C++ class
+ * that this OSMetaClass represents.
+ * @param superclass The OSMetaClass object representing the superclass
+ * of this metaclass's class.
+ * @param classSize The allocation size of the represented C++ class.
+ *
+ * @discussion
+ * This constructor is protected and cannot be used
+ * to instantiate OSMetaClass directly, as OSMetaClass is an abstract class.
+ * This function is called during kext loading
+ * to queue C++ classes for registration.
+ * See <code>@link preModLoad preModLoad@/link</code> and
+ * <code>@link postModLoad postModLoad@/link</code>.
+ */
+ OSMetaClass(const char * className,
+ const OSMetaClass * superclass,
+ unsigned int classSize);
+
+
+ /*!
+ * @function ~OSMetaClass
+ *
+ * @abstract
+ * Destructor for OSMetaClass objects.
+ *
+ * @discussion
+ * This function is called when the kernel extension that implements
+ * the metaclass's class is unloaded.
+ * The destructor removes all references to the class
+ * from the run-time type information system.
+ */
virtual ~OSMetaClass();
// Needs to be overriden as NULL as all OSMetaClass objects are allocated
// statically at compile time, don't accidently try to free them.
- void operator delete(void *mem, size_t size) { };
+ void operator delete(void *, size_t) { }
public:
static const OSMetaClass * const metaClass;
-/*! @function preModLoad
- @abstract Prepare the runtime type system for the load of a module.
- @discussion Prepare the runtime type information system for the loading of new all meta-classes constructed between now and the next postModLoad. preModLoad grab's a lock so that the runtime type information system loading can be protected, the lock is released by the postModLoad function. Any OSMetaClass that is constructed between the bracketing pre and post calls will be assosiated with the module name.
- @param kmodName globally unique cString name of the kernel module being loaded.
- @result If success full return a handle to be used in later calls 0 otherwise. */
- static void *preModLoad(const char *kmodName);
-
-/*! @function checkModLoad
- @abstract Check if the current load attempt is still OK.
- @param loadHandle Handle returned when a successful call to preModLoad is made.
- @result true if no error's are outstanding and the system is primed to recieve more objects. */
- static bool checkModLoad(void *loadHandle);
-
-/*! @function postModLoad
- @abstract Finish postprocessing on a kernel module's meta-classes.
- @discussion As the order of static object construction is undefined it is necessary to process the constructors in two phases. These phases rely on global information that is created be the preparation step, preModLoad, which also guarantees single threading between multiple modules. Phase one was the static construction of each meta-class object one by one withing the context prepared by the preModLoad call. postModLoad is the second phase of processing. Inserts links all of the super class inheritance chains up, inserts the meta-classes into the global register of classes and records for each meta-class which kernel module caused it's construction. Finally it cleans up the temporary storage and releases the single threading lock and returns whatever error has been recorded in during the construction phase or the post processing phase.
- @param loadHandle Handle returned when a successful call to preModLoad is made.
- @result Error code of the first error encountered. */
- static OSReturn postModLoad(void *loadHandle);
-
-/*! @function modHasInstance
- @abstract Do any of the objects represented by OSMetaClass and associated with the given kernel module name have instances?
- @discussion Check all meta-classes associated with the module name and check their instance counts. This function is used to check to see if a module can be unloaded. Obviously if an instance is still outstanding it isn't safe to unload the code that relies on that object.
- @param kmodName cString of the kernel module name.
- @result true if there are any current instances of any class in the module.
-*/
- static bool modHasInstance(const char *kmodName);
-
-/*! @function reportModInstances
- @abstract Log any object that has instances in a module.
- @discussion When a developer ask for a module to be unloaded but the unload fails due to outstanding instances. This function will report which classes still have instances. It is intended mostly for developers to find problems with unloading classes and will be called automatically by 'verbose' unloads.
- @param kmodName cString of the kernel module name. */
- static void reportModInstances(const char *kmodName);
-
-/*! @function considerUnloads
- @abstract Schedule module unloading.
- @discussion Schedule unused modules to be unloaded; called when IOKit matching goes idle. */
-
+ /*!
+ * @function preModLoad
+ *
+ * @abstract
+ * Prepares the run-time type system
+ * for the creation of new metaclasses
+ * during loading of a kernel extension (module).
+ *
+ * @param kextID The bundle ID of the kext being loaded.
+ *
+ * @result
+ * An opaque handle to the load context
+ * for the kernel extension on success;
+ * <code>NULL</code> on failure.
+ *
+ * @discussion
+ * <i>Not for use by kernel extensions.</i>
+ *
+ * Prepares the run-time type information system to record and register
+ * metaclasses created by static constructors until a subsequent call to
+ * <code>@link postModLoad postModLoad@/link</code>.
+ * <code>preModLoad</code> takes a lock to ensure processing of a single
+ * load operation at a time; the lock is released by
+ * <code>@link postModLoad postModLoad@/link</code>.
+ * Any OSMetaClass constructed between these two function calls
+ * will be associated with <code>kextID</code>.
+ */
+ static void * preModLoad(const char * kextID);
+
+
+ /*!
+ * @function checkModLoad
+ *
+ * @abstract
+ * Checks whether the current kext load operation can proceed.
+ *
+ * @param loadHandle The opaque handle returned
+ * by <code>@link preModLoad preModLoad@/link</code>.
+ * @result
+ * <code>true</code> if no errors are outstanding
+ * and the system is ready to process more metaclasses.
+ *
+ * @discussion
+ * <i>Not for use by kernel extensions.</i>
+ */
+ static bool checkModLoad(void * loadHandle);
+
+
+ /*!
+ * @function postModLoad
+ *
+ * @abstract
+ * Registers the metaclasses created during loading of a kernel extension.
+ *
+ * @param loadHandle The opaque handle returned
+ * by <code>@link preModLoad preModLoad@/link</code>.
+ * @result
+ * The error code of the first error encountered,
+ * or
+ * <code>@link
+ * //apple_ref/cpp/macro/kOSReturnSuccess
+ * kOSReturnSuccess@/link</code>
+ * if no error occurred.
+ *
+ * @discussion
+ * <i>Not for use by kernel extensions.</i>
+ *
+ * Called after all static constructors in a kernel extension
+ * have created metaclasses,
+ * this function checks for duplicate class names,
+ * then registers the new metaclasses under the kext ID
+ * that @link preModLoad preModLoad@/link was called with,
+ * so that they can be dynamically allocated
+ * and have their instance counts tracked.
+ * <code>postModLoad</code> releases the lock taken by
+ * <code>@link preModLoad preModLoad@/link</code>.
+ */
+ static OSReturn postModLoad(void * loadHandle);
+
+ /*!
+ * @function modHasInstance
+ *
+ * @abstract
+ * Returns whether any classes defined by the named
+ * kernel extension (or their subclasses) have existing instances.
+ *
+ * @param kextID The bundle ID of the kernel extension to check.
+ *
+ * @result
+ * <code>true</code> if the kext is found and
+ * if any class defined by that kext
+ * has a nonzero instance count,
+ * <code>false</code> otherwise.
+ *
+ * @discussion
+ * This function is called before a kernel extension's static destructors
+ * are invoked, prior to unloading the extension.
+ * If any classes stil have instances or subclasses with instances,
+ * those classes are logged
+ * (using <code>@link reportModInstances reportModInstances@/link</code>) and
+ * the kernel extension is not be unloaded.
+ */
+ static bool modHasInstance(const char * kextID);
+
+
+ /*!
+ * @function reportModInstances
+ *
+ * @abstract
+ * Logs the instance counts for classes
+ * defined by a kernel extension.
+ *
+ * @param kextID The bundle ID of the kernel extension to report on.
+ *
+ * @discussion
+ * This function prints the names and instance counts
+ * of any class defined by <code>kextID</code>
+ * that has a nonzero instance count.
+ * It's called by <code>@link modHasInstance modHasInstance@/link</code>
+ * to help diagnose problems unloading kernel extensions.
+ */
+ static void reportModInstances(const char * kextID);
+
+
+ /*!
+ * @function considerUnloads
+ *
+ * @abstract
+ * Schedule automatic unloading of unused kernel extensions.
+ *
+ * @discussion
+ * This function schedules a check for kernel extensions
+ * that can be automatically unloaded,
+ * canceling any currently scheduled check.
+ * At that time, any such kexts with no Libkern C++ instances
+ * and no external references are unloaded.
+ *
+ * The I/O Kit calls this function when matching goes idle.
+ *
+ * Kernel extensions that define subclasses of
+ * @link //apple_ref/doc/class/IOService IOService@/link
+ * are eligible for automatic unloading.
+ *
+ * (On releases of Mac OS X prior to Snow Leopard (10.6),
+ * any kernel extension defining any Libkern C++ class
+ * was eligible for automatic unloading,
+ * but that unload did not call the module stop routine.
+ * Non-I/O Kit kernel extensions that define Libkern C++ subclasses
+ * should be sure to have OSBundleLibraries declarations that ensure
+ * they will not load on releases prior to Snow Leopard.)
+ */
static void considerUnloads();
-/*! @function allocClassWithName
- @abstract Lookup a meta-class in the runtime type information system and return the results of an alloc call.
- @param name Name of the desired class.
- @result pointer to an new object, 0 if not found or so memory. */
- static OSObject *allocClassWithName(const OSSymbol *name);
-
-/*! @function allocClassWithName
- @abstract Lookup a meta-class in the runtime type information system and return the results of an alloc call.
- @param name Name of the desired class.
- @result pointer to an new object, 0 if not found or so memory. */
- static OSObject *allocClassWithName(const OSString *name);
-
-/*! @function allocClassWithName
- @abstract Lookup a meta-class in the runtime type information system and return the results of an alloc call.
- @param name Name of the desired class.
- @result pointer to an new object, 0 if not found or so memory. */
- static OSObject *allocClassWithName(const char *name);
-
-/*! @function checkMetaCastWithName
- @abstract Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.
- @param name Name of the desired class or super class.
- @param in object to be introspected.
- @result in parameter if cast valid, 0 otherwise. */
- static OSMetaClassBase *
- checkMetaCastWithName(const OSSymbol *name, const OSMetaClassBase *in);
-
-/*! @function checkMetaCastWithName
- @abstract Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.
- @param name Name of the desired class or super class.
- @param in object to be introspected.
- @result in parameter if cast valid, 0 otherwise. */
- static OSMetaClassBase *
- checkMetaCastWithName(const OSString *name, const OSMetaClassBase *in);
-
-/*! @function checkMetaCastWithName
- @abstract Introspect an objects inheritance tree looking for a class of the given name. Basis of MacOSX's kernel dynamic casting mechanism.
- @param name Name of the desired class or super class.
- @param in object to be introspected.
- @result in parameter if cast valid, 0 otherwise. */
- static OSMetaClassBase *
- checkMetaCastWithName(const char *name, const OSMetaClassBase *in);
-
-
-/*! @function instanceConstructed
- @abstract Counts the instances of the class behind this metaclass.
- @discussion Every non-abstract class that inherits from OSObject has a default constructor that calls it's own meta-class' instanceConstructed function. This constructor is defined by the OSDefineMetaClassAndStructors macro (qv) that all OSObject subclasses must use. Also if the instance count goes from 0 to 1, ie the first instance, then increment the instance count of the super class */
+#if XNU_KERNEL_PRIVATE
+ static bool removeClasses(OSCollection * metaClasses);
+#endif /* XNU_KERNEL_PRIVATE */
+
+ /*!
+ * @function allocClassWithName
+ *
+ * @abstract
+ * Allocates an instance of a named OSObject-derived class.
+ *
+ * @param name The name of the desired class.
+ *
+ * @result
+ * A pointer to the newly-allocated, uninitialized object on success;
+ * <code>NULL</code> on failure.
+ *
+ * @discussion
+ * Kernel extensions should not need to use this function
+ * directly, instead using static instance-creation functions
+ * defined by classes.
+ *
+ * This function consults the run-time type information system
+ * to find the metaclass for the named class.
+ * If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code>
+ * function and returns the result.
+ */
+ static OSObject * allocClassWithName(const OSSymbol * name);
+
+
+ /*!
+ * function allocClassWithName
+ *
+ * @abstract
+ * Allocates an instance of a named OSObject-derived class.
+ *
+ * @param name The name of the desired class.
+ *
+ * @result
+ * A pointer to the newly-allocated, uninitialized object on success;
+ * <code>NULL</code> on failure.
+ *
+ * @discussion
+ * Kernel extensions should not need to use this function
+ * directly, instead using static instance-creation functions
+ * defined by classes.
+ *
+ * This function consults the run-time type information system
+ * to find the metaclass for the named class.
+ * If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code>
+ * function and returns the result.
+ */
+ static OSObject * allocClassWithName(const OSString * name);
+
+
+ /*!
+ * function allocClassWithName
+ *
+ * @abstract
+ * Allocates an instance of a named OSObject-derived class.
+ *
+ * @param name The name of the desired class.
+ *
+ * @result
+ * A pointer to the newly-allocated, uninitialized object on success;
+ * <code>NULL</code> on failure.
+ *
+ * @discussion
+ * Kernel extensions should not need to use this function
+ * directly, instead using static instance-creation functions
+ * defined by classes.
+ *
+ * This function consults the run-time type information system
+ * to find the metaclass for the named class.
+ * If it exists, it calls the metaclass's <code>@link alloc alloc@/link</code>
+ * function and returns the result.
+ */
+ static OSObject * allocClassWithName(const char * name);
+
+
+ /*!
+ * @function checkMetaCastWithName
+ *
+ * @abstract
+ * Search the metaclass inheritance hierarchy by name for an object instance.
+ *
+ * @param className The name of the desired class or superclass.
+ * @param object The object whose metaclass begins the search.
+ *
+ * @result
+ * <code>object</code> if it's derived from <code>className</code>;
+ * <code>NULL</code> otherwise.
+ *
+ * @discussion
+ * This function is the basis of the Libkern run-time type-checking system.
+ * Kernel extensions should not use it directly,
+ * instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or
+ * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
+ */
+ static OSMetaClassBase * checkMetaCastWithName(
+ const OSSymbol * className,
+ const OSMetaClassBase * object);
+
+ /*!
+ * @function checkMetaCastWithName
+ *
+ * @abstract
+ * Search the metaclass inheritance hierarchy by name for an object instance.
+ *
+ * @param className The name of the desired class or superclass.
+ * @param object The object whose metaclass begins the search.
+ *
+ * @result
+ * <code>object</code> if it's derived from <code>className</code>;
+ * <code>NULL</code> otherwise.
+ *
+ * @discussion
+ * Kernel extensions should not use this function directly,
+ * instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or
+ * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
+ */
+ static OSMetaClassBase * checkMetaCastWithName(
+ const OSString * className,
+ const OSMetaClassBase * object);
+
+ /*!
+ * @function checkMetaCastWithName
+ *
+ * @abstract
+ * Search the metaclass inheritance hierarchy by name for an object instance.
+ *
+ * @param className The name of the desired class or superclass.
+ * @param object The object whose metaclass begins the search.
+ *
+ * @result
+ * <code>object</code> if it's derived from <code>className</code>;
+ * <code>NULL</code> otherwise.
+ *
+ * @discussion
+ * Kernel extensions should not use this function directly,
+ * instead using <code>@link OSDynamicCast OSDynamicCast@/link</code> or
+ * <code>@link OSCheckTypeInst OSCheckTypeInst@/link</code>.
+ */
+ static OSMetaClassBase * checkMetaCastWithName(
+ const char * className,
+ const OSMetaClassBase * object);
+
+
+ /*!
+ * @function instanceConstructed
+ *
+ * @abstract
+ * Counts the instances of the class managed by this metaclass.
+ *
+ * @discussion
+ * <i>Not for use by kernel extensions.</i>
+ *
+ * Every non-abstract class that inherits from OSObject
+ * has a default constructor that calls it's own metaclass's
+ * <code>instanceConstructed</code> function.
+ * This constructor is defined by the
+ * <code>@link
+ * OSDefineMetaClassAndStructors
+ * OSDefineMetaClassAndStructors@/link</code>
+ * macro that all OSObject subclasses must use.
+ *
+ * If a class's instance count goes from 0 to 1--that is,
+ * upon the creation of the first instance of that class--the
+ * superclass's instance count is also incremented.
+ * This propagates reference counts up the inheritance chain so that
+ * superclasses are counted as "in use" when subclasses have instances.
+ */
void instanceConstructed() const;
-/*! @function instanceDestructed
- @abstract Removes one instance of the class behind this metaclass.
- @discussion OSObject's free function calls this method just before it does a 'delete this' on itself. If the instance count transitions from 1 to 0, i.e. the last object, then one instance of the superclasses is also removed. */
- void instanceDestructed() const;
-
-/*! @function checkMetaCast
- @abstract Ask a OSMetaClass instance if the given object is either an instance of it or an instance of a subclass of it.
- @param check Pointer of object to introspect.
- @result check parameter if cast valid, 0 otherwise. */
- OSMetaClassBase *checkMetaCast(const OSMetaClassBase *check) const;
+ /*!
+ * @function instanceDestructed
+ *
+ * @abstract
+ * Counts the instances of the class managed by this metaclass.
+ *
+ * @discussion
+ * Every non-abstract class that inherits from OSObject
+ * has a default destructor that calls it's own metaclass's
+ * <code>instanceDestructed</code> function.
+ * This constructor is defined by the
+ * @link OSDefineMetaClassAndStructors OSDefineMetaClassAndStructors@/link
+ * macro that all OSObject subclasses must use.
+ *
+ * If a class's instance count goes from 1 to 0--that is,
+ * upon the destruction of the last instance of that class--the
+ * superclass's instance count is also decremented.
+ * This reduces "in use" counts from superclasses when their subclasses
+ * no longer have instances.
+ */
+ void instanceDestructed() const;
-/*! @function getInstanceCount
- @abstract How many instances of the class have been created.
- @result Count of the number of instances. */
+ /*!
+ * @function checkMetaCast
+ *
+ * @abstract
+ * Check whether a given object is an instance of the receiving
+ * metaclass's class or one derived from it.
+ *
+ * @param object The object to check for inheritance.
+ *
+ * @result
+ * <code>object</code> if it is derived from the receiver's class,
+ * <code>NULL</code> if not.
+ */
+ OSMetaClassBase * checkMetaCast(const OSMetaClassBase * object) const;
+
+
+ /*!
+ * @function getInstanceCount
+ *
+ * @abstract
+ * Returns the number of existing instances of the metaclass's class.
+ *
+ * @result
+ * The number of existing instances of the metaclass's class,
+ * plus 1 for each subclass with any instance.
+ */
unsigned int getInstanceCount() const;
-/*! @function getSuperClass
- @abstract 'Get'ter for the super class.
- @result Pointer to superclass, chain ends with 0 for OSObject. */
- const OSMetaClass *getSuperClass() const;
-
-/*! @function getKmodName
- @abstract 'Get'ter for the name of the kmod.
- @result OSSymbol representing the kmod name. */
- const OSSymbol *getKmodName() const;
-
-/*! @function getClassName
- @abstract 'Get'ter for class name.
- @result cString of the class name. */
- const char *getClassName() const;
-
-/*! @function getClassSize
- @abstract 'Get'ter for sizeof(class).
- @result sizeof of class that this OSMetaClass instance represents. */
+ /*!
+ * @function getSuperClass
+ *
+ * @abstract
+ * Returns the super-metaclass of the receiver.
+ *
+ * @result
+ * Returns a pointer to the super-metaclass of the receiving
+ * OSMetaClass, or <code>NULL</code> for OSObject's metaclass.
+ */
+ const OSMetaClass * getSuperClass() const;
+
+ /*!
+ * @function getKmodName
+ *
+ * @abstract
+ * Returns the bundle identifier of the kernel extension
+ * that defines this metaclass.
+ *
+ * @result
+ * The bundle identifier of the kernel extension that defines this metaclass.
+ *
+ * @discussion
+ * "Kmod" is an older term for kernel extension.
+ */
+ const OSSymbol * getKmodName() const;
+
+
+ /*!
+ * @function getClassName
+ *
+ * @abstract
+ * Returns the name of the C++ class managed by this metaclass.
+ *
+ * @result
+ * Returns the name of the C++ class managed by this metaclass.
+ */
+ const char * getClassName() const;
+ const OSSymbol * getClassNameSymbol() const;
+
+
+ /*!
+ * @function getClassSize
+ *
+ * @abstract
+ * Returns the allocation size of the C++ class managed by this metaclass.
+ *
+ * @result
+ * The allocation size of the C++ class managed by this metaclass.
+ */
unsigned int getClassSize() const;
-/*! @function alloc
- @abstract Allocate an instance of the class that this OSMetaClass instance represents.
- @discussion This alloc function is analogous to the old ObjC class alloc method. Typically not used by clients as the static function allocClassWithName is more generally useful. Infact that function is implemented in terms of this virtual function. All subclass's of OSMetaClass must implement this function but that is what the OSDefineMetaClassAndStructor's families of macros does for the developer automatically.
- @result Pointer to a new object with a retain count of 1. */
- virtual OSObject *alloc() const = 0;
-
-/*! @function OSDeclareCommonStructors
- @abstract Basic helper macro for the OSDeclare for Default and Abstract macros, qv. DO NOT USE.
- @param className Name of class. NO QUOTES. */
-#define OSDeclareCommonStructors(className) \
- private: \
- static const OSMetaClass * const superClass; \
- public: \
- static const OSMetaClass * const metaClass; \
- static class MetaClass : public OSMetaClass { \
- public: \
- MetaClass(); \
- virtual OSObject *alloc() const; \
- } gMetaClass; \
- friend class className ::MetaClass; \
- virtual const OSMetaClass * getMetaClass() const; \
- protected: \
- className (const OSMetaClass *); \
- virtual ~ className ()
-
-
-/*! @function OSDeclareDefaultStructors
- @abstract One of the macro's used in the class declaration of all subclasses of OSObject, declares runtime type information data and interfaces.
- @discussion Macro used in the class declaration all subclasses of OSObject, declares runtime type information data and interfaces. By convention it should be 'called' immediately after the opening brace in a class declaration. It leaves the current privacy state as 'protected:'.
- @param className Name of class. NO QUOTES. */
-#define OSDeclareDefaultStructors(className) \
- OSDeclareCommonStructors(className); \
- public: \
- className (); \
+
+ /*!
+ * @function alloc
+ *
+ * @abstract
+ * Allocates an instance of the C++ class managed by this metaclass.
+ *
+ * @result
+ * A pointer to the newly allocated, uninitialized instance,
+ * with a retain count of 1; <code>NULL</code> on allocation failure.
+ *
+ * @discussion
+ * This function is automatically created by the metaclass-registration macros
+ * to enable dynamic instance allocation.
+ */
+ virtual OSObject * alloc() const = 0;
+
+#ifdef XNU_KERNEL_PRIVATE
+ void addInstance(const OSObject * instance, bool super = false) const;
+ void removeInstance(const OSObject * instance, bool super = false) const;
+ void applyToInstances(OSMetaClassInstanceApplierFunction applier,
+ void * context) const;
+ static void applyToInstancesOfClassName(
+ const OSSymbol * name,
+ OSMetaClassInstanceApplierFunction applier,
+ void * context);
+private:
+ static void applyToInstances(OSOrderedSet * set,
+ OSMetaClassInstanceApplierFunction applier,
+ void * context);
+public:
+#endif /* XNU_KERNEL_PRIVATE */
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDeclareCommonStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ */
+#define OSDeclareCommonStructors(className) \
+ private: \
+ static const OSMetaClass * const superClass; \
+ public: \
+ static const OSMetaClass * const metaClass; \
+ static class MetaClass : public OSMetaClass { \
+ public: \
+ MetaClass(); \
+ virtual OSObject *alloc() const; \
+ } gMetaClass; \
+ friend class className ::MetaClass; \
+ virtual const OSMetaClass * getMetaClass() const APPLE_KEXT_OVERRIDE; \
+ protected: \
+ className (const OSMetaClass *); \
+ virtual ~ className ()
+
+
+ /*!
+ * @define OSDeclareDefaultStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Declares run-time type information and functions
+ * for a concrete Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @discussion
+ * Concrete Libkern C++ classes should "call" this macro
+ * immediately after the opening brace in a class declaration.
+ * It leaves the current privacy state as <code>protected:</code>.
+ */
+#define OSDeclareDefaultStructors(className) \
+ OSDeclareCommonStructors(className); \
+ public: \
+ className (); \
protected:
-/*! @function OSDeclareAbstractStructors
- @abstract One of the macro's used in the class declaration of all subclasses of OSObject, declares runtime type information data and interfaces.
- @discussion This macro is used when the class being declared has one or more '= 0' pure virtual methods and thus it is illegal to create an instance of this class. It leaves the current privacy state as 'protected:'.
- @param className Name of class. NO QUOTES. */
-#define OSDeclareAbstractStructors(className) \
- OSDeclareCommonStructors(className); \
- private: \
- className (); /* Make primary constructor private in abstract */ \
+ /*!
+ * @define OSDeclareAbstractStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Declares run-time type information and functions
+ * for an abstract Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @discussion
+ * Abstract Libkern C++ classes--those with at least one
+ * pure virtual method--should "call" this macro
+ * immediately after the opening brace in a class declaration.
+ * It leaves the current privacy state as <code>protected:</code>.
+ */
+#define OSDeclareAbstractStructors(className) \
+ OSDeclareCommonStructors(className); \
+ private: \
+ className (); /* Make primary constructor private in abstract */ \
+ protected:
+
+ /*!
+ * @define OSDeclareFinalStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Declares run-time type information and functions
+ * for a final (non-subclassable) Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @discussion
+ * Final Libkern C++ classes--those that do not allow subclassing--should
+ * "call" this macro immediately after the opening brace in a class declaration.
+ * (Final classes in the kernel may actually have subclasses in the kernel,
+ * but kexts cannot define any subclasses of a final class.)
+ * It leaves the current privacy state as <code>protected:</code>.
+ *
+ * <b>Note:</b> If the class is exported by a pseudokext (symbol set),
+ * the final symbol generated by this macro must be exported
+ * for the final-class attribute to be enforced.
+ *
+ * <b>Warning:</b> Changing a class from "Default" to "Final" will break
+ * binary compatibility.
+ */
+#define OSDeclareFinalStructors(className) \
+ OSDeclareDefaultStructors(className) \
+ private: \
+ void __OSFinalClass(void); \
protected:
-/*! @function OSDefineMetaClassWithInit
- @abstract Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS.
- @param init Name of a function to call after the OSMetaClass is constructed. */
-#define OSDefineMetaClassWithInit(className, superClassName, init) \
- /* Class global data */ \
- className ::MetaClass className ::gMetaClass; \
- const OSMetaClass * const className ::metaClass = \
- & className ::gMetaClass; \
- const OSMetaClass * const className ::superClass = \
- & superClassName ::gMetaClass; \
- /* Class member functions */ \
- className :: className(const OSMetaClass *meta) \
- : superClassName (meta) { } \
- className ::~ className() { } \
- const OSMetaClass * className ::getMetaClass() const \
- { return &gMetaClass; } \
- /* The ::MetaClass constructor */ \
- className ::MetaClass::MetaClass() \
- : OSMetaClass(#className, className::superClass, sizeof(className)) \
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineMetaClassWithInit
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ * @param init A function to call in the constructor
+ * of the class's OSMetaClass.
+ */
+#define OSDefineMetaClassWithInit(className, superclassName, init) \
+ /* Class global data */ \
+ className ::MetaClass className ::gMetaClass; \
+ const OSMetaClass * const className ::metaClass = \
+ & className ::gMetaClass; \
+ const OSMetaClass * const className ::superClass = \
+ & superclassName ::gMetaClass; \
+ /* Class member functions */ \
+ className :: className(const OSMetaClass *meta) \
+ : superclassName (meta) { } \
+ className ::~ className() { } \
+ const OSMetaClass * className ::getMetaClass() const \
+ { return &gMetaClass; } \
+ /* The ::MetaClass constructor */ \
+ className ::MetaClass::MetaClass() \
+ : OSMetaClass(#className, className::superClass, sizeof(className)) \
{ init; }
-/*! @function OSDefineAbstractStructors
- @abstract Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS. */
-#define OSDefineAbstractStructors(className, superClassName) \
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineAbstractStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ */
+#define OSDefineAbstractStructors(className, superclassName) \
OSObject * className ::MetaClass::alloc() const { return 0; }
-/*! @function OSDefineDefaultStructors
- @abstract Basic helper macro for the OSDefineMetaClass for the default and Abstract macros, qv. DO NOT USE.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS. */
-#define OSDefineDefaultStructors(className, superClassName) \
- OSObject * className ::MetaClass::alloc() const \
- { return new className; } \
- className :: className () : superClassName (&gMetaClass) \
- { gMetaClass.instanceConstructed(); }
-
-
-/*! @function OSDefineMetaClassAndAbstractStructorsWithInit
- @abstract Primary definition macro for all abstract classes that a subclasses of OSObject.
- @discussion Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that is an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class. Once the OSMetaClass has been constructed, at load time, call the init routine. NB you can not rely on the order of execution of the init routines.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS.
- @param init Name of a function to call after the OSMetaClass is constructed. */
-#define OSDefineMetaClassAndAbstractStructorsWithInit(className, superClassName, init) \
- OSDefineMetaClassWithInit(className, superClassName, init) \
- OSDefineAbstractStructors(className, superClassName)
-
-/*! @function OSDefineMetaClassAndStructorsWithInit
- @abstract See OSDefineMetaClassAndStructors
- @discussion Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that isn't an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class. Once the OSMetaClass has been constructed, at load time, call the init routine. NB you can not rely on the order of execution of the init routines.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS.
- @param init Name of a function to call after the OSMetaClass is constructed. */
-#define OSDefineMetaClassAndStructorsWithInit(className, superClassName, init) \
- OSDefineMetaClassWithInit(className, superClassName, init) \
- OSDefineDefaultStructors(className, superClassName)
-
-/* Helpers */
-/*! @function OSDefineMetaClass
- @abstract Define an OSMetaClass instance, used for backward compatiblility only.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS. */
-#define OSDefineMetaClass(className, superClassName) \
- OSDefineMetaClassWithInit(className, superClassName, )
-
-/*! @function OSDefineMetaClassAndStructors
- @abstract Define an OSMetaClass subclass and the runtime system routines.
- @discussion Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that isn't an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS. */
-#define OSDefineMetaClassAndStructors(className, superClassName) \
- OSDefineMetaClassAndStructorsWithInit(className, superClassName, )
-
-/*! @function OSDefineMetaClassAndAbstractStructors
- @abstract Define an OSMetaClass subclass and the runtime system routines.
- @discussion Define an OSMetaClass subclass and the primary constructors and destructors for a subclass of OSObject that is an abstract class. In general this 'function' is 'called' at the top of the file just before the first function is implemented for a particular class.
- @param className Name of class. NO QUOTES and NO MACROS.
- @param superClassName Name of super class. NO QUOTES and NO MACROS. */
-#define OSDefineMetaClassAndAbstractStructors(className, superClassName) \
- OSDefineMetaClassAndAbstractStructorsWithInit (className, superClassName, )
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineDefaultStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ */
+#define OSDefineDefaultStructors(className, superclassName) \
+ OSObject * className ::MetaClass::alloc() const \
+ { return new className; } \
+ className :: className () : superclassName (&gMetaClass) \
+ { gMetaClass.instanceConstructed(); }
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineDefaultStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ */
+#define OSDefineFinalStructors(className, superclassName) \
+ OSDefineDefaultStructors(className, superclassName) \
+ void className ::__OSFinalClass(void) { }
+
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineMetaClassAndStructorsWithInit
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ * @param init A function to call in the constructor
+ * of the class's OSMetaClass.
+ */
+#define OSDefineMetaClassAndStructorsWithInit(className, superclassName, init) \
+ OSDefineMetaClassWithInit(className, superclassName, init) \
+ OSDefineDefaultStructors(className, superclassName)
+
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineMetaClassAndAbstractStructorsWithInit
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ * @param init A function to call in the constructor
+ * of the class's OSMetaClass.
+ */
+#define OSDefineMetaClassAndAbstractStructorsWithInit(className, superclassName, init) \
+ OSDefineMetaClassWithInit(className, superclassName, init) \
+ OSDefineAbstractStructors(className, superclassName)
+
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineMetaClassAndFinalStructorsWithInit
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ * @param init A function to call in the constructor
+ * of the class's OSMetaClass.
+ */
+#define OSDefineMetaClassAndFinalStructorsWithInit(className, superclassName, init) \
+ OSDefineMetaClassWithInit(className, superclassName, init) \
+ OSDefineFinalStructors(className, superclassName)
+
+
+ /* Helpers */
+
+ /* Not to be included in headerdoc.
+ *
+ * @define OSDefineMetaClass
+ * @hidecontents
+ *
+ * @abstract
+ * Helper macro for for the standard metaclass-registration macros.
+ * DO NOT USE.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ * @param init A function to call in the constructor
+ * of the class's OSMetaClass.
+ */
+#define OSDefineMetaClass(className, superclassName) \
+ OSDefineMetaClassWithInit(className, superclassName, )
+
+
+ /*!
+ * @define OSDefineMetaClassAndStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Defines an OSMetaClass and associated routines
+ * for a concrete Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @discussion
+ * Concrete Libkern C++ classes should "call" this macro
+ * at the beginning of their implementation files,
+ * before any function implementations for the class.
+ */
+#define OSDefineMetaClassAndStructors(className, superclassName) \
+ OSDefineMetaClassAndStructorsWithInit(className, superclassName, )
+
+
+ /*!
+ * @define OSDefineMetaClassAndAbstractStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Defines an OSMetaClass and associated routines
+ * for an abstract Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @discussion
+ * Abstract Libkern C++ classes--those with at least one
+ * pure virtual method--should "call" this macro
+ * at the beginning of their implementation files,
+ * before any function implementations for the class.
+ */
+#define OSDefineMetaClassAndAbstractStructors(className, superclassName) \
+ OSDefineMetaClassAndAbstractStructorsWithInit (className, superclassName, )
+
+
+ /*!
+ * @define OSDefineMetaClassAndFinalStructors
+ * @hidecontents
+ *
+ * @abstract
+ * Defines an OSMetaClass and associated routines
+ * for a final (non-subclassable) Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param superclassName The name of the superclass of the C++ class,
+ * as a raw token,
+ * <i>not</i> a string or macro.
+ *
+ * @discussion
+ * Final Libkern C++ classes--those that do not allow
+ * subclassing--should "call" this macro at the beginning
+ * of their implementation files,
+ * before any function implementations for the class.
+ * (Final classes in the kernel may actually have subclasses in the kernel,
+ * but kexts cannot define any subclasses of a final class.)
+ *
+ * <b>Note:</b> If the class is exported by a pseudokext (symbol set),
+ * the final symbol generated by this macro must be exported
+ * for the final-class attribute to be enforced.
+ *
+ * <b>Warning:</b> Changing a class from "Default" to "Final" will break
+ * binary compatibility.
+ */
+#define OSDefineMetaClassAndFinalStructors(className, superclassName) \
+ OSDefineMetaClassAndFinalStructorsWithInit(className, superclassName, )
+
// Dynamic vtable patchup support routines and types
void reservedCalled(int ind) const;
-#define OSMetaClassDeclareReservedUnused(classname, index) \
- private: \
- virtual void _RESERVED ## classname ## index ()
-#define OSMetaClassDeclareReservedUsed(classname, index)
+ /*!
+ * @define OSMetaClassDeclareReservedUnused
+ * @hidecontents
+ *
+ * @abstract
+ * Reserves vtable space for new virtual functions
+ * in a Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param index The numeric index of the vtable slot,
+ * as a raw constant, beginning from 0.
+ *
+ * @discussion
+ * Libkern C++ classes in kernel extensions that can be used as libraries
+ * can provide for backward compatibility by declaring a number
+ * of reserved vtable slots
+ * that can be replaced with new functions as they are added.
+ * Each reserved declaration must be accompanied in the implementation
+ * by a corresponding reference to
+ * <code>@link OSMetaClassDefineReservedUnused
+ * OSMetaClassDefineReservedUnused@/link</code>.
+ *
+ * When replacing a reserved slot, change the macro from "Unused"
+ * to "Used" to document the fact that the slot used to be reserved,
+ * and declare the new function immediately after the "Used" macro
+ * to preserve vtable ordering.
+ * See
+ * <code>@link OSMetaClassDeclareReservedUsed
+ * OSMetaClassDeclareReservedUsed@/link</code>.
+ */
+#if APPLE_KEXT_VTABLE_PADDING
+#define OSMetaClassDeclareReservedUnused(className, index) \
+ private: \
+ virtual void _RESERVED ## className ## index ()
+#else
+#define OSMetaClassDeclareReservedUnused(className, index)
+#endif
-#define OSMetaClassDefineReservedUnused(classname, index) \
-void classname ::_RESERVED ## classname ## index () \
- { gMetaClass.reservedCalled(index); }
-#define OSMetaClassDefineReservedUsed(classname, index)
+ /*!
+ * @define OSMetaClassDeclareReservedUsed
+ * @hidecontents
+ *
+ * @abstract
+ * Documents use of reserved vtable space for new virtual functions
+ * in a Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param index The numeric index of the vtable slot,
+ * as a raw constant, beginning from 0.
+ *
+ * @discussion
+ * This macro evaluates to nothing, and is used to document reserved
+ * vtable slots as they are filled.
+ * See
+ * <code>@link OSMetaClassDeclareReservedUnused
+ * OSMetaClassDeclareReservedUnused@/link</code>.
+ */
+#define OSMetaClassDeclareReservedUsed(className, index)
+
+
+ /*!
+ * @define OSMetaClassDefineReservedUnused
+ * @hidecontents
+ *
+ * @abstract
+ * Defines a reserved vtable slot for a Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param index The numeric index of the vtable slot,
+ * as a raw constant, beginning from 0.
+ *
+ * @discussion
+ * Libkern C++ classes in kernel extensions that can be used as libraries
+ * can provide for backward compatibility by declaring a number
+ * of reserved vtable slots
+ * that can be replaced with new functions as they are added.
+ * Each reserved defintion accompanies
+ * a corresponding declaration created with
+ * <code>@link OSMetaClassDeclareReservedUnused
+ * OSMetaClassDeclareReservedUnused@/link</code>.
+ *
+ * This macro is used in the implementation file
+ * to provide a placeholder definition for the reserved vtable slot,
+ * as a function that calls <code>panic</code> with an error message.
+ *
+ * When replacing a reserved slot, change the macro from "Unused"
+ * to "Used" to document the fact that the slot used to be reserved,
+ * and declare the new function immediately after the "Used" macro
+ * to preserve vtable ordering.
+ * See
+ * <code>@link OSMetaClassDefineReservedUsed
+ * OSMetaClassDefineReservedUsed@/link</code>.
+ */
+#if APPLE_KEXT_VTABLE_PADDING
+#define OSMetaClassDefineReservedUnused(className, index) \
+void className ::_RESERVED ## className ## index () \
+ { gMetaClass.reservedCalled(index); }
+#else
+#define OSMetaClassDefineReservedUnused(className, index)
+#endif
+
- // IOKit debug internal routines.
+ /*!
+ * @define OSMetaClassDefineReservedUsed
+ * @hidecontents
+ *
+ * @abstract
+ * Reserves vtable space for new virtual functions in a Libkern C++ class.
+ *
+ * @param className The name of the C++ class, as a raw token,
+ * <i>not</i> a string or macro.
+ * @param index The numeric index of the vtable slot,
+ * as a raw constant, beginning from 0.
+ *
+ * @discussion
+ * This macro evaluates to nothing, and is used to document reserved
+ * vtable slots as they are filled.
+ * See
+ * <code>@link OSMetaClassDefineReservedUnused
+ * OSMetaClassDefineReservedUnused@/link</code>.
+ */
+#define OSMetaClassDefineReservedUsed(className, index)
+
+ // I/O Kit debug internal routines.
static void printInstanceCounts();
- static void serializeClassDictionary(OSDictionary *dict);
+ static void serializeClassDictionary(OSDictionary * dict);
+#ifdef XNU_KERNEL_PRIVATE
+#if IOTRACKING
+public:
+ static void * trackedNew(size_t size);
+ static void trackedDelete(void * mem, size_t size);
+ void trackedInstance(OSObject * instance) const;
+ void trackedFree(OSObject * instance) const;
+ void trackedAccumSize(OSObject * instance, size_t size) const;
+ struct IOTrackingQueue * getTracking() const;
+#endif /* IOTRACKING */
+#endif /* XNU_KERNEL_PRIVATE */
private:
// Obsolete APIs
- static OSDictionary *getClassDictionary();
- virtual bool serialize(OSSerialize *s) const;
+ static OSDictionary * getClassDictionary();
+ virtual bool serialize(OSSerialize * serializer) const;
// Virtual Padding functions for MetaClass's
OSMetaClassDeclareReservedUnused(OSMetaClass, 0);
projects / apple / xnu.git / blobdiff