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