| # Device firmware | |
| Device firmware are binary blobs containing code or configuration data executed | |
| by device hardware. | |
| Drivers, like other Fuchsia components, are packages whose package contents are | |
| mounted at `/pkg` in its incoming namespace (`fdf::Namespace` in C++, | |
| `fdf_component::Incoming` in Rust). Firmware blobs packaged with a driver are | |
| placed under `lib/firmware/` in the driver package and loaded directly by the | |
| driver from `/pkg/lib/firmware/<filename>` using the `fuchsia.io/File` protocol. | |
| Prebuilt device firmware packages are stored in CIPD (Chrome Infrastructure | |
| Package Deployment) and mirrored in Google Storage. | |
| ## Create a Firmware Package | |
| To create a firmware package, create a directory containing the following | |
| files: | |
| * One or more firmware files | |
| * A license file | |
| * [README.fuchsia](/docs/development/source_code/third-party-metadata.md) | |
| `README.fuchsia` must contain the required third-party metadata directives: | |
| * `Name` | |
| * `URL` | |
| * `Version` | |
| * `Revision` | |
| * `License` | |
| * `License File` | |
| * `Security Critical` | |
| * `Description` | |
| If this is the first time you uploaded to CIPD from the host system, | |
| authenticate with CIPD: | |
| ```posix-terminal | |
| fx cipd auth-login | |
| ``` | |
| Upload and tag the package in CIPD using the following command: | |
| ```posix-terminal | |
| fx cipd create -in <package-directory> -install-mode copy \ | |
| -name <package-name> \ | |
| -tag git_repository:<source-git-repository> \ | |
| -tag git_revision:<source-git-revision> | |
| ``` | |
| `<package-name>` uses one of the following naming conventions: | |
| * `fuchsia/firmware/<name>` for open-source redistributable firmware. | |
| * `fuchsia_internal/firmware/<name>` or `turquoise_internal/firmware/<name>` for | |
| internal or non-redistributable vendor firmware. | |
| `<name>` should be a string that identifies the firmware. It may contain | |
| any non-whitespace character. It is helpful to identify the driver that will | |
| use the firmware in the name. | |
| After this step, the package is uploaded to CIPD. Check the | |
| [CIPD browser](https://chrome-infra-packages.appspot.com/#/?path=fuchsia/firmware) | |
| for packages under `fuchsia/firmware`. | |
| ## Adding the Firmware Package to the Build | |
| ### 1. Add the CIPD package to Jiri manifests | |
| To fetch the prebuilt firmware package into the checkout (typically under | |
| `//prebuilt/...`), add a `<package>` entry to the appropriate Jiri manifest: | |
| * **In `fuchsia.git`**: Add driver firmware packages (both open-source and | |
| `internal="true"` packages) to `//manifests/prebuilts` (board and bootloader | |
| firmware packages are declared in `//manifests/firmware`). For example: | |
| ```xml | |
| <package name="fuchsia/firmware/<name>" | |
| version="git_revision:<source-git-revision>" | |
| path="prebuilt/<subsystem>/firmware/<name>"/> | |
| ``` | |
| After editing `//manifests/prebuilts` or `//manifests/firmware`, update the | |
| Jiri lockfile and test fetching the package locally: | |
| ```posix-terminal | |
| //manifests/update-lockfiles.sh | |
| jiri fetch-packages -local-manifest-project=fuchsia | |
| ``` | |
| * **In `integration.git` (internal vendor checkouts)**: Internal vendor firmware | |
| packages can also be declared in `//integration/internal/vendor/google/firmware`. | |
| ### 2. Include the firmware in the driver package | |
| Include the downloaded firmware blob in your driver package at | |
| `lib/firmware/<filename>` so that it appears at `/pkg/lib/firmware/<filename>` | |
| in the driver's incoming namespace. | |
| #### GN | |
| Define a `resource()` target and add it to the `deps` of your | |
| `fuchsia_driver_package()` target. If the firmware package requires internal | |
| access (`internal="true"`), guard the dependency with `if (internal_access)`: | |
| ```gn | |
| import("//build/cipd.gni") | |
| import("//build/components.gni") | |
| import("//build/drivers.gni") | |
| resource("my-driver-firmware") { | |
| sources = [ "//prebuilt/<subsystem>/firmware/<name>/fw.bin" ] | |
| outputs = [ "lib/firmware/{{source_file_part}}" ] | |
| } | |
| fuchsia_driver_package("my-driver-package") { | |
| driver_components = [ ":my-driver-component" ] | |
| deps = [] | |
| if (internal_access) { | |
| deps += [ ":my-driver-firmware" ] | |
| } | |
| } | |
| ``` | |
| #### Bazel | |
| Define a `fuchsia_package_resource()` target and include it in the `resources` | |
| list of your `fuchsia_package()` target: | |
| ```bazel | |
| load( | |
| "@rules_fuchsia//fuchsia:defs.bzl", | |
| "fuchsia_package", | |
| "fuchsia_package_resource", | |
| ) | |
| fuchsia_package_resource( | |
| name = "my_driver_firmware", | |
| src = "//:prebuilt/<subsystem>/firmware/<name>/fw.bin", | |
| dest = "lib/firmware/fw.bin", | |
| ) | |
| fuchsia_package( | |
| name = "my_driver_pkg", | |
| package_name = "my-driver", | |
| components = [":my_driver_component"], | |
| resources = [":my_driver_firmware"], | |
| ) | |
| ``` | |
| ## Loading Firmware in a Driver | |
| In a C++ driver, open `/pkg/lib/firmware/<filename>` from the driver's incoming | |
| namespace (`incoming()`) using `fuchsia.io/File` and call `GetBackingMemory` to | |
| obtain a read-only VMO containing the firmware: | |
| ```cpp | |
| #include <fidl/fuchsia.io/cpp/wire.h> | |
| #include <lib/driver/component/cpp/driver_base.h> | |
| #include <lib/zx/result.h> | |
| #include <lib/zx/vmo.h> | |
| zx::result<zx::vmo> LoadFirmware(fdf::Namespace& incoming, | |
| std::string_view filename, | |
| size_t* out_size) { | |
| std::string full_path = std::string("/pkg/lib/firmware/").append(filename); | |
| constexpr fuchsia_io::Flags kOpenFlags = | |
| fuchsia_io::Flags::kPermReadBytes | fuchsia_io::Flags::kProtocolFile; | |
| zx::result client = incoming.Open<fuchsia_io::File>(full_path.c_str(), kOpenFlags); | |
| if (client.is_error()) { | |
| return client.take_error(); | |
| } | |
| fidl::WireResult result = | |
| fidl::WireCall(*client)->GetBackingMemory(fuchsia_io::wire::VmoFlags::kRead); | |
| if (!result.ok()) { | |
| return zx::error(result.is_peer_closed() ? ZX_ERR_NOT_FOUND : result.status()); | |
| } | |
| if (result->is_error()) { | |
| return zx::error(result->error_value()); | |
| } | |
| zx::vmo& vmo = result->value()->vmo; | |
| if (zx_status_t status = vmo.get_prop_content_size(out_size); status != ZX_OK) { | |
| return zx::error(status); | |
| } | |
| return zx::ok(std::move(vmo)); | |
| } | |
| ``` |