IoTGateway/BSP/Linux/APQ8016/BSP User Guide V1
Contents
Getting Started
Package Content
An official build release consists of the following contents. We take V1.050 for RSB-4760 as example.
Filename | Usage |
4760LIV1050_sd_install.img.gz | Installation SD card image |
4760LIV1050_2017-05-19_misc.tgz | Kernel, DTS & kernel modules |
4760LIV1050_2017-05-19.tgz | Image binaries (boot image & rootfs) |
4760LIV1050_2017-05-19.csv | Official build information |
4760LBV1050_2017-05-19_sdk.tgz | SDK installer |
4760LBV1050_2017-05-19.tgz | BSP source code, including bootloader binaries |
*.md5, log.tgz & *.log | MD5 checksum & Log files |
Conventions
${BSP_HOME}: home directory of the BSP
${BDIR} : build directory (e.g. build/)
${MACHINE} : available target boards list below
- rsb-4760 / epc-r4761
${DISTRO} : Linux distribution
- rpb / rpb-wayland
${RPB-IMAGES} : meta-rpb provides the following images
- rpb-console-image / rpb-desktop-image / rpb-minimal-image / rpb-qt5-image / rpb-weston-image
Build Environment on Host
Currently, we adopt Docker as build environment.
You can get the latest version of advrisc/u14.04-410clbv1 Docker image for developing Qualcomm APQ8016 projects.
If you don't know much about Docker, please refer to IoTGateway/Docker for details.
BSP
BSP Source
You have two methods to put BSP into Docker container.
[1] Download BSP from GitHub
The oe-rpb-manifest @GitHub is our manifest repository for Qualcomm APQ8016 projects. You can use repo init & repo sync to get the entire BSP we put on GitHub.
Create your own BSP folder first.
$ mkdir ${BSP_HOME} $ cd ${BSP_HOME}
To get the latest version of meta-advantech layer, you can do this.
$ repo init -u https://github.com/ADVANTECH-Corp/oe-rpb-manifest.git -b morty -m 17.06.xml
To get an official release version, you can assign a specific xml, e.g. 410cLBV1060.xml. (Note: This XML does not exist yet. Just an example.)
$ repo init -u https://github.com/ADVANTECH-Corp/oe-rpb-manifest.git -b morty -m 410cLBV1060.xml
Finally, pull down the BSP by running
$ repo sync
Checking the steps in oe-rpb-manifest for details.
[2] Copy BSP tarball into Container
The BSP tarball file can be found in BSP & Image Binaries field in OS Support List.
You can use docker cp to do this.
// Copy BSP source code into container $ docker cp 410cLBV1050_2017-05-19.tgz <your container id>:/home/adv
Or Use docker run with -v options to enable data volume. Then, you are able to put the BSP into the data volume folder.
For example, you can put the BSP into /home/root/workspace folder.
$ docker run -it --name docker_test -v /home/root/workspace:/home/adv/BSP advrisc/u14.04-410clbv1:20170605/bin/bash
BSP Content
The descriptions of some important folders in BSP are listed below:
bitbake/ : Yocto build command
bootloader/ : Bootloader binaries including of CDT, SBL, RPM, LK, etc.
layers/ : Sources for meta-layers
meta-96boards/ : meta layer of 96Boards definitions
meta-advantech/ ':' meta layer by Advantech
meta-qcom/ : meta layer for APQ8016 configurations
meta-rpb/ : meta layer for RPB distro
setup-environment : to set up build environment for Yocto
Naming Rule
The tarball/prebuilt image name consists of the model name followed by "LB" or "LI" plus version number and released date.
For example, BSP file name: 410cLBV1050_2017-05-19.tgz
Which "410c" means Dragonboard410c which a demo board for APQ8016 we use
"LB" is acronym of Linux BSP,
"V1050" stands for Version 1.050.
Another example, Yocto image name: 4760LIV1040_2017-04-20.tgz
which "4760" stands for RSB-4760
"LI" is acronym for prebuilt Linux Image.
Pre-built Images
In LIV tarball file, you can get binary images. For example,
boot-Image--4.4-r0-rsb-4760-20170426102349-52.img : Boot Image
rpb-desktop-image-rsb-4760-20170426102349-52.rootfs.img : Root filesystem
In BSP tarball file, you can see a zip file in bootloader/ folder. It is bootloader binary images.
advantech_bootloader_emmc_linux-72/
cdt_1.1_MT52L256M32D1PF.bin : DDR CDT parameters
emmc_appsboot.mbn : Little Kernel (LK) responsible to load Linux kernel
flashall : Shell script to flash bootloader binaries
gpt_both0.bin : GPT partition table
hyp.mbn : Trust Zone / QHEE
rpm.mbn : Resource and Power Management (RPM)
sbl1.mbn : Secondary Boot Loader (SBL)
tz.mbn : Trust Zone / QSEE
Build Instructions
Create New Build Environment
To create one new build environment, perform following commands in terminal console:
$ cd ${BSP_HOME} $ MACHINE=${MACHINE} DISTRO=${DISTRO} source setup-environment ${BDIR}
You need to read and accept the EULA. Press "Y"
Load Existed Build Environment
To continue an existed build environment, perform following commands in terminal console:
$ cd ${BSP_HOME} $ source setup-environment ${BDIR}
Build Images
To build the desktop image, run
$ bitbake rpb-desktop-image
Build Linux Kernel
To build kernel only, run
$ bitbake linux-linaro-qcomlt
Build Toolchain Installer
To build SDK toolchain installer, perform following commands in terminal console:
$ bitbake ${RPB-IMAGES} -c populate_sdk
Build Bootloader
To build & sign LK bootloader, run
$ cd ${BSP_HOME}
$ cd bootloader/lk
$ make -j4 msm8916 EMMC_BOOT=1 TOOLCHAIN_PREFIX=../toolchain/bin/arm-eabi-
$ mv ./build-msm8916/emmc_appsboot.mbn ./build-msm8916/emmc_appsboot_unsigned.mbn
$ ../signlk/signlk.sh -i=./build-msm8916/emmc_appsboot_unsigned.mbn -o=./build-msm8916/emmc_appsboot.mbn -d
Flash Pre-built Images
We provide two ways to flash pre-built images, Fastboot & Installation SD Card.
Fastboot Tool
By default, we use fastboot
utility to flash images into on-board eMMC. On Ubuntu, you can get the package by this way.
$ sudo apt-get install android-tools-fastboot
To download the images, the target device must be booted into fastboot mode
.
There are 2 ways to do this.
1. Boot from rescue sdcard
- Download the rescue image from here. It will be named like
advantech_sdcard_rescue-<version>.zip
. - Flash the rescue image into a sdcard. Then, insert the sdcard and boot from it. You will enter the fastboot mode by default.
2. Hold volume down key when booting
- While holding down volume down key, power on the target device.
- After a few seconds, release Vol down key. Then, it will enter fastboot mode as well.
- You can only do this, when bootloader is already flashed on your target device.
Once you enter fastboot mode, you can plug a USB cable from host to target device. To verify the fastboot connection, you can run:
$ sudo fastboot devices
Bootloader
Besides, you also need the bootloader packages from here, it will be named something like advantech_bootloader_emmc_linux-<version>.zip
.
Unzip the file and run the flashall
script to update bootloader.
Flash into eMMC
At the end of any successful build you will end up with the following artifacts.
${RPB-IMAGES}-${MACHINE}.ext4.gz
andboot-${MACHINE}.img
If your ${RPB-IMAGES} is rpb-desktop-image
and ${MACHINE} is rsb-4760
, the images will be rpb-desktop-image-rsb-4760.ext4.gz
and boot-rsb-4760.img
respectively.
You can use fastboot to flash them as well.
$ fastboot flash boot boot-${MACHINE}.img
Because fastboot supports sparse image, you have to transform the rootfs image before flashing.
$ gunzip ${RPB-IMAGES}-${MACHINE}.ext4.gz $ ext2simg -v ${RPB-IMAGES}-${MACHINE}.ext4 ${RPB-IMAGES}-${MACHINE}.img $ fastboot flash rootfs ${RPB-IMAGES}-${MACHINE}.img
Installation SD Card
1. Boot from installation SD Card, and Click "Install"
2. Flash all partitions
3. Installing
4. Finish and Reboot
Customization
Set Up SDK
Create Debian Images
In this section, we will show you how to generate a Debian image based on the same Yocto kernel.
Customize the kernel source code
In Yocto BSP, you can build kernel easily. To learn how to build kernel, you can refer to oe-rpb-manifest.
Then, we need three output files in your build artifacts.
- Kernel image (Image-MACHINE.bin)
- DTS image (dt-Image-MACHINE.img)
- Modules (modules-MACHINE.tgz)
Now you need to create a valid boot image with your own kernel build.
On your host PC, we need to install the following tools:
$ git clone git://codeaurora.org/quic/kernel/skales
To create the boot image, you also need a ramdisk image, and you can get one from the 96Boards release:
$ wget https://builds.96boards.org/snapshots/dragonboard410c/linaro/debian/227/initrd.img-4.9.21-linaro-lt-qcom
The tool mkbootimg is a standalone application that will process all files and create the boot image that can then be booted on the target board, or flash into the on-board eMMC. The boot image also contains the kernel bootargs, which can be changed as needed in the next command:
$ ./skales/mkbootimg --kernel Image-MACHINE.bin \ --ramdisk initrd.img-4.9.21-linaro-lt-qcom \ --output boot-MACHINE-debian.img \ --dt dt-Image-MACHINE.img \ --pagesize 2048 \ --base 0x80000000 \ --cmdline "root=/dev/disk/by-partlabel/rootfs rw rootwait console=ttyMSM0,115200n8"
After this step, you will get a boot image for Debian called boot-MACHINE-debian.img.
Revise Debian Rootfs
Basically, we can adopt Linaro's Debian rootfs directly with a little modifications for kernel modules. First, you can get the Debian rootfs from the 96Boards release:
$ wget https://builds.96boards.org/snapshots/dragonboard410c/linaro/debian/227/linaro-stretch-alip-qcom-snapdragon-arm64-20170427-227.img.gz
Second, unzip the file and transform it from sparse image to raw image.
$ gunzip linaro-stretch-alip-qcom-snapdragon-arm64-20170427-227.img.gz $ simg2img linaro-stretch-alip-qcom-snapdragon-arm64-20170427-227.img rootfs.raw
Then, you are able to mount the raw rootfs, and update with your kernel modules.
$ sudo mount -o loop rootfs.raw /mnt $ sudo rm -rf /mnt/lib/modules/ // Copy firmware & modules into /lib $ tar zxf modules-MACHINE.tgz $ sudo cp -a lib/* /mnt/lib $ sudo umount /mnt
Finally, make the rootfs into sparse image.
$ ext2simg -v rootfs.raw linaro-stretch-alip-qcom-snapdragon-arm64-20170427-227-MACHINE.img
Flash Debian Images
Now, you have both boot & rootfs images. You can easily flash them into eMMC via fastboot utility.
$ sudo fastboot erase boot $ sudo fastboot flash boot boot-MACHINE-debian.img $ sudo fastboot erase rootfs $ sudo fastboot flash rootfs linaro-stretch-alip-qcom-snapdragon-arm64-20170427-227-MACHINE.img
Note: After booting up, you have an important thing to do! You have to generate modules.dep and map files.
$ depmod -a
After reboot, the Debian system should work well!