1# Device Firmware
2
3Device firmware are binary blobs containing code that are executed by device
4hardware. The binary blob is available in the driver's namespace for loading.
5
6Device firmware are stored in CIPD (Chrome Infrastructure Package Deployment)
7and mirrored in Google Storage.
8
9## Before You Start
10
11Ensure that CIPD is available. cipd must be either in PATH or
12`zircon/../buildtools/cipd`.
13
14The buildtools repository is available
15[here](https://fuchsia.googlesource.com/buildtools/).
16
17## Create a Firmware Package
18
19To create a firmware package, create a directory containing the following
20files:
21
22* One or more firmware files
23* A license file
24* [README.fuchsia](https://fuchsia.googlesource.com/docs/+/master/development/source_code/README.fuchsia.md)
25
26README.fuchsia must contain at least the following directives:
27
28* `Name`
29* `Version`
30* `Upstream Git`
31* `License`
32* `License File`
33
34If this is the first time you uploaded to CIPD from the host system,
35authenticate with CIPD:
36
37```
38cipd auth-login
39```
40
41Upload and tag the package in CIPD using the following command:
42
43```
44cipd create -in <package-directory> -install-mode copy \
45    -name <package-name> \
46    -tag git_repository:<source-git-repositry> \
47    -tag git_revision:<source-git-revision>
48```
49
50`package-name` has the format `fuchsia/firmware/<name>`.
51
52`<name>` should be a string that identifies the firmware. It may contain
53any non-whitespace character. It is helpful to identify the driver that will
54use the firmware in the name.
55
56After this step, the package is uploaded to CIPD. Check the
57[CIPD browser here](https://chrome-infra-packages.appspot.com/#/?path=fuchsia/firmware)
58for packages under `fuchsia/firmware`.
59
60## Adding the Firmware Package to the Build
61
62Add the following entry in `prebuilt/zircon.ensure`:
63
64```
65@Subdir firmware/<name>
66<package-name> git_revision:<source-git-revision>
67```
68
69Where `<name>`, `<package-name>` and `<source-git-revision>` matches the
70values passed to `cipd create` above. The package will be downloaded to
71the path specified by `@Subdir` under `prebuilt`, i.e.
72`prebuilt/firmware/<name>`.
73
74Next, update `prebuilt/zircon.versions` with the following command:
75
76```
77scripts/download-prebuilt --resolve
78```
79
80Upload this change to Gerrit and send it to the CQ.  The firmware package will
81be downloaded by `scripts/download-prebuilt` along with the toolchain and QEMU.
82
83## Using the Firmware Package in the Driver
84
85Add the following line to the driver's `rules.mk`:
86
87```
88MODULE_FIRMWARE := <name>/<path-to-binary-blob>
89```
90
91This will install the firmware to bootfs under
92`/boot/lib/firmware/$(basename $(MODULE_FIRMWARE))`.
93
94The `load_firmware()` API, defined in [`driver.h`](../../system/ulib/ddk/include/ddk/driver.h)
95loads the firmware pointed to by the path in a VMO.
96