The porting flow covers the macos-27.3-26C5035r profile from profile selection to the porting record: the macOS profile page lists the profile contents, host inputs, board.toml override, Data seed, build commands, driver adaptations and boot checkpoints, and the steps, arm64e, packaging, records, bring-up, building, requirements and reference pages point to it. The iPadOS instructions are unchanged. Porting pages link porting pages for driver topics: Develop a driver and Brightness interface are porting pages, and component names in porting pages are plain text. English and Chinese pages.
5.8 KiB
Develop a driver
Write a driver when the component catalog has no
implementation for the hardware. Define its boundary first.
Run the build examples from the assembled target tree that ./unixnu tree reports.
1. Choose the layer
| Need | Layer | Built as | Loaded by |
|---|---|---|---|
| Display, input or storage before XNU | UEFI driver | EDK II .efi |
Firmware dispatch, [[driver]] in unixnu.toml, or a kit |
| Platform, CPU, storage, display, GPU or any service inside XNU | Built-in XNU driver | Static archive linked into the kernel | The kernel at boot |
| A bundle that an external loader validates and injects | Kext bundle | .kext |
A loader that accepts kext requests. The shipped DarwinBoot starts prelinked kernels |
2. Match the provider
ArmDTPlatform publishes an IOPlatformDevice nub for every arm-io child of
the ADT. A driver binds through an IOKit personality:
| Key | Meaning |
|---|---|
IOClass |
Driver class |
IOProviderClass |
Provider class: IOPlatformDevice for SoC devices, IOPlatformExpertDevice for /product and /buttons, IOResources for global services |
IONameMatch |
Provider name or a compatible value |
IOPropertyMatch |
Exact provider property values |
IOResourceMatch |
Resource that must exist before probing, for example IOBSD |
IOProbeScore |
Higher scores probe first |
IOMatchCategory |
Lets a second driver match the same provider |
Built-in personalities are added to iokit/KernelConfigTables.cpp by a patch,
guarded by the driver's kernel flag:
#if defined(XNU_MY_DRIVER) && XNU_MY_DRIVER
" ,{"
" 'IOClass' = MyDriver;"
" 'IOProviderClass' = IOPlatformDevice;"
" 'IONameMatch' = 'vendor,my-device';"
" 'IOProbeScore' = 1000:32;"
" }"
#endif
The node's compatible and unixnu,adt-name come from the board DTS, see
device tree. A format 2 reg property is a sequence of
little-endian u64 address and size pairs.
3. Write the driver class
class MyDriver : public IOService {
OSDeclareDefaultStructors(MyDriver)
public:
IOService *probe(IOService *provider, SInt32 *score) override;
bool start(IOService *provider) override;
void stop(IOService *provider) override;
};
OSDefineMetaClassAndStructors(MyDriver, IOService)
bool MyDriver::start(IOService *provider)
{
if (!IOService::start(provider)) return false;
OSData *reg = OSDynamicCast(OSData, provider->getProperty("reg"));
if (reg == nullptr || reg->getLength() != 2 * sizeof(uint64_t)) return false;
registerService();
return true;
}
start() reads the provider properties, maps registers, allocates DMA buffers
through the device's SMMU context, installs interrupt sources and calls
registerService(). A failed start() releases what it took and returns false.
4. Compile against the kernel ABI
The kernel build records the exact compiler command of every object in a
.cpo.json file, for example:
build/xnu/ios-obj/DEVELOPMENT_ARM64_BCM2837/iokit/DEVELOPMENT/IOPlatformExpert.cpo.json
The driver recipe reads one record, replaces the source and output paths, adds its include paths and runs the compiler. The object then has the architecture, platform and deployment version of the selected kernel. A driver that subclasses or calls a class of the original kernelcache also needs that build's class layout, virtual method slots and symbol bindings, checked against the kernelcache of the selected OS profile. Each OS profile has its own.
5. Link into the kernel
-
Archive the objects, for example
build/my-driver/libMyDriver.a. -
Put the recipe in the device repository's
scripts/and add it to[kernel] archivesin dependency order. SetCONFIG_XNU_BUILD_ARCHIVES=y. -
Add the archive to the kernel link in the defconfig:
CONFIG_XNU_EXTRA_LD_ARCHIVES="-Wl,-force_load,{tree}/build/my-driver/libMyDriver.a"-force_loadkeeps every object, including classes nothing references. -
Enable the flag that guards the personality:
CONFIG_XNU_<NAME>=yin the defconfig, read inscripts/build-xnu-4k-baseline.shand passed toKernelConfigTables.cpoas-DXNU_<NAME>=1, see Build the kernel. A board-started service is called from the board initialization instead. -
Run
./unixnu build kernelfrom the main checkout and inspect the archive log underlogs/and the prelink report.
A reusable driver becomes a component: give it a repository and a
components.toml entry with build, outputs, dependencies and OS ABI, then
select it with component:<ID>.
6. Add a UEFI driver
A UEFI driver is an EDK II module with an INF, listed in a DSC.
| Location | Build | Load |
|---|---|---|
| Firmware volume | Add the INF to the firmware DSC and FDF, then run ./unixnu build firmware |
Firmware dispatch |
| Payload | Build a standalone .efi |
[[driver]] in unixnu.toml or in a kit, see boot configuration |
The driver receives the args of its [[driver]] entry as load options.
connect = true runs ConnectController on every handle after it starts.
Follow firmware integration for the DSC and FDF.
7. Verify
| Check | Method |
|---|---|
| Compile | -Wall -Wextra -Werror on top of the recorded flags |
| Archive | llvm-ar t and llvm-nm --defined-only show the objects and the start symbol |
| Host logic | Compile the hardware-independent functions as a host test |
| Device | Boot and read the driver's start line with log capture |
Record the result in the owning area of porting.toml, then return to the adaptation sequence.