libkern/libkern/OSKextLibPrivate.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef _LIBKERN_OSKEXTLIBPRIVATE_H
  30 #define _LIBKERN_OSKEXTLIBPRIVATE_H
  31
  32
  33 #include <sys/cdefs.h>
  34 #include <uuid/uuid.h>
  35
  36 __BEGIN_DECLS
  37 #ifdef KERNEL
  38 #include <libkern/OSTypes.h>
  39 #include <mach/kmod.h>
  40 #include <mach/vm_types.h>
  41 #else
  42 #include <CoreFoundation/CoreFoundation.h>
  43 #include <mach/kmod.h>
  44 #endif /* KERNEL */
  45 __END_DECLS
  46
  47 #include <libkern/OSReturn.h>
  48
  49 __BEGIN_DECLS
  50
  51 #if PRAGMA_MARK
  52 #pragma mark -
  53 /********************************************************************/
  54 #pragma mark Misc Constants
  55 /********************************************************************/
  56 #endif
  57
  58 typedef uint8_t OSKextExcludeLevel;
  59 #define kOSKextExcludeNone  (0)
  60 #define kOSKextExcludeKext  (1)
  61 #define kOSKextExcludeAll   (2)
  62
  63 #if PRAGMA_MARK
  64 #pragma mark -
  65 /********************************************************************/
  66 #pragma mark Kext/OSBundle Property List Keys
  67 /********************************************************************/
  68 #endif
  69
  70 /*!
  71  * @define   kOSBundleHelperKey
  72  * @abstract Used by loginwindow.
  73  */
  74 #define kOSBundleHelperKey      "OSBundleHelper"
  75
  76 /*!
  77  * @define   kOSBundleDeveloperOnlyKey
  78  * @abstract A boolean value indicating whether the kext should only load on
  79  *           Developer devices.
  80  */
  81 #define kOSBundleDeveloperOnlyKey               "OSBundleDeveloperOnly"
  82
  83 /*!
  84  * @define   kOSBundleRamDiskOnlyKey
  85  * @abstract A boolean value indicating whether the kext should only load when
  86  *           booted from a ram disk.
  87  */
  88 #define kOSBundleRamDiskOnlyKey         "OSBundleRamDiskOnly"
  89
  90
  91 /*!
  92  * @define   kAppleSecurityExtensionKey
  93  * @abstract A boolean value indicating whether the kext registers
  94  *           MACF hooks.
  95  */
  96 #define kAppleSecurityExtensionKey      "AppleSecurityExtension"
  97
  98 /*!
  99  * @define   kAppleKernelExternalComponentKey
 100  * @abstract A boolean value indicating whether the kext is vending kernel
 101  *           KPI, and needs special loading behavior.
 102  */
 103 #define kAppleKernelExternalComponentKey        "AppleKernelExternalComponent"
 104
 105 // properties found in the registry root
 106 #define kOSKernelCPUTypeKey             "OSKernelCPUType"
 107 #define kOSKernelCPUSubtypeKey          "OSKernelCPUSubtype"
 108 #define kOSStartupMkextCRC              "OSStartupMkextCRC"             /* value is 32-bit OSData */
 109 #define kOSPrelinkKextCountKey          "OSPrelinkKextCount"            /* value is 32-bit OSNumber */
 110 #define kOSPrelinkPersonalityCountKey   "OSPrelinkPersonalityCount"     /* value is 32-bit OSNumber */
 111
 112 #if PRAGMA_MARK
 113 #pragma mark -
 114 /********************************************************************/
 115 #pragma mark Load Info Keys
 116 /********************************************************************/
 117 #endif
 118 /*********************************************************************
 119 * In addition to the keys defined here, you will find:
 120 *   kCFBundleIdentifierKey
 121 *   kCFBundleVersionKey
 122 *   kOSBundleCompatibleVersionKey
 123 *   kOSBundleIsInterfaceKey
 124 *   kOSKernelResourceKey
 125 *********************************************************************/
 126 #define kOSBundleMachOHeadersKey                "OSBundleMachOHeaders"
 127 #define kOSBundleLogStringsKey                  "OSBundleLogStrings"
 128 #define kOSBundleCPUTypeKey                     "OSBundleCPUType"
 129 #define kOSBundleCPUSubtypeKey                  "OSBundleCPUSubtype"
 130 #define kOSBundlePathKey                        "OSBundlePath"
 131 #define kOSBundleExecutablePathKey              "OSBundleExecutablePath"
 132 #define kOSBundleUUIDKey                        "OSBundleUUID"
 133 #define kOSBundleTextUUIDKey                    "OSBundleTextUUID"
 134 #define kOSBundleStartedKey                     "OSBundleStarted"
 135 #define kOSBundlePrelinkedKey                   "OSBundlePrelinked"
 136 #define kOSBundleLoadTagKey                     "OSBundleLoadTag"
 137 #define kOSBundleLoadAddressKey                 "OSBundleLoadAddress"
 138 #define kOSBundleLoadSizeKey                    "OSBundleLoadSize"
 139 #define kOSBundleExecLoadAddressKey             "OSBundleExecLoadAddress"
 140 #define kOSBundleExecLoadSizeKey                "OSBundleExecLoadSize"
 141 #define kOSBundleWiredSizeKey                   "OSBundleWiredSize"
 142 #define kOSBundleDependenciesKey                "OSBundleDependencies"
 143 #define kOSBundleRetainCountKey                 "OSBundleRetainCount"
 144 #define kOSBundleCacheLoadAddressKey            "OSBundleCacheLoadAddress"
 145 // Kernel TEXT encompasses kexts
 146 #define kOSBundleKextsInKernelTextKey           "OSBundleKextsInKernelText"
 147 // OSKextCopyLoadedKextInfo includes non-started kexts when present:
 148 #define kOSBundleAllPrelinkedKey                "OSBundleAllPrelinked"
 149
 150 /* Dictionary of metaclass info keyed by classname.
 151  */
 152 #define kOSBundleClassesKey                     "OSBundleClasses"
 153
 154 /* These are contained in kOSBundleClassesKey. kOSMetaClassSuperclassNameKey
 155  * may be absent (for the root class).
 156  */
 157 #define kOSMetaClassNameKey                     "OSMetaClassName"
 158 #define kOSMetaClassSuperclassNameKey           "OSMetaClassSuperclassName"
 159 #define kOSMetaClassTrackingCountKey            "OSMetaClassTrackingCount"
 160
 161 #if PRAGMA_MARK
 162 #pragma mark -
 163 /********************************************************************/
 164 #pragma mark Kext Log Specification
 165 /********************************************************************/
 166 #endif
 167 /*!
 168  * @group Kext Log Specification
 169  * Logging levels & flags for kernel extensions.
 170  * See <code>@link //apple_ref/c/tdef/OSKextLogSpec OSKextLogSpec@/link</code>
 171  * for an overview.
 172  */
 173
 174 /*!
 175  * @typedef  OSKextLogSpec
 176  * @abstract Describes what a log message applies to,
 177  *           or a filter that determines which log messages are displayed.
 178  *
 179  * @discussion
 180  * A kext log specification is a 32-bit value used as a desription of
 181  * what a given log message applies to, or as a filter
 182  * indicating which log messages are desired and which are not.
 183  * A log specification has three parts (described in detail shortly):
 184  * <ul>
 185  *   <li>A <b>level</b> from 0-7 in the lowest-order nibble (0x7).</li>
 186  *   <li>A flag bit in the lowest-order nibble (0x8) indicating whether
 187  *       log messages tied to individual kexts are always printed (1)
 188  *       or printed only if the kext has an
 189  *       @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 190  *       OSBundleEnableKextLogging@/link set to <code>true</code>.
 191  *   <li>A set of <b>activity flags</b> in the remaining nibbles (0xFFFFFFF0),
 192  *       which describe areas of activity related to kernel extensions.</li>
 193  * </ul>
 194  *
 195  * You can specify a log spec to most of the kext tools with the -v option
 196  * and a hex number (rather than the escalating decimal levels 0-6).
 197  * You can also specify a log spec to the kernel with the "kextlog" boot arg
 198  * or "debug.kextlog" sysctl.
 199  *
 200  * <b>Log Levels</b>
 201  *
 202  * The log level spans a range from silent (no log messages)
 203  * to debuging information:
 204  *
 205  * <ol start="0">
 206  * <li>Silent - Not applicable to messages; as a filter, do not print any log messages.</li>
 207  * <li>Errors - Log message is an error.
 208  * <li>Warnings - Log message is a warning.
 209  * <li>Basic information - Log message is basic success/failure.</li>
 210  * <li>Progress - Provides high-level information about stages in processing.</li>
 211  * <li>Step - Provides low-level information about complex operations,
 212  *          typically about individual kexts.</li>
 213  * <li>Detail - Provides very low-level information about parts of kexts,
 214  *          including individual Libkern classes and operations on bundle files.</li>
 215  * <li>Debug - Very verbose logging about internal activities.</li>
 216  * </ol>
 217  *
 218  * Log messages at
 219  * <code>@link kOSKextLogErrorLevel kOSKextLogErrorLevel@/link</code> or
 220  * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code>
 221  * ignore activity flags and the
 222  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 223  * OSBundleEnableKextLogging@/link property;
 224  * that is, only the filter level is checked for messages at these levels.
 225  * Log messages at levels above
 226  * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code>
 227  * are filtered according both to the activity flags in the current filter
 228  * and to whether the log message is associated with a kext or not.
 229  * Normally log messages associated with kexts are not printed
 230  * unless the kext has a
 231  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 232  * OSBundleEnableKextLogging@/link property set to <code>true</code>.
 233  * If you set the high-order bit of the log level (that is, add 8 to the level),
 234  * then all kext-specific log messages matching the activity flags are printed.
 235  * This can be very verbose.
 236  *
 237  * <b>Activity Flags</b>
 238  *
 239  * Each flag governs a category of activity,
 240  * such as loading, IPC, or archives; by combining them with bitwise OR,
 241  * you can choose which messages you wish to see (or when logging messages,
 242  * which bit flags select your message).
 243  *
 244  * <b>Byte 1:</b> <code>0xF0</code> - Basic activities
 245  * (<code>@link kOSKextLogGeneralFlag kOSKextLogGeneralFlag@/link</code>,
 246  * <code>@link kOSKextLogLoadFlag kOSKextLogLoadFlag@/link</code>, and
 247  * <code>@link kOSKextLogArchiveFlag kOSKextLogArchiveFlag@/link</code>).
 248  *
 249  * <b>Byte 2:</b> <code>0xF00</code> - Reserved.
 250  *
 251  * <b>Byte 4:</b> <code>0xF000</code> - Kext diagnostics
 252  * (<code>@link kOSKextLogValidationFlag kOSKextLogValidationFlag@/link</code>,
 253  * <code>@link kOSKextLogAuthenticationFlag kOSKextLogAuthenticationFlag@/link</code>, and
 254  * <code>@link kOSKextLogDependenciesFlag kOSKextLogDependenciesFlag@/link</code>).
 255  *
 256  * <b>Byte 5:</b> <code>0xF00000</code> - Kext access & bookkeeping
 257  * (<code>@link kOSKextLogDirectoryScanFlag kOSKextLogDirectoryScanFlag@/link</code>,
 258  * <code>@link kOSKextLogFileAccessFlag kOSKextLogFileAccessFlag@/link</code>,
 259  * <code>@link kOSKextLogKextBookkeepingFlag kOSKextLogKextBookkeepingFlag@/link </code>).
 260  *
 261  * <b>Byte 6:</b> <code>0xF000000</code> - Linking & patching
 262  * (<code>@link kOSKextLogLinkFlag kOSKextLogLinkFlag@/link</code> and
 263  * <code>@link kOSKextLogPatchFlag kOSKextLogPatchFlag@/link</code>).
 264  *
 265  * <b>Byte 7:</b> <code>0xF0000000</code> - Reserved.
 266  */
 267 typedef uint32_t OSKextLogSpec;
 268
 269 #if PRAGMA_MARK
 270 /********************************************************************/
 271 #pragma mark Masks
 272 /********************************************************************/
 273 #endif
 274 /*!
 275  * @define   kOSKextLogLevelMask
 276  * @abstract Masks the bottom 3 bits of an
 277  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code> to extract
 278  *           the raw level.
 279  */
 280 #define kOSKextLogLevelMask              ((OSKextLogSpec) 0x00000007)
 281
 282 /*!
 283  * @define   kOSKextLogKextOrGlobalMask
 284  * @abstract Determines whether per-kext log messages are output.
 285  *
 286  * @discussion
 287  * In filter specifications, if unset (the usual default),
 288  * then log messages associated with a kext are only output
 289  * if the kext has an
 290  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 291  * OSBundleEnableKextLogging@/link
 292  * property set to <code>true</code>.
 293  * If set, then all log messages associated with kexts
 294  * are output.
 295  *
 296  * In message specifications, if set it indicates that the message is either
 297  * not associated with a kext, or is associated with a kext that has an
 298  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 299  * OSBundleEnableKextLogging@/link
 300  * property set to <code>true</code>.
 301  */
 302 #define kOSKextLogKextOrGlobalMask       ((OSKextLogSpec) 0x00000008)
 303
 304
 305 /*!
 306  * @define   kOSKextLogFlagsMask
 307  * @abstract Masks the flag bits of an
 308  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>.
 309  */
 310 #define kOSKextLogFlagsMask              ((OSKextLogSpec) 0x0ffffff0)
 311
 312 /*!
 313  * @define   kOSKextLogFlagsMask
 314  * @abstract Masks the flag bits of an
 315  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>
 316  *           to which command-line <code>-v</code> levels apply.
 317  */
 318 #define kOSKextLogVerboseFlagsMask       ((OSKextLogSpec) 0x00000ff0)
 319
 320 /*!
 321  * @define   kOSKextLogConfigMask
 322  * @abstract Masks the config bits of an
 323  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>.
 324  */
 325 #define kOSKextLogConfigMask             ((OSKextLogSpec) 0xf0000000)
 326
 327 #if PRAGMA_MARK
 328 /********************************************************************/
 329 #pragma mark 0xF - Log Level
 330 /********************************************************************/
 331 #endif
 332
 333 /*!
 334  * @define   kOSKextLogExplicitLevel
 335  * @abstract Used when logging a message to overrides the current log filter,
 336  *           even if it's set to silent for log messages.
 337  *           This is essentially a pass-through for
 338  *           unconditional print messages to go
 339  *           through the logging engine.
 340  */
 341 #define kOSKextLogExplicitLevel          ((OSKextLogSpec)        0x0)
 342
 343 /*!
 344  * @define   kOSKextLogErrorLevel
 345  * @abstract Log messages concerning error conditions in any category.
 346  */
 347 #define kOSKextLogErrorLevel            ((OSKextLogSpec)        0x1)
 348
 349
 350 /*!
 351  * @define   kOSKextLogWarningLevel
 352  * @abstract Log messages concerning warning conditions in any category,
 353  *           which indicate potential error conditions,
 354  *           and notices, which may explain unexpected but correct behavior.
 355  */
 356 #define kOSKextLogWarningLevel          ((OSKextLogSpec)        0x2)
 357
 358
 359 /*!
 360  * @define   kOSKextLogBasicLevel
 361  * @abstract Log messages concerning top-level outcome in any category
 362  *           (kext load/unload, kext cache creation/extration w/# kexts).
 363  */
 364 #define kOSKextLogBasicLevel           ((OSKextLogSpec)        0x3)
 365
 366
 367 /*!
 368  * @define   kOSKextLogProgressLevel
 369  * @abstract Log messages concerning high-level progress in any category,
 370  *           such as sending a load request to the kernel,
 371  *           allocation/link/map/start (load operation),
 372  *           stop/unmap (unload operation), kext added/extracted (archive).
 373  */
 374 #define kOSKextLogProgressLevel          ((OSKextLogSpec)        0x4)
 375
 376
 377 /*!
 378  * @define   kOSKextLogStepLevel
 379  * @abstract Log messages concerning major steps in any category,
 380  *           such as sending personalities to the IOCatalogue when loading,
 381  *           detailed IPC with the kernel, or filtering of kexts for an archive.
 382  */
 383 #define kOSKextLogStepLevel             ((OSKextLogSpec)        0x5)
 384
 385
 386 /*!
 387  * @define   kOSKextLogDetailLevel
 388  * @abstract Log messages concerning specific details in any category,
 389  *           such as classes being registered/unregistered or
 390  *           operations on indivdual files in a kext.
 391  */
 392 #define kOSKextLogDetailLevel           ((OSKextLogSpec)        0x6)
 393
 394
 395 /*!
 396  * @define   kOSKextLogDebugLevel
 397  * @abstract Log messages concerning very low-level actions that are
 398  *           useful mainly for debugging the kext system itself.
 399  */
 400 #define kOSKextLogDebugLevel             ((OSKextLogSpec)        0x7)
 401
 402
 403 #if PRAGMA_MARK
 404 /********************************************************************/
 405 #pragma mark 0xF0 - General Activity, Load, Kernel IPC, Personalities
 406 /********************************************************************/
 407 #endif
 408
 409 /*!
 410  * @define   kOSKextLogGeneralFlag
 411  * @abstract Log messages about general activity in the kext system.
 412  */
 413 #define kOSKextLogGeneralFlag            ((OSKextLogSpec)       0x10)
 414
 415 /*!
 416  * @define   kOSKextLogLoadFlag
 417  * @abstract Log messages regarding kernel extension load, start/stop, or unload activity
 418  *           in the kernel.
 419  */
 420 #define kOSKextLogLoadFlag               ((OSKextLogSpec)       0x20)
 421
 422 /*!
 423  * @define   kOSKextLogIPCFlag
 424  * @abstract Log messages about any interaction between kernel and user space
 425  *           regarding kernel extensions.
 426  */
 427 #define kOSKextLogIPCFlag                ((OSKextLogSpec)       0x40)
 428
 429 /*!
 430  * @define   kOSKextLogArchiveFlag
 431  * @abstract Log messages about creating or processing a kext startup cache file
 432  *           (mkext or prelinked kernel).
 433  */
 434 #define kOSKextLogArchiveFlag           ((OSKextLogSpec)       0x80)
 435
 436
 437 #if PRAGMA_MARK
 438 /********************************************************************/
 439 #pragma mark 0xF00 - Reserved Verbose Area
 440 /********************************************************************/
 441 #endif
 442 // reserved slot for group               ((OSKextLogSpec)      0x100)
 443 // reserved slot for group               ((OSKextLogSpec)      0x200)
 444 // reserved slot for group               ((OSKextLogSpec)      0x400)
 445 // reserved slot for group               ((OSKextLogSpec)      0x800)
 446
 447 #if PRAGMA_MARK
 448 /********************************************************************/
 449 #pragma mark 0xF000 - Kext diagnostic activity
 450 /********************************************************************/
 451 #endif
 452
 453 /*!
 454  * @define   kOSKextLogValidationFlag
 455  * @abstract Log messages when validating kernel extensions.
 456  */
 457 #define kOSKextLogValidationFlag         ((OSKextLogSpec)     0x1000)
 458
 459 /*!
 460  * @define   kOSKextLogAuthenticationFlag
 461  * @abstract Log messages when autnenticating kernel extension files.
 462  *           Irrelevant in the kernel.
 463  */
 464 #define kOSKextLogAuthenticationFlag     ((OSKextLogSpec)     0x2000)
 465
 466 /*!
 467  * @define   kOSKextLogDependenciesFlag
 468  * @abstract Log messages when resolving dependencies for a kernel extension.
 469  */
 470 #define kOSKextLogDependenciesFlag       ((OSKextLogSpec)     0x4000)
 471
 472 // reserved slot for group               ((OSKextLogSpec)     0x8000)
 473
 474 #if PRAGMA_MARK
 475 /********************************************************************/
 476 #pragma mark 0xF0000 - Archives, caches, directory scan, file access
 477 /********************************************************************/
 478 #endif
 479
 480 /*!
 481  * @define   kOSKextLogDirectoryScanFlag
 482  * @abstract Log messages when scanning directories for kernel extensions.
 483  *           In the kernel logs every booter kext entry processed.
 484  */
 485 #define kOSKextLogDirectoryScanFlag      ((OSKextLogSpec)    0x10000)
 486
 487 /*!
 488  * @define   kOSKextLogFileAccessFlag
 489  * @abstract Log messages when performing any filesystem access (very verbose).
 490  *           Irrelevant in the kernel.
 491  */
 492 #define kOSKextLogFileAccessFlag         ((OSKextLogSpec)    0x20000)
 493
 494 /*!
 495  * @define   kOSKextLogKextBookkeepingFlag
 496  * @abstract Log messages about internal tracking of kexts. Can be very verbose.
 497  */
 498 #define kOSKextLogKextBookkeepingFlag    ((OSKextLogSpec)    0x40000)
 499
 500 // reserved slot for group               ((OSKextLogSpec)    0x80000)
 501
 502 #if PRAGMA_MARK
 503 /********************************************************************/
 504 #pragma mark 0xF00000 - Linking & Patching
 505 /********************************************************************/
 506 #endif
 507
 508 /*!
 509  * @define   kOSKextLogLinkFlag
 510  * @abstract Log messages about linking.
 511  */
 512 #define kOSKextLogLinkFlag               ((OSKextLogSpec)   0x100000)
 513
 514 /*!
 515  * @define   kOSKextLogPatchFlag
 516  * @abstract Log messages about patching.
 517  */
 518 #define kOSKextLogPatchFlag              ((OSKextLogSpec)   0x200000)
 519
 520 // reserved slot for group               ((OSKextLogSpec)   0x400000)
 521 // reserved slot for group               ((OSKextLogSpec)   0x800000)
 522
 523 #if PRAGMA_MARK
 524 /********************************************************************/
 525 #pragma mark 0xF000000 - Reserved
 526 /********************************************************************/
 527 #endif
 528
 529 // reserved slot for grouping            ((OSKextLogSpec)  0x1000000)
 530 // reserved slot for grouping            ((OSKextLogSpec)  0x2000000)
 531 // reserved slot for grouping            ((OSKextLogSpec)  0x4000000)
 532 // reserved slot for grouping            ((OSKextLogSpec)  0x8000000)
 533
 534
 535 #if PRAGMA_MARK
 536 /********************************************************************/
 537 #pragma mark 0xF0000000 - Config Flags
 538 /********************************************************************/
 539 #endif
 540
 541 // reserved slot for grouping            ((OSKextLogSpec) 0x10000000)
 542 // reserved slot for grouping            ((OSKextLogSpec) 0x20000000)
 543 // reserved slot for grouping            ((OSKextLogSpec) 0x40000000)
 544
 545 #if PRAGMA_MARK
 546 /********************************************************************/
 547 #pragma mark Predefined Specifications
 548 /********************************************************************/
 549 #endif
 550
 551 /*!
 552  * @define   kOSKextLogSilentFilter
 553  * @abstract For use in filter specs:
 554  *           Ignore all log messages with a log level greater than
 555  *           <code>@link kOSKextLogExplicitLevel kOSKextLogExplicitLevel@/link</code>.
 556  */
 557 #define kOSKextLogSilentFilter           ((OSKextLogSpec)        0x0)
 558
 559 /*!
 560  * @define   kOSKextLogShowAllFilter
 561  * @abstract For use in filter specs:
 562  *           Print all log messages not associated with a kext or
 563  *           associated with a kext that has
 564  *           @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 565  *           OSBundleEnableKextLogging@/link
 566  *           set to <code>true</code>.
 567  */
 568 #define kOSKextLogShowAllFilter          ((OSKextLogSpec) 0x0ffffff7)
 569
 570 /*!
 571  * @define   kOSKextLogShowAllKextsFilter
 572  * @abstract For use in filter specs:
 573  *           Print all log messages has
 574  *           @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 575  *           OSBundleEnableKextLogging@/link
 576  *           set to <code>true</code>.
 577  */
 578 #define kOSKextLogShowAllKextsFilter     ((OSKextLogSpec) \
 579                                            (kOSKextLogShowAllFilter | \
 580                                             kOSKextLogKextOrGlobalMask))
 581
 582 #if PRAGMA_MARK
 583 #pragma mark -
 584 /********************************************************************/
 585 #pragma mark Kext Version String Processing
 586 /********************************************************************/
 587 #endif
 588 /*!
 589  * @group Kext Version String Processing
 590  * Functions for working with kext versions and compatible versions.
 591  */
 592
 593 /*!
 594  * @typedef   OSKextVersion
 595  * @abstract  An encoded kext version that can be compared arithmetically.
 596  *
 597  * @discussion
 598  * A value of zero (<code>@link kOSKextVersionUndefined kOSKextVersionUndefined@/link</code>)
 599  * is <i>not</i> equivalent to a version string of "0.0",
 600  * and typically means there is no version specified
 601  * (for example, that there is no CFBundleVersion property at all).
 602  * Values below zero are invalid.
 603  *
 604  * The encoding used is subject to change,
 605  * and should never be saved to permanent storage.
 606  * Always use proper version strings in files and interprocess communication.
 607  */
 608 typedef int64_t OSKextVersion;
 609
 610 /*!
 611  * @define    kOSKextVersionMaxLength
 612  * @abstract  The length of a string buffer
 613  *            guaranteed to be able to hold a kext version.
 614  *
 615  * @discussion
 616  * Kext versions use an extended Mac OS 'vers' format with double the number
 617  * of digits before the build stage: ####.##.##s{1-255} where 's'
 618  * is a build stage 'd', 'a', 'b', 'f' or 'fc'.
 619  */
 620 #define kOSKextVersionMaxLength (20)
 621 // with a few bytes to spare including a nul byte
 622 // xx-review: Should we make this much bigger in case we ever need longer strings?
 623
 624 /*!
 625  * @define    kOSKextVersionUndefined
 626  * @abstract  The undefined version.
 627  *
 628  * @discussion
 629  * This value of <code>@link OSKextVersion OSKextVersion@/link</code> represents the
 630  * lack of a version
 631  * (for example, that there is no CFBundleVersion property at all).
 632  */
 633 #define kOSKextVersionUndefined  (0)
 634
 635 /*!
 636  * @function OSKextParseVersionString
 637  *
 638  * @abstract
 639  * Parses a kext version string into an <code>@link OSKextVersion OSKextVersion@/link</code>.
 640  *
 641  * @param  versionString  The kext version string to parse.
 642  *
 643  * @result
 644  * An encoded kext version that can be compared numerically
 645  * against other encoded kext versions,
 646  * <0 if <code>versionString</code> is <code>NULL</code>, empty,
 647  * or cannot be parsed.
 648  *
 649  * @discussion
 650  * Kext versions use an extended Mac OS 'vers' format with double the number
 651  * of digits before the build stage: ####.##.##s{1-255} where 's'
 652  * is a build stage 'd', 'a', 'b', 'f' or 'fc'.
 653  */
 654 OSKextVersion OSKextParseVersionString(const char * versionString);
 655
 656
 657 /*!
 658  * @function OSKextVersionGetString
 659  *
 660  * @abstract
 661  * Formats an encoded <code>@link OSKextVersion OSKextVersion@/link</code> into a string
 662  * representation.
 663  *
 664  * @param  aVersion
 665  *         The encoded version to format.
 666  * @param  buffer
 667  *         A C string buffer of at least
 668  *         <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code> bytes.
 669  * @param  bufferSize  The size in bytes of <code>buffer</code>.
 670  *
 671  * @result
 672  * <code>TRUE</code> if the encoded version is formatted successfully.
 673  * <code>FALSE</code> if <code>buffer</code> is <code>NULL</code> or
 674  * <code>bufferSize</code> is less than
 675  * <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code>.
 676  *
 677  * @discussion
 678  * The return value strictly indicates whether <code>buffer</code>
 679  * is large enough to hold the result.
 680  * If <code>aVersion</code> is 0, the resulting string is "(missing)".
 681  * If <code>aVersion</code> is less than 0
 682  * or is not a valid kext version encoding,
 683  * the resulting string is "(invalid)".
 684  */
 685 Boolean OSKextVersionGetString(
 686         OSKextVersion   aVersion,
 687         char          * buffer,
 688         uint32_t        bufferSize);
 689
 690
 691 #ifdef KERNEL
 692
 693
 694 #if PRAGMA_MARK
 695 /********************************************************************/
 696 #pragma mark -
 697 #pragma mark Weak linking
 698 /********************************************************************/
 699 #endif
 700 #ifdef XNU_KERNEL_PRIVATE
 701 void kext_weak_symbol_referenced(void);
 702 #endif /* XNU_KERNEL_PRIVATE */
 703
 704 #if PRAGMA_MARK
 705 #pragma mark -
 706 /********************************************************************/
 707 #pragma mark Miscellaneous Kernel-Only Kext Functions
 708 /********************************************************************/
 709 #endif
 710
 711 /*!
 712  * @function kext_get_vm_map
 713  * @abstract Returns the vm_map from which the kext was allocated.
 714  *
 715  * @param info The kmod_info_t structure of the kext.
 716  * @result The vm_map from which the kext was allocated.  This function
 717  * cannot return <code>NULL</code>.
 718  */
 719 vm_map_t kext_get_vm_map(kmod_info_t * info);
 720
 721 #ifdef XNU_KERNEL_PRIVATE
 722
 723 #if CONFIG_DTRACE
 724 /*!
 725  * @function OSKextRegisterKextsWithDTrace
 726  * @abstract
 727  * DTrace calls this once when it has started up so that the kext system
 728  * will register any already-loaded kexts with it.
 729  */
 730 void OSKextRegisterKextsWithDTrace(void);
 731
 732 #endif /* CONFIG_DTRACE */
 733
 734 /*!
 735  * @function kext_dump_panic_lists
 736  * @abstract Prints compacted lists of last unloaded & all loaded kexts
 737  *           during a panic.
 738  *
 739  * @param printf_func The printf-style function to use for output.
 740  */
 741 void kext_dump_panic_lists(int (*printf_func)(const char *fmt, ...));
 742
 743 #endif /* XNU_KERNEL_PRIVATE */
 744
 745 #ifdef XNU_KERNEL_PRIVATE
 746
 747 #if PRAGMA_MARK
 748 #pragma mark -
 749 /********************************************************************/
 750 #pragma mark Kext Loading C Functions
 751 /********************************************************************/
 752 #endif
 753 /*!
 754  * @function OSKextGetLoadTagForBundleIdentifier
 755  * @abstract Look up the load tag for a kext.
 756  *
 757  * @param  kextIdentifier  The bundle identifier of the kext to look up.
 758  * @result
 759  * The load tag of the requested kext, or
 760  * <code>@link //apple_ref/c/macro/kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>
 761  * if the kext was not found.
 762  *
 763  * @discussion
 764  * A load tag uniquely identifies a loaded kext.
 765  * It can be found as the <code>id</code> field of a loaded kext's
 766  * <code>kmod_info_t</code> struct.
 767  *
 768  * Note that a load tag represents a specific loaded instance of a kext.
 769  * If that kext is unloaded, the load tag is no longer a valid reference.
 770  * If the same kext is later reloaded, it will have a new load tag.
 771  *
 772  * You can use the load tag to adjust a kext's reference count
 773  * via
 774  * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag
 775  * OSKextRetainKextWithLoadTag@/link</code>
 776  * and
 777  * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag
 778  * OSKextReleaseKextWithLoadTag@/link</code>,
 779  * so that the kext is automatically unloaded when no references remain,
 780  * or to unload the kext immediately
 781  * with <code>@link //apple_ref/c/func/OSKextUnloadKextWithLoadTag OSKextUnloadKextWithLoadTag@/link</code>.
 782  *
 783  * Those functions are intended for use with non-IOKit kexts
 784  * (specifically, kexts that define no subclasses of
 785  * <code>@link //apple_ref/doc/class/IOServiceIOService@/link</code>).
 786  * Pure IOKit kexts are managed via instance counts
 787  * of their libkern C++ object classes;
 788  * using those functions on them will only interfere with that mechanism.
 789  * If you have a hybrid kext with both IOService subclasses and non-IOKit code,
 790  * however, you may want to use reference counting for the non-IOKit portions:
 791  * that way the kext will only unload automaticaly
 792  * when there are no C++ objects and the kext reference count is zero.
 793  */
 794 uint32_t OSKextGetLoadTagForBundleIdentifier(
 795         const char * kextIdentifier);
 796
 797
 798 /*!
 799  * @function OSKextUnloadKextWithLoadTag
 800  * @abstract Stop and unload a kext based on its load tag.
 801  *
 802  * @param  loadTag   The load tag of the kext to unload.
 803  * @result
 804  * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code>
 805  * if the kext was found and unloaded.
 806  * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound
 807  * kOSKextReturnNotFound@/link</code>
 808  * if the kext was not found.
 809  * <code>@link //apple_ref/c/macro/kOSKextReturnInUse
 810  * kOSKextReturnInUse@/link</code>
 811  * if the kext has outstanding references
 812  * or if there are instances of its libkern C++ subclasses.
 813  * Other return values indicate a failure to unload the kext,
 814  * typically because the module stop routine failed.
 815  *
 816  * @discussion
 817  * A panic will occur if a kext calls this function to unload itself.
 818  * The safest way for a kext to unload itself is to call
 819  * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag
 820  * OSKextRetainKextWithLoadTag@/link</code>
 821  * with its own load tag
 822  * (the <code>id</code> field of its <code>kmod_info_t</code> struct),
 823  * followed by
 824  * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag
 825  * OSKextReleaseKextWithLoadTag@/link</code>;
 826  * this will schedule the kext for unload on a separate thread.
 827  *
 828  * This function can be used when reference-based autounloading is not
 829  * appropriate.
 830  * If a kernel system or kext is already monitoring
 831  * the need for a kext,
 832  * it can simply call this function when it's known that the kext is not needed.
 833  */
 834 OSReturn OSKextUnloadKextWithLoadTag(uint32_t loadTag);
 835
 836 #endif /* XNU_KERNEL_PRIVATE */
 837
 838 #endif /* KERNEL */
 839
 840 #if PRAGMA_MARK
 841 #pragma mark -
 842 /********************************************************************/
 843 #pragma mark Loaded Kext Summary
 844 /********************************************************************/
 845 #endif
 846
 847 /*!
 848  * @define kOSKextLoadedKextSummaryVersion
 849  * @abstract The current version of the loaded kext summary headers.
 850  */
 851 #define kOSKextLoadedKextSummaryVersion 2
 852
 853 /*!
 854  * @typedef OSKextLoadedKextSummary
 855  * @abstract A structure that describes a loaded kext.
 856  *
 857  * @field name The kext's bundle identifier.
 858  * @field uuid The kext's UUID;
 859  * @field address The kext's load address.
 860  * @field size The kext's load size.
 861  * @field version The binary format (OSKextVersion) version of the kext.
 862  * @field loadTag The kext's load tag.
 863  * @field flags Internal tracking flags.
 864  * @field reference_list who this refs (links on).
 865  *
 866  * @discussion
 867  * The OSKextLoadedKextSummary structure contains a basic set of information
 868  * about the kext to facilitate kext debugging and panic debug log output.
 869  */
 870 typedef struct _loaded_kext_summary {
 871         char        name[KMOD_MAX_NAME];
 872         uuid_t      uuid;
 873         uint64_t    address;
 874         uint64_t    size;
 875         uint64_t    version;
 876         uint32_t    loadTag;
 877         uint32_t    flags;
 878         uint64_t    reference_list;
 879 } OSKextLoadedKextSummary;
 880
 881 /*!
 882  * @typedef OSKextLoadedKextSummaryHeader
 883  * @abstract A structure that describes the set of loaded kext summaries.
 884  *
 885  * @field version The version of the loaded kext summary structures.
 886  * @field entry_size The size of each entry in summaries.
 887  * @field numSummaries The number of OSKextLoadedKextSummary structures
 888  *        following the header.
 889  * @field summaries A convenience pointer to the array of summaries following
 890  *        the header.
 891  *
 892  * @discussion
 893  * The OSKextLoadedKextSummaryHeader describes the set of loaded kext summaries
 894  * available for use by the debugger or panic log routine.
 895  * The array of summaries contains one OSKextLoadedKextSummary for every kext
 896  * that declares an executable and is not an interface to the kernel.
 897  */
 898 typedef struct _loaded_kext_summary_header {
 899         uint32_t version;
 900         uint32_t entry_size;
 901         uint32_t numSummaries;
 902         uint32_t reserved; /* explicit alignment for gdb  */
 903         OSKextLoadedKextSummary summaries[0];
 904 } OSKextLoadedKextSummaryHeader;
 905
 906 /*!
 907  * @var gLoadedKextSummaries
 908  * @abstract The global pointer to the current set of loaded kext summaries.
 909  */
 910 extern OSKextLoadedKextSummaryHeader * gLoadedKextSummaries;
 911
 912 /*!
 913  * @var gLoadedKextSummariesTimestamp
 914  *
 915  * @abstract This will be set to mach_absolute_time() around updates to
 916  * gLoadedKextSummaries.  Ie. immediately before gLoadedKextSummaries is set to
 917  * zero, and immediately after it is set to a new value.
 918  */
 919 extern uint64_t gLoadedKextSummariesTimestamp;
 920
 921 /*!
 922  * @function OSKextLoadedKextSummariesUpdated
 923  * @abstract Called when gLoadedKextSummaries has been updated.
 924  *
 925  * @discussion
 926  * gLoadedKextSummaries is updated when a kext is loaded or unloaded.
 927  * When the update is complete, OSKextLoadedKextSummariesUpdated is called.
 928  * gdb can set a breakpoint on this function to detect kext loads and unloads.
 929  */
 930 void OSKextLoadedKextSummariesUpdated(void);
 931
 932 #ifdef XNU_KERNEL_PRIVATE
 933
 934 extern const vm_allocation_site_t * OSKextGetAllocationSiteForCaller(uintptr_t address);
 935 extern uint32_t                     OSKextGetKmodIDForSite(const vm_allocation_site_t * site,
 936     char * name, vm_size_t namelen);
 937 extern void                         OSKextFreeSite(vm_allocation_site_t * site);
 938
 939 #if CONFIG_IMAGEBOOT
 940 extern int OSKextGetUUIDForName(const char *, uuid_t);
 941 #endif
 942
 943 extern vm_tag_t gIOSurfaceTag;
 944
 945 extern void *OSKextKextForAddress(const void *addr);
 946
 947 #endif /* XNU_KERNEL_PRIVATE */
 948
 949 __END_DECLS
 950
 951 #endif /* ! _LIBKERN_OSKEXTLIBPRIVATE_H */