| # Fuchsia Firmware SDK | |
| The Firmware SDK provides definitions and reference code used to develop | |
| bootloader firmware for Fuchsia devices. The intent is for this SDK to provide | |
| common functionality needed by all firmware, such as the ZBI structure needed | |
| to boot the Zircon kernel, so it doesn't have to be re-implemented from scratch | |
| when bringing up a new board. | |
| ## Building the Firmware SDK | |
| The Firmware SDK build rules live in [`//src/firmware/`]. The SDK is | |
| not built in the normal flow, but can be built manually as follows: | |
| 1. Run `fx set minimal.x64` or similar. | |
| * Note: There is nothing special about this product or architecture. It was | |
| selected because it is a relatively small standard build capable of | |
| producing the necessary artifacts. | |
| 1. Run `fx args` and add `build_only_labels = [ "//sdk/firmware" ]`. | |
| * Note: This must be done manually because `fx set` does not currently | |
| support setting `build_only_labels`. | |
| 1. Run `fx build //sdk/firmware`. | |
| 1. Find the resulting SDK archive at `<build_dir>/sdk/archive/firmware.tar.gz` | |
| or its content at `<build_dir>/sdk/exported/firmware/`. | |
| ## Porting | |
| Firmware development is usually device-specific so it's not expected that this | |
| code will be usable directly; some porting work will be necessary. However, to | |
| ease the porting burden, everything in the Firmare SDK has a pure C | |
| implementation available, as firmware toolchains are commonly C-only. | |
| General porting steps are: | |
| 1. Build the Firmware IDK archive (see instructions above) | |
| 1. Unpack the archive in the firmware source tree | |
| 1. Add the required files and paths to the firmware build system | |
| 1. If necessary, modify SDK headers to work with the firmware source (e.g. | |
| some files use standard library headers which may not exist) | |
| ## Backwards Compatibility | |
| ### ABI | |
| The structures used to communicate between the OS and bootloader will maintain | |
| ABI backwards compatibility: | |
| * ZBI format | |
| * vbmeta format | |
| * A/B/R metadata | |
| This backwards compatibility is required so that we can continue to evolve the | |
| Fuchsia implementation as needed without also requiring simultaneous firmware | |
| updates. | |
| ### API | |
| The Firmware SDK does not enforce any API compatibility, meaning function | |
| signatures, constant/type names, etc may change at any time. However, any such | |
| changes should be relatively infrequent, and will only affect firmware when | |
| uprevving to a newer Firmware SDK version. | |
| ## Components | |
| ### ZBI format | |
| The ZBI format defines the structure of ZBI images. The firmware needs to know | |
| this in order to load the ZBI from disk into memory, append a number of ZBI | |
| items, and then pass control to the ZBI kernel. | |
| There's currently no way to provide these definitions alone in an SDK; instead | |
| they are included as part of the larger Zircon sysroot SDK (https://fxbug.dev/42144657). | |
| The ZBI definitions are currently located in the Firmware SDK under | |
| `arch/<arch>/sysroot/include/zircon/boot/`, primarily `image.h`. | |
| ### libzbi | |
| libzbi is a reference library, wrapping the ZBI format in a more convenient API. | |
| Firmware is not required to use libzbi, it just has to adhere to the underlying | |
| ZBI format. | |
| libzbi will be in the Firmware SDK under `pkg/zbi/`. | |
| ### libabr | |
| libabr provides A/B/R booting support. A/B/R booting is optional, for example a | |
| dev board may have no real need for A/B OTA updates, and it is not mandatory for | |
| booting Zircon. | |
| libabr will be in the Firmware SDK under `pkg/abr/`. | |
| ### libavb | |
| libavb provides verified boot support, i.e. using vbmeta images to authenticate | |
| Zircon images loaded from disk before attempting to use them. Like libabr, this | |
| library is not required and may be omitted for things like dev boards. | |
| This library originally comes from | |
| [Android](https://android.googlesource.com/platform/external/avb/). While we | |
| intend to upstream any necessary changes so they should be functionally | |
| identical, firmware should use the copy in the Firmware SDK in case there are | |
| local changes, and to make sure there aren't any version mismatch issues with | |
| the code used by the Fuchsia build to generate the vbmeta images. | |
| libavb will be in the Firmware SDK under `pkg/avb/`. | |
| ### Demo/Test avb_keys | |
| The "avb_key" subdirectory holds a set of board/product specific certificates | |
| and keys for for demonstrating the use of verified booting with libavb. |