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