Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)
[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]
FreeBSD/Linux Kernel Cross Reference
sys/libkern/libkern/OSKextLibPrivate.h
Version:
- FREEBSD - FREEBSD-13-STABLE - FREEBSD-13-0 - FREEBSD-12-STABLE - FREEBSD-12-0 - FREEBSD-11-STABLE - FREEBSD-11-0 - FREEBSD-10-STABLE - FREEBSD-10-0 - FREEBSD-9-STABLE - FREEBSD-9-0 - FREEBSD-8-STABLE - FREEBSD-8-0 - FREEBSD-7-STABLE - FREEBSD-7-0 - FREEBSD-6-STABLE - FREEBSD-6-0 - FREEBSD-5-STABLE - FREEBSD-5-0 - FREEBSD-4-STABLE - FREEBSD-3-STABLE - FREEBSD22 - l41 - OPENBSD - linux-2.6 - MK84 - PLAN9 - xnu-8792
SearchContext: - none - 3 - 10
SearchContext: - none - 3 - 10
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=""> 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 */
Cache object: c857a5f0fcbfe1e367c53b575d0298e8
[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]