EFI Resolver user guide documentation

1 files changed, 69 insertions, 0 deletions

diff --git a/docs/guide/efiresolver.md b/docs/guide/efiresolver.md
new file mode 100644
index 00000000..a11545eb
--- /dev/null
+++ b/docs/guide/efiresolver.md
@@ -0,0 +1,69 @@
+# EFI Resolver
+
+EFI Resolver is a Binary Ninja workflow that automates the resolution of type information for EFI (Extensible Firmware
+Interface) protocol usage in UEFI binaries. It supports Terse Executable (TE) and Portable Executable (PE) formatted
+EFI binaries such as PEI, DXE, and SMM modules.
+
+![EFI Resolver](../img/efi-resolver.png "EFI Resolver")
+
+## Key Features
+
+* **Automatic Type Propagation** – propagates EFI types from the module entry point to callee functions and global data
+  variables
+* **EFI Protocol Interface Detection** – identifies EFI DXE, SMM, and PPI protocol interfaces by analyzing calls to EFI
+  services methods (`InstallProtocolInterface`, `LocateProtocol`, etc.), queries known EFI types by GUID, and applies
+  types to interface pointers
+* **PEI Services Table Recovery** – identifies architecture-specific code patterns (described in the
+  [UEFI PI Specification](https://uefi.org/specs/PI/1.8/V1_PEI_Foundation.html#pei-services-table-retrieval)) for
+  resolving the address of the PEI services table
+* **User-defined / Proprietary EFI Protocol Support** – allows users to create custom EFI types and associate them with
+  an EFI GUID to be included during automated analysis
+
+## Re-running the Workflow
+
+EFI Resolver registers a plugin command that allows for re-running the EFI Resolver workflow after the binary view has
+been finalized. This can be valuable when manually applying new types or when creating new types for proprietary EFI
+protocol interfaces. To re-run EFI Resolver, click `Plugins -> Run EFI Resolver`.
+
+## User-defined EFI Protocol GUIDs and Types
+
+Binary Ninja bundles EFI platform type definitions for the majority of the types in the UEFI specification. However,
+many UEFI firmware vendors implement proprietary interfaces. EFI Resolver allows users to extend its capabilities by
+supplying custom GUIDs and associated type definitions for proprietary protocols. This can be achieved in the following
+steps:
+
+1. Create a JSON file named `efi-guids.json` in the `types` directory of your [user folder](index.md#user-folder)
+    * macOS: `~/Library/Application Support/Binary Ninja/types/efi-guids.json`
+    * Linux: `~/.binaryninja/types/efi-guids.json`
+    * Windows: `%APPDATA%\Binary Ninja\types`
+
+    ???+ Important "GUID Database"
+        An excellent source of proprietary EFI GUIDs is Binarly's
+        [GUID DB](https://github.com/binarly-io/guiddb/blob/main/guids.json). This file is in the expected format for
+        EFI Resolver's `efi-guids.json`, and can be copied directly to your user folder as a starting point.
+
+2. Define a GUID in the following format:
+
+    ```
+    {
+        "EFI_EXAMPLE_CUSTOM_PROTOCOL_GUID": [
+            19088743, 35243, 52719,
+            1, 35, 69, 103, 137, 171, 205, 239
+        ]
+    }
+    ```
+
+3. Create a type named `EFI_EXAMPLE_CUSTOM_PROTOCOL` using the types widget
+
+    ???+ Important "Unassociated EFI Types"
+        If there is not a type for a GUID defined in `efi-guids.json`, EFI Resolver will still use the GUID name to name
+        the protocol interface and GUID data variables.
+
+4. Re-run the workflow
+
+In this example, the workflow will apply the `EFI_EXAMPLE_CUSTOM_PROTOCOL` type to identified protocol interfaces that
+were queried in the binary via the `EFI_EXAMPLE_CUSTOM_PROTOCOL_GUID` EFI GUID.
+
+???+ Important "Platform Types"
+	To make a custom EFI protocol type accessible when loading future EFI binaries, it is recommended to add the type to
+	[platform types](types/platformtypes.md)