Fuchsia Firmware on NUC

This document contains NUC specific firmware workflows and features.

Bootstrap Fuchsia with GBL

This section gives instructions for bootstrapping NUC boards using the Generic Bootloader(GBL) EFI application, which will replace the recovery-installer workflow. The doc assumes that the NUC device has already enabled USB booting using these instructions.

Get the latest GBL prebuilts for x64 gbl_x86_64.efi from Android Build Artifact.

Configure Fuchsia to build with the GBL installer image.

fx set core.x64 \
   --args=gigaboot_gbl_efi_app='"<absolute path to gbl_x86_64.efi>"' \
   --with //src/firmware/gigaboot/cpp:gbl-installer

Build Fuchsia.
```
fx build
```
Create a bootable USB drive with the GBL installer.
```
fx mkinstaller --gbl <path to usb drive>
```

Boot NUC from the USB drive. Wait until the device appears as a Fastboot devices in ffx target list.

Sample output for ffx target list

NAME                      SERIAL          TYPE       STATE           ADDRS/IP                           RCS
fuchsia-4821-0b31-eaf8*   <unknown>       Unknown    Fastboot        [fe80::4a21:bff:fe31:eaf8%eno2]    N

Take the ip6 address from the above i.e. fe80::4a21:bff:fe31:eaf8%eno2

Run the following fastboot command to list all fastboot variables.

fx fastboot -s tcp:<ip6 address> getvar all

For example, using the example ip6 address from the previous step:

fx fastboot -s tcp:fe80::4a21:bff:fe31:eaf8%eno2 getvar all

In the output, look for variables that begin with "block-device" to find out the block devices detected on this device.

For example:

$ fx fastboot -s tcp:fe80::4a21:bff:fe31:eaf8%eno2 getvar all
(bootloader) max-download-size: 0x20000000
(bootloader) version-bootloader: 1.0
(bootloader) max-fetch-size: 0xffffffffffffffff
(bootloader) block-device:0:total-blocks: 0x1dcf32b0
(bootloader) block-device:0:block-size: 0x200
(bootloader) block-device:0:status: idle
(bootloader) block-device:1:total-blocks: 0x3bb4000
(bootloader) block-device:1:block-size: 0x200
(bootloader) block-device:1:status: idle
(bootloader) gbl-default-block: None
(bootloader) partition-size:gbl-installer.esp/1: 0x3f00000
(bootloader) partition-type:gbl-installer.esp/1: raw
(bootloader) hw-revision: x64
all:
Finished. Total time: 0.049s

The above example output shows that the device has two block devices, with numeric ID 0 and 1 respectively. Note that because we boot from USB, one of them is a USB disk which will not be our target disk for bootstrap. To tell which one is USB, look for variable partition-type:gbl-installer.esp, which gives the size and block device ID of the "gbl-installer.esp" partition on the USB disk. In the above example, it is

(bootloader) partition-size:gbl-installer.esp/1: 0x3f00000

which indicates that block device 1 is the USB disk. Therefore, this leaves only one possible disk candidate for bootstrap, which is block device 0.

Flash GPT to the target block device.
```
fx fastboot -s tcp:<ip6 address> flash gpt/<block device ID> gpt.bin
```
where <block device ID> is the block device ID determined from the previous step. The file gpt.bin comes from the same directory as this doc.
For example:
```
fx fastboot -s tcp:fe80::4a21:bff:fe31:eaf8%eno2 flash gpt/0 gpt.bin
```
After this step, the device should now have the needed partitions for flashing. It can be be manually verified by running getvar all.
Flash the device.
```
fx flash --no-bootloader-reboot
```
After flash completes and device successfully boots into Fuchsia. Unplug the USB disk.

gpt.bin

The GPT image gpt.bin in this directory is generated by script gen_nuc_gpt.py and contains the following partitions.

+-----------------------------------------------------------------------+
|                               gpt.bin                                 |
+-----------------------------------------------------------------------+
| Sector size (logical): 512 bytes                                      |
|                                                                       |
| Number  Start (sector)    End (sector)  Size       Code  Name         |
|    1              34           32801   16.0 MiB    F105  bootloader   |
|    2           32802          294945   128.0 MiB   F107  zircon_a     |
|    3          294946          557089   128.0 MiB   F107  zircon_b     |
|    4          557090          958497   196.0 MiB   F107  zircon_r     |
|    5          958498          958625   64.0 KiB    F106  vbmeta_a     |
|    6          958626          958753   64.0 KiB    F106  vbmeta_b     |
|    7          958754          958881   64.0 KiB    F106  vbmeta_r     |
|    8          958882          958889   4.0 KiB     F102  durable_boot |
|    9          958890       118399401   56.0 GiB    F113  fvm          |
+-----------------------------------------------------------------------+