# GKI boot image retrofitting tools for upgrading devices

Starting from Android T the GKI boot images consist of the generic `boot.img`
and `init_boot.img`. The `boot.img` contains the generic kernel, and
`init_boot.img` contains the generic ramdisk.
For upgrading devices whose `vendor_boot` partition is non-existent, this tool
(or spec) can be used to retrofit a set of Android T GKI `boot`, `init_boot` and
OEM `vendor_boot` partition images back into a single boot image containing the
GKI kernel plus generic and vendor ramdisks.

## Retrofitting the boot images

1. Download the certified GKI `boot.img`.
2. Go to the build artifacts page of `aosp_arm64` on `aosp-master` branch on
   https://ci.android.com/ and download `gki_retrofitting_tools.zip`.
3. Unzip and make sure the tool is in `${PATH}`.

   ```bash
   unzip gki_retrofitting_tools.zip
   export PATH="$(pwd)/gki_retrofitting_tools:${PATH}"
   # See tool usage:
   retrofit_gki --help
   ```

4. Create the retrofitted image. The `--version` argument lets you choose the
   boot image header version of the retrofitted boot image. Only version 2 is
   supported at the moment.

   ```bash
   retrofit_gki --boot boot.img --init_boot init_boot.img \
     --vendor_boot vendor_boot.img --version 2 -o boot.retrofitted.img
   ```

## Spec of the retrofitted images

* The SOURCE `boot.img` must be officially certified Android T (or later) GKI.
* The DEST retrofitted boot image must not set the security patch level in its
  header. This is because the SOURCE images might have different SPL value, thus
  making the boot header SPL of the retrofitted image ill-defined. The SPL value
  must be defined by the chained vbmeta image of the `boot` partition.
* The `boot signature` of the DEST image is the `boot signature` of the DEST
  `boot.img`.
* The DEST retrofitted boot image must pass the `vts_gki_compliance_test`
  testcase.

### Retrofit to boot image V2

* The `kernel` of the DEST image must be from the SOURCE `boot.img`.
* The `ramdisk` of the DEST image must be from the SOURCE `vendor_boot.img` and
  `init_boot.img`. The DEST `ramdisk` is the ramdisk concatenation of the vendor
  ramdisk and generic ramdisk.
* The `recovery dtbo / acpio` must be empty.
* The `dtb` of the DEST image must be from the SOURCE `vendor_boot.img`.
* The `boot_signature` section must be appended to the end of the boot image,
  and its size is zero-padded to 16KiB.

```
  +---------------------+
  | boot header         | 1 page
  +---------------------+
  | kernel              | n pages
  +---------------------+
  | * vendor ramdisk    |
  |  +generic ramdisk   | m pages
  +---------------------+
  | second stage        | o pages
  +---------------------+
  | recovery dtbo/acpio | 0 byte
  +---------------------+
  | dtb                 | q pages
  +---------------------+
  | * boot signature    | 16384 (16K) bytes
  +---------------------+
```