Info.plist Properties for Kernel Extensions
This appendix describes the properties you can use for your kext’s Info.plist
file.
Top-Level Properties
The
CFBundleIdentifier
property uniquely identifies your kext. Two kexts with the same value for this property cannot both be loaded into the kernel. The value for this property should be in a reverse-DNS format, for examplecom.MyCompany.driver.MyDriver
for an I/O Kit driver ororg.MyCompany.kext.MyKext
for a generic kext.This property is required.
The
CFBundleExecutable
property specifies the name of your kext’s executable code. Xcode automatically creates and populates this value correctly for all kext projects, so you should not need to change it.This property is required if your kext contains an executable. If you are developing a codeless kext, do not include this property.
The
CFBundleVersion
property indicates your kext’s version. Kext version numbers must adhere to a strict format:The version number is divided into three parts by periods, for example
3.1.2
.The first number represents the most recent major release, the second number represents the most recent significant revision, and the third number represents the most recent minor bug fix.
The first number is limited to four digits; the second and third numbers are limited to two digits each.
If the value of the third number is
0
, you can omit it and the second period.While developing a new version of your kext, include a suffix after the number that is being updated, for example
3.1.3a1
.The letter in the suffix represents the stage of development the new version is in (development, alpha, beta, or final candidate, represented by
d
,a
,b
, andfc
), and the number in the suffix is the build version. The build version cannot be0
or exceed255
.When you release the new version of your kext, make sure to remove the suffix.
This property is required.
The
OSBundleLibraries
property is a dictionary that lists the library kexts that your kext links against.Each element in the dictionary consists of a key-value pair. The key is the CFBundleIdentifier of the dependency (such as
com.apple.kernel.mach
), and the value is the required version of the dependency. When a kext is about to be loaded, the required version of each element in itsOSBundleLibraries
dictionary is compared to the current and compatible versions of the dependency. If the required version lies between the current version of the dependency and itsOSBundleCompatibleVersion
value, the kext and its dependencies are deemed compatible.You determine the kexts to add with the
kextlibs
command-line tool (see Determine Kext Dependencies).This property is required if your kext contains an executable.
This property can be architecture-specific (see Architecture-Specific Properties).
The
OSBundleRequired
property informs the system that your kext must be available for loading during early boot. Kexts that don’t set this property can’t load during early boot. You can specify one of the following values for this property:This kext is required to mount root, regardless of where root comes from—for example, platform drivers and families, PCI, or USB.
This kext is required to mount root on a remote volume—for example, the network family, Ethernet drivers, or NFS.
This kext is required to mount root on a local volume—for example, the storage family, disk drivers, or file systems.
This kext is required to provide character console support (single-user mode)—for example, keyboard drivers or the ADB family.
This kext is required even during safe-boot (unnecessary extensions disabled)—for example, mouse drivers or graphics drivers.
Root
Network-Root
Local-Root
Console
Safe Boot
This property can be architecture-specific (see Architecture-Specific Properties).
The
OSBundleCompatibleVersion
property is used to enable linking against a kext as a library. It indicates the oldest version of your library kext that other kexts can link against and still use the current version successfully.You should increment the value of this property when you remove a symbol from the library, or when an exported symbol's semantics change significantly enough to impact binary compatibility.
The format of this value is the same as that of
CFBundleVersion
.This property can be architecture-specific (see Architecture-Specific Properties).
The
OSBundleAllowUserLoad
property allows non-root users to load your kext. Using this property is not recommended.I/O Kit drivers should never include this property, because they are loaded by the kernel when they are needed.
Specify a boolean value of true to enable this option.
This property can be architecture-specific (see Architecture-Specific Properties).
The
OSBundleEnableKextLogging
property indicates that logging information specific to your kext should be logged in the kernel log (available at/var/log/kernel.log
). Thekextutil
tool automatically enables this option to assist with debugging. Specify a boolean value oftrue
to enable this option. Seekext_logging
for more information.This property can be architecture-specific (see Architecture-Specific Properties).
The
IOKitPersonalities
property is used by I/O Kit drivers. It is a nested dictionary of information describing hardware that the driver can operate.See IOKitPersonalities Properties for a list of properties to include in the
IOKitPersonalities
dictionary.See Driver Personalities and Matching Languages in IOKit Fundamentals for more information on personalities.
This property is required for I/O Kit drivers.
This property can be architecture-specific (see Architecture-Specific Properties).
CFBundleIdentifier
CFBundleExecutable
CFBundleVersion
OSBundleLibraries
OSBundleRequired
OSBundleCompatibleVersion
OSBundleAllowUserLoad
OSBundleEnableKextLogging
IOKitPersonalities
IOKitPersonalities Properties
The
IOClass
property names the C++ class to instantiate from your driver when it matches on a nub.The
IOKitDebug
property indicates that I/O Kit-specific events such as attaching, matching, and probing should be logged in the kernel log (available at/var/log/kernel.log
). The value of this property defines which events are logged. To log all relevant information, specify65535
as the value. SeeIOKitDebug.h
(available in/System/Library/Frameworks/Kernel.framework/Headers/IOKit
) for itemized logging values.The
IOProviderClass
property names the C++ class of the I/O Kit device object that your driver matches on. This is typically the nub that controls the port that your device connects to. For example, if your driver connects to a PCI bus, you should specifyIOPCIDevice
as your driver’s provider class.The
IOMatchCategory
property allows multiple drivers with unique values for the property to match on the same provider class. Typically, only one driver can match on a given provider class. Include this property if you are matching onIOResources
or on a port with multiple devices attached to it. The value for this property should be the same as the value forCFBundleIdentifier
, with periods replaced with underscores (for examplecom_MyCompany_driver_MyDriver
).The
IOResourceMatch
property allows you to declare a dependency between your driver and a specific resource, such as the BSD kernel or a particular resource on a device, like an audio video jack. If you provide this property, your driver will not load into the kernel until the specified resource is available.
IOClass
IOKitDebug
IOProviderClass
IOMatchCategory
IOResourceMatch
Architecture-Specific Properties
Top-level kext Info.plist
properties that begin with OS
or IO
have architecture-specific versions you can use to differentiate your kext’s behavior on different architectures. To specify an architecture-specific property, add an underscore followed by the architecture name to a property name, for example, OSBundleCompatibleVersion_x86_64
or OSBundleCompatibleVersion_i386
. Make sure to keep the base property in your Info.plist
file for backwards compatibility.
Copyright © 2003, 2010 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2010-09-01