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.

FirmwareInterface is the static gateway to every UEFI capability in Unified.Firmware. It handles platform backend selection, availability checking, EFI System Partition discovery, and boot-to-firmware-UI signalling — all from a single, dependency-free class that requires no instantiation.

​
Platform Backend Selection

Unified.Firmware ships two platform backends: Win32PlatformBackend for Windows and LinuxPlatfromBackend for Linux. FirmwareInterface.CurrentBackend picks the right one automatically by inspecting Environment.OSVersion.Platform the first time it is accessed, then caches the result for the lifetime of the process. 
public static IFirmwareBackend CurrentBackend
{
    get => field ??= Environment.OSVersion.Platform switch
    {
        PlatformID.Win32NT => new Win32PlatformBackend(),
        PlatformID.Unix    => new LinuxPlatfromBackend(),
        _                  => throw new PlatformNotSupportedException()
    };
}
You rarely need to call CurrentBackend directly — higher-level APIs such as FirmwareEnvironment.Global and FirmwareBootService consume it internally. Access it only when you need to pass the backend to a FirmwareEnvironment instance you are constructing yourself. 
// Pass the auto-selected backend to a custom vendor environment
var env = new FirmwareEnvironment(FirmwareInterface.CurrentBackend, myVendorGuid);

​
Availability Check

Before calling any UEFI API, verify that the current system was actually booted through UEFI and that the firmware exposes the required runtime services. Calling UEFI APIs on a BIOS/Legacy-boot system or inside a VM without firmware support will throw a PlatformNotSupportedException. 
public static bool Available { get; }
Available delegates to CurrentBackend.CheckFirmwareAvailablity(). It returns false when the platform is not UEFI or the process lacks the privileges needed to call firmware runtime services. 
if (!FirmwareInterface.Available)
{
    Console.WriteLine("UEFI is not available on this system.");
    return;
}

Console.WriteLine("UEFI is available. Proceeding with firmware operations.");
On Windows, reading or writing UEFI variables requires the process to hold the SE_SYSTEM_ENVIRONMENT_NAME privilege. You must run your application elevated (as Administrator) or explicitly acquire the privilege before UEFI APIs will succeed.

​
EFI System Partition

The EFI System Partition (ESP) is a FAT-formatted partition that stores boot loaders, firmware applications, and related files. FirmwareInterface.SystemPartition searches the mounted volumes for the one flagged as the ESP and returns a DirectoryInfo pointing to its root. 
public static DirectoryInfo SystemPartition { get; }
The property throws PlatformNotSupportedException if Available is false, ensuring callers never receive a stale or invalid path. 
if (!FirmwareInterface.Available)
    throw new PlatformNotSupportedException("UEFI not available.");

DirectoryInfo esp = FirmwareInterface.SystemPartition;
Console.WriteLine($"ESP root: {esp.FullName}");

// List EFI application directories
foreach (DirectoryInfo dir in esp.GetDirectories("EFI\\*", SearchOption.TopDirectoryOnly))
    Console.WriteLine(dir.Name);

​
Boot to Firmware UI

BootToUserInterface() sets the BOOT_TO_FW_UI flag in the OsIndications global UEFI variable. On the next reboot the firmware reads this flag and drops straight into its setup utility instead of starting the normal boot sequence. The call does not reboot the computer — it only sets the condition for the following restart. 
public static void BootToUserInterface()
The method first checks that OsIndicationsSupported contains the BOOT_TO_FW_UI bit. If the firmware does not advertise support for this feature, a PlatformNotSupportedException is thrown rather than writing an unsupported flag. 
if (!FirmwareInterface.Available)
{
    Console.Error.WriteLine("UEFI not available.");
    return;
}

// Schedule a boot into the firmware UI on the next reboot
FirmwareInterface.BootToUserInterface();
Console.WriteLine("Boot-to-firmware-UI flag set. Reboot to enter setup.");
Once OsIndications is written the flag persists in NVRAM. If the process crashes or the reboot is cancelled the flag remains set and the next reboot will still enter the firmware UI. The firmware clears the flag automatically after honouring it.

​
Custom Backend

IFirmwareBackend is the interface both built-in backends implement. You can provide your own implementation for unit testing, emulation, or exotic platforms by assigning it to CurrentBackend before any other call is made. For the full interface contract, see IFirmwareBackend. 
// Use a test double that reads/writes from a local file instead of NVRAM
public class MockFirmwareBackend : IFirmwareBackend
{
    public bool CheckFirmwareAvailablity() => true;

    public VolumePath FindEfiSystemPartition()
        => new VolumePath(/* ... */);

    public IntPtr ReadEnvironmentVariable(
        string varName, Guid envId,
        out VariableAttributes attributes,
        int bufferSize, out uint dataSize)
    {
        // Return test data from an in-memory dictionary
        // ...
    }

    public void WriteEnvironmentVariable(
        string varName, Guid envId,
        VariableAttributes attributes,
        IntPtr valueBuffer, int bufferSize)
    {
        // Capture written bytes for assertion
        // ...
    }
}

Firmware Environment

Read and write UEFI NVRAM variables in global and vendor namespaces

Boot Service

Enumerate, create, update, and delete UEFI boot entries

Build docs developers (and LLMs) love

Get started for freeTalk to us