UEFI File Protocol Directory Traversal Guide

The Unified Extensible Firmware Interface (UEFI) File Protocol, structurally defined as EFI_FILE_PROTOCOL, is the foundational interface that enables pre-boot applications, bootloaders, and firmware drivers to access and manage file systems. This article explains the architectural purpose of the protocol, detailing how it abstracts physical storage into a functional file hierarchy, manages file pointer operations, and facilitates sequential directory traversal and direct file manipulation without requiring an underlying operating system.

Core Architecture and File System Access

The EFI_FILE_PROTOCOL works in tandem with the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL. While the Simple File System protocol exposes a volume level interface on a specific storage device (such as a FAT32 partition on an NVMe or USB drive), its primary function is to call OpenVolume(). This method instantiates an initial EFI_FILE_PROTOCOL handle representing the root directory (\) of that volume.

Once obtained, each EFI_FILE_PROTOCOL instance acts as an abstraction for an individual opened file or directory, exposing function pointers for standard I/O mechanisms, metadata operations, and path resolution.

Directory Traversal Mechanisms

UEFI treats directories identically to files, distinguishing them by their metadata attributes (EFI_FILE_DIRECTORY). Navigating a directory tree via the UEFI File Protocol relies on two primary operations:

  1. Path-Based Navigation (Open): The Open() function allows an application to access a child directory or file relative to an already open directory handle. Developers can pass relative paths (e.g., EFI\\BOOT) or nested subpaths to descend into the file system tree. Specifying access modes—such as read-only (EFI_FILE_MODE_READ) or read-write (EFI_FILE_MODE_WRITE)—controls access permissions during traversal.
  2. Sequential Directory Enumeration (Read): To inspect the contents of an open directory, the Read() function is repurposed. Instead of reading raw file bytes, calling Read() on a directory handle populates an EFI_FILE_INFO structure containing the metadata of the next entry (such as file name, file size, physical size, attributes, and timestamps). Repeatedly calling Read() iterates through all files and subdirectories sequentially. When the end of the directory is reached, the protocol returns a buffer size of zero bytes. To restart traversal from the beginning, the file pointer can be reset using SetPosition() with an offset of 0.

File Manipulation Capabilities

Beyond directory discovery, the protocol provides low-level file manipulation routines necessary for system initialization, diagnostics, and firmware flashing:

  • Creation and Deletion: Files and folders are created by passing the EFI_FILE_MODE_CREATE flag alongside write permissions to the Open() function. Conversely, calling the Delete() function immediately removes the target file or directory from the underlying storage medium and frees the handle.
  • Data I/O Operations: For open files, Read() extracts raw byte buffers into memory, which is essential for loading OS kernels, configuration files, and secondary bootloaders. The Write() function commits data buffers back to the device, and Flush() forces any unwritten cached data directly to persistent storage.
  • Stream Positioning: The GetPosition() and SetPosition() functions manage the internal file offset. Setting the position to 0xFFFFFFFFFFFFFFFF moves the pointer to the end of the file, allowing straightforward data appending.
  • Metadata Manipulation: The protocol provides GetInfo() and SetInfo() routines. By interfacing with global unique identifiers (GUIDs) like EFI_FILE_INFO_ID, systems can inspect and modify attributes such as read-only flags, hidden flags, file size (truncation or expansion), and modification dates.

Practical Role in System Boot

The purpose of the UEFI File Protocol is to eliminate the need for bootloaders to contain custom, hard-coded storage drivers or raw block-level parsing logic. By providing a clean, standardized abstraction for reading directories and manipulating files, UEFI enables pre-boot environments to securely find boot configurations, load operating system binaries into system memory, and write diagnostic logs directly to mass storage before the primary OS kernel takes control.