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.
The Firmware SDK build rules live in
//sdk/BUILD.gn. The SDK is not built in the normal flow, but can be built manually as follows:
build_sdk_archives=true to your gn args, typically by one of:
fx set ... --args=build_sdk_archives=true, or
fx args and add
build_sdk_archives = true to the args file
fx build sdk:firmware
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:
The structures used to communicate between the OS and bootloader will maintain ABI backwards compatibility:
This backwards compatibility is required so that we can continue to evolve the Fuchsia implementation as needed without also requiring simultaneous firmware updates.
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.
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 (fxbug.dev/65907).
The ZBI definitions are currently located in the Firmware SDK under
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
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
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. 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
The “avb_key” subdirectory holds a set of board/product specific certificates and keys for for demonstrating the use of verified booting with libavb.