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