Add `gki_retrofitting_tools.zip` to GSI/GKI DIST_DIR am: 680c62a5d2
Original change: https://android-review.googlesource.com/c/platform/system/tools/mkbootimg/+/1956320
Change-Id: I52b692e0f343bcd09c137e43525e6f48dc176cf5
diff --git a/gki/Android.bp b/gki/Android.bp
index 9ee7e39..50e995f 100644
--- a/gki/Android.bp
+++ b/gki/Android.bp
@@ -46,3 +46,31 @@
"general-tests",
],
}
+
+genrule {
+ name: "gki_retrofitting_tools",
+ tools: [
+ "soong_zip",
+ "retrofit_gki",
+ "mkbootimg",
+ "unpack_bootimg",
+ ],
+ srcs: [
+ "README.md",
+ ],
+ cmd: "STAGE_DIR=$(genDir)/gki_retrofitting_tools && " +
+ "rm -rf $${STAGE_DIR} && mkdir -p $${STAGE_DIR} && " +
+ "cp $(location retrofit_gki) $${STAGE_DIR} && " +
+ "cp $(location mkbootimg) $${STAGE_DIR} && " +
+ "cp $(location unpack_bootimg) $${STAGE_DIR} && " +
+ "cp $(in) $${STAGE_DIR} && " +
+ "$(location soong_zip) -o $(out) -C $(genDir) -D $${STAGE_DIR}",
+ out: [
+ "gki_retrofitting_tools.zip",
+ ],
+ dist: {
+ targets: [
+ "gki_retrofitting_tools",
+ ],
+ },
+}
diff --git a/gki/Android.mk b/gki/Android.mk
new file mode 100644
index 0000000..c0af5ef
--- /dev/null
+++ b/gki/Android.mk
@@ -0,0 +1,36 @@
+#
+# Copyright (C) 2022 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+_gsi_gki_product_names := \
+ aosp_arm \
+ aosp_arm64 \
+ aosp_x86 \
+ aosp_x86_64 \
+ gsi_arm \
+ gsi_arm64 \
+ gsi_x86 \
+ gsi_x86_64 \
+ gki_arm64 \
+ gki_x86_64 \
+
+# Add gki_retrofitting_tools to `m dist` of GSI/GKI for easy pickup.
+ifneq (,$(filter $(_gsi_gki_product_names),$(TARGET_PRODUCT)))
+
+droidcore-unbundled: gki_retrofitting_tools
+
+endif
+
+_gsi_gki_product_names :=
diff --git a/gki/README.md b/gki/README.md
new file mode 100644
index 0000000..d080f53
--- /dev/null
+++ b/gki/README.md
@@ -0,0 +1,115 @@
+# Android T GKI boot image retrofitting tools
+
+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 `init_boot` partition is non-existent, this tool
+(or spec) can be used to retrofit a set of Android T GKI `boot` and `init_boot`
+partition images back into a single *retrofitted GKI boot image*.
+
+## Retrofitting the boot images
+
+1. Download the certified GKI `boot.img` and `init_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 image. You would have to choose
+ this value according to the bootloader capabilities.
+
+ ```bash
+ # Retrofit to boot v4:
+ retrofit_gki --boot boot.img --init_boot init_boot.img \
+ --version 4 -o boot.retrofitted.img
+ # Retrofit to boot v2:
+ 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` and `init_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 `boot.img` and `init_boot.img` 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 concatenation of the
+ `boot signature` from the DEST `boot.img` and `init_boot.img`.
+* The DEST retrofitted boot image must pass the `vts_gki_compliance_test`
+ testcase.
+
+### Retrofit to boot image V4
+
+* The `kernel` of the DEST image must be from the SOURCE `boot.img`.
+* The `ramdisk` of the DEST image must be from the SOURCE `init_boot.img`.
+
+```
+ +---------------------+
+ | boot header | 4096 bytes
+ +---------------------+
+ | kernel | m pages
+ +---------------------+
+ | ramdisk | n pages
+ +---------------------+
+ | boot signature | g pages
+ +---------------------+
+```
+
+### Retrofit to boot image V3
+
+* The `kernel` of the DEST image must be from the SOURCE `boot.img`.
+* The `ramdisk` of the DEST image must be from the SOURCE `init_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 | 4096 bytes
+ +---------------------+
+ | kernel | m pages
+ +---------------------+
+ | ramdisk | n pages
+ +---------------------+
+ | * boot signature | 16384 (16K) bytes
+ +---------------------+
+```
+
+### 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
+ +---------------------+
+```