Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rikitav/Unified.Firmware/llms.txt

Use this file to discover all available pages before exploring further.

A UEFI device path is a packed, variable-length binary structure that describes every step of the hardware route to a boot image — from the PCI bus controller, through the disk partition, down to the exact EFI executable file. Each step is a typed node called a device path protocol. Unified.Firmware models these nodes as strongly-typed C# classes so you can build, inspect, and serialize device paths without writing any binary marshalling code yourself.

​
DevicePathProtocolBase

All device path protocol classes inherit from the abstract DevicePathProtocolBase. It captures the two header fields that appear in every UEFI device path node and declares the serialization contract. 
public abstract class DevicePathProtocolBase(DeviceProtocolType type, byte subType)
{
    // Type field from the UEFI device path node header
    public DeviceProtocolType Type { get; }

    // SubType field — interpretation depends on Type
    public byte SubType { get; }

    // Returns the byte length of the payload data (excluding the 4-byte header)
    public abstract ushort GetSerializationDataLength();

    // Reads payload fields from a BinaryReader
    public abstract void Deserialize(BinaryReader reader, ushort length);

    // Writes payload fields to a BinaryWriter
    public abstract void Serialize(BinaryWriter writer);
}
The DeviceProtocolType enum covers all top-level categories defined by the UEFI specification:
ValueByteDescription
Hardware0x01Physical hardware connection (PCI, memory map, controller)
ACPI0x02ACPI device namespace path
Message0x03Messaging devices (USB, SCSI, NVMe, …)
Media0x04Logical partition or file within a media device
BIOS0x05BIOS Boot Specification compatibility node
End0x7FEnd-of-path sentinel node

​
Hardware Device Path Protocols

Hardware device path protocols are provided by the Unified.Firmware.DevicePathProtocols.Hardware package. They describe the physical connection between the firmware and a device on the system board.

​
PciProtocol

Identifies a PCI function on a specific device. Corresponds to UEFI spec PCI Device Path, sub-type 1. 
[DefineDevicePathProtocol(DeviceProtocolType.Hardware, 1)]
public sealed class PciProtocol : DevicePathProtocolBase
{
    public byte Function { get; set; }
    public byte Device { get; set; }

    public PciProtocol(byte function, byte device);
}

// Describe PCI device 0x1F, function 0x02 (e.g. SATA controller)
var pci = new PciProtocol(function: 0x02, device: 0x1F);
Console.WriteLine(pci); // → Pci(0x1F, 0x2)

​
MemoryMappedProtocol

Describes a device that is mapped directly into the physical address space. Sub-type 3. 
[DefineDevicePathProtocol(DeviceProtocolType.Hardware, 3)]
public sealed class MemoryMappedProtocol : DevicePathProtocolBase
{
    public uint  MemoryType    { get; set; }
    public ulong StartAddress  { get; set; }
    public ulong EndAddress    { get; set; }
}

​
ControllerProtocol

Identifies a child controller number underneath a parent bus controller. Sub-type 5. 
[DefineDevicePathProtocol(DeviceProtocolType.Hardware, 5)]
public sealed class ControllerProtocol : DevicePathProtocolBase
{
    public uint ControllerNumber { get; set; }

    public ControllerProtocol(uint controllerNumber);
}

var ctrl = new ControllerProtocol(controllerNumber: 0);
Console.WriteLine(ctrl); // → Ctrl(0)

​
VendorProtocol (Hardware)

Carries an arbitrary vendor GUID and a variable-length byte payload. Sub-type 4. Used when no standard hardware node type applies. 
[DefineDevicePathProtocol(DeviceProtocolType.Hardware, 4)]
public sealed class VendorProtocol : DevicePathProtocolBase
{
    public Guid   VendorGuid        { get; set; }
    public byte[] VendorDefinedData { get; set; }
}

​
Media Device Path Protocols

Media device path protocols are provided by the Unified.Firmware.DevicePathProtocols.Media package. They describe logical partitions and files that live above the physical hardware layer.

​
HardDriveProtocol

Represents a single GPT or MBR partition. This is the most common first step in any disk-based boot entry’s device path. Sub-type 1. 
[DefineDevicePathProtocol(DeviceProtocolType.Media, 1)]
public class HardDriveProtocol : DevicePathProtocolBase
{
    public uint            PartitionNumber      { get; set; }
    public ulong           PartitionStart       { get; set; } // bytes
    public ulong           PartitionSize        { get; set; } // bytes
    public Guid            GptPartitionSignature { get; set; }
    public PartitionFormat PartitionFormat      { get; set; }
    public SignatureType   SignatureType        { get; set; }

    // Convenience constructor: resolves all fields from a partition GUID
    public HardDriveProtocol(Guid partitionIdentificator);
}
The Guid-based constructor calls into the platform backend to locate the partition and fill in all fields automatically, so you only need the GPT partition GUID (which you can read from FirmwareInterface.SystemPartition or any disk enumeration API). 
Guid espGuid = GetEspPartitionGuid(); // your helper
var hd = new HardDriveProtocol(espGuid);
Console.WriteLine(hd); // → <partition-guid>

​
FilePathProtocol

Holds a null-terminated Unicode path string relative to the root of the partition identified by the preceding node. Sub-type 4. 
[DefineDevicePathProtocol(DeviceProtocolType.Media, 4)]
public sealed class FilePathProtocol : DevicePathProtocolBase
{
    public string PathName { get; set; }

    public FilePathProtocol(string pathName);
}

var fp = new FilePathProtocol(@"EFI\ubuntu\grubx64.efi");
Console.WriteLine(fp); // → EFI\ubuntu\grubx64.efi
Use backslash (\) as the path separator, matching the convention in the UEFI specification. Forward slashes are not standard in EFI_DEVICE_PATH file path nodes.

​
CdRomProtocol

Describes a partition on an ISO 9660 / El Torito CD-ROM. Sub-type 2. 
[DefineDevicePathProtocol(DeviceProtocolType.Media, 2)]
public sealed class CdRomProtocol : DevicePathProtocolBase
{
    public uint  BootEntry     { get; set; } // 0 = initial/default entry
    public ulong PartitionStart { get; set; } // bytes
    public ulong PartitionSize  { get; set; } // bytes

    public CdRomProtocol(uint bootEntry, ulong partitionStart, ulong partitionSize);
}

​
VendorDefinedProtocol (Media)

Carries a vendor GUID and arbitrary byte payload for media nodes that do not fit a standard type. Sub-type 3. 
[DefineDevicePathProtocol(DeviceProtocolType.Media, 3)]
public class VendorDefinedProtocol : DevicePathProtocolBase
{
    public Guid   VendorGuid        { get; set; }
    public byte[] VendorDefinedData { get; set; }
}

​
DefineDevicePathProtocolAttribute

Every concrete protocol class is decorated with [DefineDevicePathProtocol(type, subType)]. This attribute registers the class with the library’s internal protocol deserializer. When FirmwareBootService reads a raw Boot#### variable, it walks each device path node and looks up the registered type for the (Type, SubType) pair. If a match is found, the typed class is instantiated and Deserialize is called. If no match is found, the node is wrapped in a raw fallback type, so unrecognised nodes do not break deserialization of the rest of the path.

​
Building a Typical Boot Entry Device Path

The most common pattern is a two-node path: HardDriveProtocol to select the ESP partition, followed by FilePathProtocol to select the EFI application within that partition. 
Guid espGuid = GetEspPartitionGuid(); // resolve from your system

var protocols = new DevicePathProtocolBase[]
{
    new HardDriveProtocol(espGuid),
    new FilePathProtocol(@"EFI\myapp\bootx64.efi")
};

var bootOption = new FirmwareBootOption(
    LoadOptionAttributes.ACTIVE | LoadOptionAttributes.CATEGORY_BOOT,
    "My Application",
    protocols,
    optionalData: Array.Empty<byte>());

BootOptionIndex idx = FirmwareBootService.CreateLoadOption(bootOption, addFirst: false);
Console.WriteLine($"Created Boot{idx:X4}");
The authoritative reference for every device path type, sub-type, and binary layout is UEFI Specification 2.10, Section 10 — Protocols: Device Path Protocol. When implementing a custom DevicePathProtocolBase subclass, consult Section 10 to ensure your Serialize / Deserialize byte order exactly matches the spec.

Build docs developers (and LLMs) love

Get started for freeTalk to us