5.7 KiB
UEFI drivers
Procedure
- Prepare the package DEC and its protocol declarations. Generate distinct file
and protocol GUIDs with
uuidgen; fill the example identifiers below. - Add the driver source and INF, then register it in the target DSC. Place public
protocol headers under the package's
Include/Protocol/directory. - For firmware dispatch, add the INF to the target FDF and run
./unixnu build firmwarefrom UniXNU. Follow firmware integration. - For file loading, build the EFI module and add its path to the payload configuration as shown below. Repack the payload and boot image.
- Check driver-start logs and protocol publication before starting its consumer.
A UEFI driver is an EDK II module built as a .efi image. It runs in boot services and can publish protocols, bind devices and prepare hardware for the next stage.
The shared UniXNURamDiskDxe module in package/UniXNUPkg/Driver/ exposes a Mu-Silicium FDT initrd as a read-only Block I/O device. Include it in the firmware DSC and FDF with DiskIoDxe and FAT support. See firmware integration.
Module layout
MyDriver/
MyDriver.c
MyDriver.inf
# public header: MyPkg/Include/Protocol/MyProtocol.h
MyDriver.inf:
[Defines]
INF_VERSION = 0x00010019
BASE_NAME = MyDriver
FILE_GUID = 00000000-0000-0000-0000-000000000000
MODULE_TYPE = UEFI_DRIVER
VERSION_STRING = 0.1
ENTRY_POINT = MyDriverEntry
[Sources]
MyDriver.c
[Packages]
MdePkg/MdePkg.dec
UniXNUPkg/UniXNUPkg.dec
[LibraryClasses]
MemoryAllocationLib
UefiBootServicesTableLib
UefiDriverEntryPoint
[Protocols]
gMyProtocolGuid ## PRODUCES
gEfiLoadedImageProtocolGuid ## CONSUMES
MyDriver.c:
#include <Uefi.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Protocol/LoadedImage.h>
#include <Protocol/MyProtocol.h>
STATIC MY_PROTOCOL mProtocol = { MY_SIGNATURE, NULL };
EFI_STATUS
EFIAPI
MyDriverEntry (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
{
EFI_LOADED_IMAGE_PROTOCOL *Loaded;
EFI_HANDLE Handle = NULL;
if (!EFI_ERROR (gBS->HandleProtocol (
ImageHandle, &gEfiLoadedImageProtocolGuid, (VOID **)&Loaded)) &&
(Loaded->LoadOptions != NULL))
{
mProtocol.Options = AllocateCopyPool (
Loaded->LoadOptionsSize, Loaded->LoadOptions);
}
return gBS->InstallMultipleProtocolInterfaces (
&Handle, &gMyProtocolGuid, &mProtocol, NULL);
}
The driver receives its LoadOptions from the UniXNU args field.
Build
Add the INF to a DSC:
[Components]
MyPkg/MyDriver/MyDriver.inf
Build with EDK II:
build -p MyPkg/MyPkg.dsc -a AARCH64 -b DEBUG -t CLANGPDB -n 8
The result is Build/MyPkg/DEBUG_CLANGPDB/AARCH64/MyDriver.efi.
The UniXNU package DSC contains the standalone build:
package/UniXNUPkg/UniXNUPkg.dsc
package/build.sh copies the EFI binaries to Build/Out/AARCH64-DEBUG.
Load from UniXNU
Copy the driver to the payload volume and add an entry to unixnu.toml:
[[driver]]
path = "Drivers/MyDriver.efi"
args = "board=1"
connect = true
enabled = true
| Key | Meaning |
|---|---|
path |
Path relative to \EFI\UniXNU, or fv:<GUID> |
args |
Load options string |
connect |
Run ConnectController on every handle after the driver starts |
enabled |
false skips the entry |
A kit can add the driver:
[[driver]]
file = "MyDriver.efi"
args = "from-kit"
The kit path resolves relative to the kit directory.
Firmware volume path
fv:<GUID> loads a file from any firmware volume by file GUID:
[[driver]]
path = "fv:00000000-0000-0000-0000-000000000000"
This loads a driver already embedded in the firmware without copying it to the payload.
Firmware volume inclusion
To embed a driver in the firmware:
- Add the INF to the platform DSC under
[Components]. - Add the INF to the FDF under
[FV.<name>] INF. - Rebuild the firmware.
The firmware dispatcher starts DXE drivers during dispatch. A UEFI application in the FV is started by UniXNUDxe or by a Boot#### option.
Driver model
A UEFI driver that follows the driver model implements EFI_DRIVER_BINDING_PROTOCOL:
| Function | Role |
|---|---|
Supported |
Reports whether the driver can handle a controller |
Start |
Installs child handles or protocols |
Stop |
Removes them |
UniXNU calls ConnectController on every handle when connect = true and [boot] connect_all is true. This binds driver-model drivers to new devices.
Protocols
A protocol is a GUID and a function table:
typedef struct {
UINT64 Signature;
EFI_STATUS (EFIAPI *DoWork)(IN struct _MY_PROTOCOL *This);
} MY_PROTOCOL;
extern EFI_GUID gMyProtocolGuid;
The producer installs it with InstallMultipleProtocolInterfaces. A consumer locates it with LocateProtocol or HandleProtocol.
Example modules
| Module | Purpose |
|---|---|
UniXNUPkg/Test/SampleDriver |
Installs UNIXNU_SAMPLE_PROTOCOL and records its load options |
UniXNUPkg/Test/HelloPayload |
Test application for injection |
UniXNUPkg/Driver/UniXNUDxe |
Registers the UniXNU application as a boot option |
drivers/DarwinBoot |
Installs UNIXNU_LOADER_PROTOCOL |
Logging
UniXNU logs every driver result:
UNIXNU: driver <path> (<origin>): started
UNIXNU: driver <path> (<origin>): load failed: <status>
UNIXNU: driver <path> (<origin>): start failed: <status>
The menu shows the loaded and failed counts and the first failure reason.