NXP Semiconductors ASUG User manual

1 Overview
This document describes how to build Android Pie 9.0 platform for the i.MX 8
series devices. It provides instructions for:
• Configuring a Linux® OS build machine.
• Downloading, patching, and building the software components that create
the Android™ system image.
• Building from sources and using pre-built images.
• Copying the images to boot media.
• Hardware/software configurations for programming the boot media and
running the images.
For more information about building the Android platform, see
source.android.com/source/building.html.
2 Preparation
2.1 Setting up your computer
To build the Android source files, use a computer running the Linux OS. The Ubuntu 16.04 64-bit version and openjdk-8-jdk is
the most tested environment for the Android Pie 9.0 build.
After installing the computer running Linux OS, check whether all the necessary packages are installed for an Android build. See
"Setting up your machine" on the Android website source.android.com/source/initializing.html.
In addition to the packages requested on the Android website, the following packages are also needed:
$ sudo apt-get install uuid uuid-dev
$ sudo apt-get install zlib1g-dev liblz-dev
$ sudo apt-get install liblzo2-2 liblzo2-dev
$ sudo apt-get install lzop
$ sudo apt-get install git-core curl
$ sudo apt-get install u-boot-tools
$ sudo apt-get install mtd-utils
$ sudo apt-get install android-tools-fsutils
$ sudo apt-get install openjdk-8-jdk
$ sudo apt-get install device-tree-compiler
$ sudo apt-get install gdisk
$ sudo apt-get install m4
$ sudo apt-get install libz-dev
Contents
1 Overview................................................1
2 Preparation............................................ 1
3 Building the Android platform for i.MX... 2
4 Running the Android Platform with a
Prebuilt Image..................................... 7
5 Programming Images............................ 9
6 Booting.................................................13
7 Over-The-Air (OTA) Update.................17
8 Customized Configuration................... 21
9 Revision History...................................30
ASUG
Android™ User's Guide
Rev. P9.0.0_2.3.2 — 6 March 2020 User's Guide

If you have trouble installing the JDK in Ubuntu, see How to install misc JDK in Ubuntu for Android build.
Configure git before use. Set the name and email as follows:
• git config --global user.name "First Last"
• git config --global user.email "[email protected]"
NOTE
2.2 Unpacking the Android release package
After you have set up a computer running Linux OS, unpack the Android release package by using the following commands:
$ cd ~ (or any other directory you like)
$ tar xzvf imx-p9.0.0_2.3.2.tar.gz
3 Building the Android platform for i.MX
3.1 Getting i.MX Android release source code
The i.MX Android release source code consists of three parts:
• NXP i.MX public source code, which is maintained in the CodeAurora Forum repository.
• AOSP Android public source code, which is maintained in android.googlesource.com.
• NXP i.MX Android proprietary source code package, which is maintained in www.NXP.com.
Assume you had i.MX Android proprietary source code package imx-p9.0.0_2.3.2.tar.gz under ~/. directory. To generate the i.MX
Android release source code build environment, execute the following commands:
$ mkdir ~/bin
$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo
$ export PATH=${PATH}:~/bin
$ source ~/imx-p9.0.0_2.3.2/imx_android_setup.sh
# By default, the imx_android_setup.sh script will create the source code build environemnt in the
folder ~/android_build
# ${MY_ANDROID} will be refered as the i.MX Android source code root directory in all i.MX Andorid
release documentation.
$ export MY_ANDROID=~/android_build
3.2 Building Android images
Building the Android image is performed when the source code has been downloaded (Section 3.1 "Getting i.MX Android release
source code").
Commands lunch <buildName-buildType> to set up the build configuration and make to start the build process are executed.
The build configuration command lunch can be issued with an argument <Build name>-<Build type> string, such as lunch
evk_8mm-userdebug, or can be issued without the argument, which will present a menu of options to select.
The Build Name is the Android device name found in the directory ${MY_ANDROID}/device/fsl/. The following table lists the i.MX
build names.
Table 1. Build names
Build name Description
evk_8mn i.MX 8M Nano EVK Board
Table continues on the next page...
NXP Semiconductors
Building the Android platform for i.MX
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 2 / 31

Table 1. Build names (continued)
Build name Description
mek_8q i.MX 8QuadXPlus MEK Board
The build type is used to specify what debug options are provided in the final image. The following table lists the build types.
Table 2. Build types
Build type Description
user Production-ready image, no debug
userdebug Provides image with root access and debug, similar to "user"
eng Development image with debug tools
Android build steps are as follows:
1. Change to the top level build directory.
$ cd ${MY_ANDROID}
2. Set up the environment for building. This only configures the current terminal.
$ source build/envsetup.sh
3. Execute the Android lunch command. In this example, the setup is for the production image of i.MX 8M Mini EVK Board/
Platform device with userdebug type.
$ lunch evk_8mn-userdebug
4. Execute the make command to generate the image.
$ make 2>&1 | tee build-log.txt
When the make command is complete, the build-log.txt file contains the execution output. Check for any errors.
For BUILD_ID & BUILD_NUMBER changing, update build_id.mk in your ${MY_ANDROID} directory. For details, see the
Android™ Frequently Asked Questions.
The following outputs are generated by default in ${MY_ANDROID}/out/target/product/evk_8mn:
• root/: root file system (including init, init.rc). Mounted at /.
• system/: Android system binary/libraries. Mounted at /system.
• recovery/: root file system when booting in "recovery" mode. Not used directly.
• dtbo-imx8mn.img: Board's device tree binary. It is used to support MIPI-to-HDMI output.
• dtbo-imx8mn-rpmsg.img: Board's device tree binary. It is used to support MIPI-to-HDMI output and MCU image.
• dtbo-imx8mn-mipi-panel: Board's device tree binary. It is used to support MIPI Panel output.
• vbmeta-imx8mn.img: Android Verify boot metadata image for dtbo-imx8mn.img.
• vbmeta-imx8mn-rpmsg.img: Android Verify boot metadata image for dtbo-imx8mn-rpmsg.img.
• vbmeta-imx8mn-mipi-panel.img: Android Verify boot metadata image for dtbo-imx8mn-mipi-panel.img.
• ramdisk.img: Ramdisk image generated from "root/". Not directly used.
• system.img: EXT4 image generated from "system/". Can be programmed to "SYSTEM" partition on SD/eMMC card with
"dd".
NXP Semiconductors
Building the Android platform for i.MX
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 3 / 31

• partition-table.img: GPT partition table image. Used for 16 GB SD card and eMMC card.
• partition-table-7GB.img: GPT partition table image. Used for 8 GB SD card.
• partition-table-28GB.img: GPT partition table image. Used for 32 GB SD card.
• u-boot-imx8mn.imx: U-Boot image without Trusty OS integrated into it for i.MX 8M Nano EVK DDR4.
• u-boot-imx8mn-trusty.imx: U-Boot image with Trusty OS integrated into it for i.MX 8M Nano EVK DDR4.
• u-boot-imx8mn-evk-uuu.imx: U-Boot image used by UUU for i.MX 8M Nano EVK DDR4. It is not flashed to MMC.
• u-boot-imx8mn-lpddr4.imx: U-Boot image without Trusty OS integrated into it for i.MX 8M Nano EVK LPDDR4.
• u-boot-imx8mn-lpddr4-evk-uuu.imx: U-Boot image used by UUU for i.MX 8M Nano EVK LPDDR4. It is not flashed to
MMC.
• imx8mn_mcu_demo.img: MCU FreeRTOS image on MCU side.
• vendor.img: vendor image, which holds platform binaries. Mounted at /vendor.
• boot.img: a composite image that includes the kernel Image, ramdisk, and boot parameters.
• rpmb_key_test.bin: prebuilt test RPMB key. Can be used to set the RPMB key as fixed 32 bytes 0x00.
• testkey_public_rsa4096.bin: prebuilt AVB public key. It is extracted from the default AVB private key.
• To build the U-Boot image separately, see Building U-Boot images.
• To build the kernel uImage separately, see Building a kernel image.
• To build boot.img, see Building boot.img.
• To build dtbo.img, see Building dtbo.img.
NOTE
3.2.1 Configuration examples of building i.MX devices
The following table shows examples of using the lunch command to set up different i.MX devices. After the desired i.MX device
is set up, the make command is used to start the build.
Table 3. i.MX device lunch examples
Build name Description
i.MX 8M Nano EVK Board $ lunch evk_8mn-userdebug
i.MX 8QuadXPlus MEK board $ lunch mek_8q-userdebug
3.2.2 Build mode selection
There are three types of build mode to select: eng, user, and userdebug.
To pass CTS, use user build mode.
NOTE
The userdebug build behaves the same as the user build, with the ability to enable additional debugging that normally violates
the security model of the platform. This makes the userdebug build with greater diagnosis capabilities for user test.
The eng build prioritizes engineering productivity for engineers who work on the platform. The eng build turns off various
optimizations used to provide a good user experience. Otherwise, the eng build behaves similar to the user and userdebug builds,
so that device developers can see how the code behaves in those environments.
In a module definition, the module can specify tags with LOCAL_MODULE_TAGS, which can be one or more values of optional
(default), debug, eng.
NXP Semiconductors
Building the Android platform for i.MX
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 4 / 31

If a module does not specify a tag (by LOCAL_MODULE_TAGS), its tag defaults to optional. An optional module is installed only
if it is required by product configuration with PRODUCT_PACKAGES.
The main differences among the three modes are listed as follows:
• eng: development configuration with additional debugging tools
— Installs modules tagged with: eng and/or debug.
— Installs modules according to the product definition files, in addition to tagged modules.
— ro.secure=0
— ro.debuggable=1
— ro.kernel.android.checkjni=1
— adb is enabled by default.
• user: limited access; suited for production
— Installs modules tagged with user.
— Installs modules according to the product definition files, in addition to tagged modules.
— ro.secure=1
— ro.debuggable=0
— adb is disabled by default.
• userdebug: like user but with root access and debuggability; preferred for debugging
— Installs modules tagged with debug.
— ro.debuggable=1
— adb is enabled by default.
There are two methods for the build of Android image.
Method 1: Set the environment first and then issue the make command:
$ cd ${MY_ANDROID}
$ source build/envsetup.sh #set env
$ make -j4 PRODUCT-XXX userdebug 2>&1 | tee build-log.txt #XXX depends on different boards. See the
table below.
Table 4. Android system image production build method 1
i.MX development tool Description Image build command
Evaluation Kit i.MX 8M Nano EVK $ make -j4 PRODUCT-evk_8mn-userdebug
Evaluation Kit i.MX 8QuadXPlus MEK $ make -j4 PRODUCT-mek_8q-userdebug
Method 2: Set the environment and then use lunch command to configure argument. See table below. An example for the i.MX
8M Nano EVK board is as follows:
$ cd ${MY_ANDROID}
$ source build/envsetup.sh
$ lunch evk_8mn-userdebug
$ make -j4
NXP Semiconductors
Building the Android platform for i.MX
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 5 / 31

Table 5. Android system image production build method 2
i.MX development tool Description Lunch configuration
Evaluation Kit i.MX 8M Nano EVK evk_8mn-userdebug
Evaluation Kit i.MX 8QuadXPlus MEK mek_8q-userdebug
For more Android platform building information, see source.android.com/source/building.html.
3.2.3 Building with GMS package
Get the Google Mobile Services (GMS) package from Google. Put the GMS package into ${MY_ANDROID}/vendor/partner_gms
folder. Make sure that the product.mk* file includes the following line:
$(call inherit-product-if-exists, vendor/partner_gms/products/gms.mk)
Then build the images. The GMS package is installed into the target images.
product.mk indicates the build target make file. For example, for i.MX 8M Nano EVK Board, the product.mk
is named device/fsl/imx8m/evk_8mn/evk_8mn.mk.
NOTE
3.3 Building U-Boot images
Use the following command to generate u-boot.imx under the Android environment:
# U-Boot image for i.MX 8M Nano board
$ cd ${MY_ANDROID}
$ source build/envsetup.sh
$ lunch evk_8mn-userdebug
$ make bootloader -j4
For other platforms, use lunch <buildName-buildType> to set up the build configuration. For detailed build configuration, see
Section 3.2 "Building Android images".
3.4 Building a kernel image
Kernel image is automatically built when building the Android root file system.
The following are the default Android build commands to build the kernel image:
$ cd ${MY_ANDROID}/vendor/nxp-opensource/kernel-imx
$ echo $ARCH && echo $CROSS_COMPILE
Make sure that you have those two environment variables set. If the two variables are not set, set them as follows:
$ export ARCH=arm64
$ export CROSS_COMPILE=${MY_ANDROID}/prebuilts/gcc/linux-x86/aarch64/aarch64-linux-android-4.9/bin/
aarch64-linux-android-
# Generate ".config" according to default config file under arch/arm64/configs/android_defconfig.
# to build the kernel Image for i.MX 8M Nano EVK and i.MX 8QuadXPlus MEK.
$ make android_defconfig
$ make KCFLAGS=-mno-android
The kernel images are found in ${MY_ANDROID}/out/target/product/evk_8mm/obj/KERNEL_OBJ/arch/arm64/boot/Image.
NXP Semiconductors
Building the Android platform for i.MX
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 6 / 31

3.5 Building boot.img
boot.img and boota are default booting commands.
As outlined in Running the Android Platform with a Prebuilt Image, we use boot.img and boota as default commands to boot
instead of the uramdisk and Image we used before.
Use this command to generate boot.img under Android environment:
# Boot image for i.MX 8M Nano EVK board
$ source build/envsetup.sh
$ lunch evk_8mn-userdebug
$ make bootimage -j4
For other platforms, use lunch <buildName-buildType> to set up the build configuration. For detailed build configuration, see
Section 3.2 "Building Android images".
3.6 Building dtbo.img
Dtbo image holds the device tree binary of the board.
To generate dtbo.img under the Android environment, use the following commands:
# dtbo image for i.MX 8M Nano board
$ source build/envsetup.sh
$ lunch evk_8mn-userdebug
$ make dtboimage -j4
For other platforms, use lunch <buildName-buildType> to set up the build configuration. For detailed build configuration, see
Section 3.2 "Building Android images".
4 Running the Android Platform with a Prebuilt Image
Table 6. Image packages
Image package Description
android_p9.0.0_2.3.2_image_8mnevk.tar.gz Prebuilt image for i.MX 8M Nano EVK board, which includes NXP extended
features.
android_p9.0.0_2.3.2_image_8qmek.tar.gz Prebuilt image for i.MX 8QuadXPlus MEK board, which includes NXP
extended features.
The following tables list the detailed contents of android_p9.0.0_2.3.2_image_8mnevk.tar.gz image package.
The table below shows the prebuilt images to support the system on i.MX 8M Nano EVK boards.
Table 7. Images for i.MX 8M Nano EVK
i.MX 8M Nano EVK image Description
u-boot-imx8mn.imx Bootloader without Trusty OS integrated into it for i.MX 8M Nano EVK DDR4 board.
u-boot-imx8mn-trusty.imx Bootloader with Trusty OS integrated into it for i.MX 8M Nano EVK DDR4 board.
u-boot-imx8mn-evk-uuu.imx Bootloader used by UUU for i.MX 8M Nano EVK DDR4 board. It is not flashed to
MMC.
u-boot-imx8mn-lpddr4.imx Bootloader without Trusty OS integrated into it for i.MX 8M Nano EVK LPDDR4
board.
Table continues on the next page...
NXP Semiconductors
Running the Android Platform with a Prebuilt Image
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 7 / 31

Table 7. Images for i.MX 8M Nano EVK (continued)
u-boot-imx8mn-lpddr4-evk-uuu.imx Bootloader used by UUU for i.MX 8M Nano EVK LPDDR4 board. It is not flashed to
MMC.
boot.img Boot image for i.MX 8M Nano EVK board.
system.img System Boot image for i.MX 8M Nano EVK board.
vendor.img Vendor image for i.MX 8M Nano EVK board.
partition-table.img GPT table image for 16 GB SD card and eMMC.
partition-table-7GB.img GPT table image for 8 GB SD card.
partition-table-28GB.img GPT table image for 32 GB SD card.
imx8mn_mcu_demo.img MCU image for i.MX 8M Nano EVK board.
dtbo-imx8mn.img Device Tree image for i.MX 8M Nano EVK board to support MIPI-to-HDMI output.
dtbo-imx8mn-rpmsg.img Device Tree image for i.MX 8M Nano EVK board to support MIPI-to-HDMI output
and MCU image.
dtbo-imx8mn-mipi-panel.img Device Tree image for i.MX 8M Nano EVK board to support MIPI panel output.
vbmeta-imx8mn.img Android Verify Boot metadata image for i.MX 8M Nano EVK board to support MIPI-
to-HDMI output.
vbmeta-imx8mn-rpmsg.img Android Verify Boot metadata image for i.MX 8M Nano board to support MIPI-to-
HDMI output and mcu image.
vbmeta-imx8mn-mipi-panel.img Android Verify Boot metadata image for i.MX 8M Nano EVK board to support MIPI
panel output.
rpmb_key_test.bin Prebuilt test RPMB key, which can be used to set the RPMB key as fixed 32 bytes
0x00.
testkey_public_rsa4096.bin Prebuilt AVB public key, which is extracted from the default AVB private key.
The following tables list the detailed contents of android_p9.0.0_2.3.2_image_8qmek.tar.gz package.
The table below shows the prebuilt images to support the system on i.MX 8QuadXPlus MEK boards.
Table 8. Images for i.MX 8QuadXPlus MEK
i.MX 8QuadXPlus MEK images Description
spl-imx8qxp.bin SPL for i.MX 8QuadXPlus MEK board with b0 chip.
u-boot-imx8qxp-mek-uuu.imx Bootloader used by UUU for i.MX 8QuadXPlus MEK board with b0 chip. It is not
flashed to MMC.
bootloader-imx8qxp.img The next loader image after SPL for i.MX 8QuadXPlus MEK board with b0 chip.
spl-imx8qxp-c0.bin SPL for i.MX 8QuadXPlus MEK board with c0 chip.
u-boot-imx8qxp-mek-c0-uuu.imx Bootloader used by UUU for i.MX 8QuadXPlus MEK board with c0 chip. It is not
flashed to MMC.
bootloader-imx8qxp-c0.img The next loader image after SPL for i.MX 8QuadXPlus MEK board with c0 chip.
boot.img Boot image for to support LVDS-to-HDMI display.
partition-table.img GPT table image for 16 GB boot storage.
Table continues on the next page...
NXP Semiconductors
Running the Android Platform with a Prebuilt Image
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 8 / 31

Table 8. Images for i.MX 8QuadXPlus MEK (continued)
partition-table-7GB.img GPT table image for 8 GB boot storage.
partition-table-28GB.img GPT table image for 32 GB boot storage.
vbmeta-imx8qxp.img Android Verify Boot metadata Image for i.MX 8QuadXPlus MEK board to support
LVDS-to-HDMI display.
system.img System image.
vendor.img Vendor image.
dtbo-imx8qxp.img Device Tree Image for i.MX 8QuadXPlus MEK.
rpmb_key_test.bin Prebuilt test RPMB key. It can be used to set the RPMB key as fixed 32 bytes 0x00.
testkey_public_rsa4096.bin Prebuilt AVB public key. It is extracted from the default AVB private key.
boot.img is an Android image that stores Image and ramdisk together. It can also store other information such as
the kernel boot command line and machine name. This information can be configured in android.mk. It can avoid
touching boot loader code to change any default boot arguments.
NOTE
5 Programming Images
The images from the prebuilt release package or created from source code contain the U-Boot boot loader, system image, GPT
image, vendor image, and vbmeta image. At a minium, the storage devices on the development system (MMC/SD) must be
programmed with the U-Boot boot loader. The i.MX 8 series boot process determines what storage device to access based on
the switch settings. When the boot loader is loaded and begins execution, the U-Boot environment space is then read to determine
how to proceed with the boot process. For U-Boot environment settings, see Section Booting.
The following download methods can be used to write the Android System Image:
• UUU to download all images to the eMMC/SD card.
• fsl-sdcard-partition.sh to download all images to the SD card.
• fastboot_imx_flashall script to download all images to the eMMC/SD storage.
5.1 System on eMMC/SD
The images needed to create an Android system on eMMC/SD can either be obtained from the release package or be built
from source.
The images needed to create an Android system on eMMC/SD are listed below:
• U-Boot image: u-boot.imx
• GPT table image: partition-table.img
• Android dtbo image: dtbo.img
• Android boot image: boot.img
• Android system image: system.img
• Android verify boot metadata image: vbmeta.img
• Android vendor image: vendor.img
5.1.1 Storage partitions
The layout of the eMMC card for Android system is shown below:
NXP Semiconductors
Programming Images
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 9 / 31

• [Partition type/index] which is defined in the GPT.
• [Start Offset] shows where partition is started, unit in MB.
The system partition is used to put the built-out Android system image. The userdata parition is used to put the unpacked codes/
data of the applications, system configuration database, etc. In normal boot mode, the root file system is mounted from the system
partition. In recovery mode, the root file system is mounted from the boot partition.
Table 9. Storage partitions
Partition type/index Name Start offset Size File system Content
N/A bootloader 0 KB (i.MX 8M
Nano EVK
eMMC), 32 KB
(i.MX 8M Nano
EVK, i.MX
8QuadXPlus
MEK SD card)
4 MB N/A bootloader
1 dtbo_a 8 MB 4 MB N/A dtbo.img
2 dtbo_b Follow dtbo_a 4 MB N/A dtbo.img
3 boot_a Follow dtbo_b 48 MB boot.img format, a
kernel + recovery
ramdisk
boot.img
4 boot_b Follow boot_a 48 MB boot.img format, a
kernel + recovery
ramdisk
boot.img
5system_a Follow boot_b 2560 MB EXT4. Mount as /
system
Android system files under /
system/dir
6system_b Follow
system_a
2560 MB EXT4. Mount as /
system
Android system files under /
system/dir
7misc Follow
system_b
4 MB N/A For recovery store
bootloader message, reserve
8metadata Follow misc 2 MB N/A For system slide show
9 presistdata Follow
metadata
1 MB N/A Option to operate unlock
\unlock
10 vendor_a Follow
persistdata
256 MB EXT4. Mount at /
vendor
vendor.img
11 vendor_b Follow
vendor_a
256 MB EXT4. Mount at /
vendor
vendor.img
12 userdata Follow
vendor_b
Remained
space
EXT4. Mount at /
data
Application data storage for
system application, and for
internal media partition,
in /mnt/sdcard/ dir.
Table continues on the next page...
NXP Semiconductors
Programming Images
Android™ User's Guide, Rev. P9.0.0_2.3.2, 6 March 2020
User's Guide 10 / 31