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