新手入门

Install dependencies

Debian 12 / Ubuntu 22.04

sudo apt update
sudo apt install -y git qemu-user-static binfmt-support

# Podman (recommended)
sudo apt install -y podman podman-docker
sudo touch /etc/containers/nodocker
# Docker
#sudo apt install docker.io

# Optional dependcies for minor features
sudo apt install -y systemd-container

Check out the code

bsp uses git submodules. As such, please check out the code with the following command:

git clone --recurse-submodules https://github.com/radxa-repo/bsp.git

Understand `bsp`'s usage

Once the repo is cloned on your machine, you can run bsp to check the built-in help:

Tip

The built-in help is intended as the first step to troubleshoot for bsp usage, while the documentation site covers more about high level applications and low level implementation details. As such, you are more likely to find your questions solved by an option listed in the built-in help.

It is strongly recommended to read the built-in help at once, if you want to do anything beyond the trival package rebuild.

cd bsp
./bsp

Build your first packages

bsp now supports building kernel and U-Boot in a single step, and specify them by product name instead of specific profiles. This should help new users to test their setup without much bsp knowledge:

# The following command will build linux-stable
# and u-boot-latest for radxa-zero
./bsp radxa-zero

Custom kernel/firmware developer should at least read the Development reference section to better understand the development workflow and the internal data sctructure for bsp.

Local development workflow

In this article, we will demonstrate how to develop and create patches for bsp.

Prepare working tree

Use --no-build and -C|--distclean to set up the source tree with bsp predefined profiles:

./bsp -C --no-build linux latest

Retrive additional commit history

bsp uses shallow clone by default to save bandwidth and speed up build process. However, you might want to access additional git history for rebase or cherry-pick. You can use either of the following 2 options to fetch more commits:

cd .src/linux
# Fetch HEAD~10 commits
git fetch --depth=10 --all
# Fetch everything
# WARNING! VERY SLOW!
git fetch --unshallow --all

Build packages

You can use --dirty to build without resetting the source tree. This will allow the build process to reuse previously built objects:

./bsp --dirty linux latest

Note

Currently --dirty is broken for linux. You can use following arguments to allow bsp to rebuild .config to workaround this issue:

./bsp --no-prepare-source --no-container-update linux latest

Install build artifacts

You can use ./bsp install to install the built package to a root partition (like a microSD card):

./bsp install linux-image-6.*_arm64.deb /dev/sdb2

Create patch set

After you are happy with the changes, you can export your commits with git format-patch:

mkdir -p linux/latest/0500-my-first-pr
cd .src/linux
# Update start-number to the last one + 1
# in your targetting patch subfolder
git format-patch -M -N --start-number 1 --zero-commit -o ../../linux/latest/0500-my-first-pr HEAD~1

Move the outputted patch files to the corresponding subfolder, and you are ready to submit your first PR!

Developer FAQ

`bsp` takes a lot of time applying patches

There are 2 possible causes:

Your bsp project is stored on mechinical hard drives.
As patching is random 4K intensive, we suggest you put bsp on solid state drives.
Your source tree has too many dangling commits.
This happens naturally as you use the project. You can go to the source tree under .src and run git gc --prune to restore the performance.

Understand profile

Profiles are subfolders under linux and u-boot folder. Each of them describes a specific flavor of their targeted software.

Special files

fork.conf: Profile config file
kconfig.conf: kconfig overriding file

Tree structure and mode of operation

sample
├── 0001-common -> ../.common/
├── 0010-backport
│   ├── 0001-scripts-dtc-Update-to-upstream-version-v1.6.0-51-g18.patch
│   ├── 0002-kbuild-Add-support-to-build-overlays-.dtbo.patch.ignore
│   ├── 0003-mm-page_alloc-fix-building-error-on-Werror-array-com.patch
│   └── 0004-etherdevice-Adjust-ether_addr-prototypes-to-silence-.patch
├── 0001-Fix-multiple-definition-of-yylloc.patch
├── 0002-Suppress-additional-warnings.patch
├── fork.conf
├── kconfig.conf
└── rockchip -> ../.rockchip

fork.conf

fork.conf is the profile configuration file. This file is mandatory and is sourced early by bsp.

BSP_GIT defines upstream source repo.

BSP_COMMIT or BSP_BRANCH or BSP_TAG defines the exact source code. The first defined option in the listed order will be used.

BSP_DEFCONFIG defines the defconfig used for building. Default to defconfig.

SUPPORTED_BOARDS defines the supported product list, which is a Bash array. bsp will use this list to create virtual packages that reference the binary package. Suffixes are commonly used to denote kernel/firmware variants that also support the same board. However, the default package is the one that matches exactly to the product name.

kconfig.conf

kconfig.conf is a kernel configuration file. This file mirrors defconfig format.

Firmware management

Firmware, or do you mean U-Boot?

bsp is intended to be a general Board Support Package builder. In this sense, there are firmwares which perform low level initialization, and kernel which runs the operating system. Currently the only kernel bsp supports is Linux, and the only supported firmware is U-Boot. However, we plan to support EDK2 in the future, thus this section is titled firmware management.

U-Boot installation location

Following Debian convention, we install U-Boot under /usr/lib/u-boot folder, and save all supported bootloaders in a single package.

We also provide a maintenance script called setup.sh.

Extracting binaries from released package

Firmware binaries are usually needed to perform various offline recovery tasks. As we only release firmware in the form of Debian package, it is necessary to extract the required files first before performing any recovery steps.

On Windows, you can extract .deb files with 7-Zip.

On Linux, you can run following command to extrace the package:

ar p u-boot-latest.deb data.tar.xz | tar -xJ

`setup.sh` usage

Under each board's directory, there are a few binary blobs, along with a maintenance script called setup.sh, which provides a wrapper for common management tasks.

There is minimal error checking in the script, as such, it is intended as the advanced method of bootloader management. Normal user should use rsetup instead, which provides a TUI for bootloader update.

Additionally, not all commands are intended for the end user usage. Below are documented and supported commands:

Common `setup.sh` command

`setup.sh maskrom`

Maskrom is a special boot mode, that can run binary passed via USB OTG connection. This is usually the first command to run when you boot the board in maskrom mode.

For Amlogic devices, the binary is actually a normal U-Boot binary running in memory, so you can access the U-Boot console for recovery.

For Rockchip devices, the binary allows access to on-board eMMC via rkdeveloptool.

Running from GitHub Workflows

Please check out our GitHub workflows as an example.

Reproduce a previous release

In this example, we will recreate linux-rockchip 5.10.110-5 package.

Find the original GitHub release for the desired package
For our example, it is located at https://github.com/radxa-pkg/linux-rockchip/releases/tag/5.10.110-5.
From the release pages, you will see multiple packages.
We will focus on the top 2 packages:

File Name	Size
linux-headers-5.10.110-5-rockchip_5.10.110-5-1932709cf_arm64.deb	7.4 MB
linux-headers-radxa-nx5-io_5.10.110-5-3a557f6_all.deb	1.1 KB

As our packages are built with bsp and radxa/kernel, there are 2 git commits that we need to find out to accurately reproduce those packages:
Since the real package (the one with larger file size) is closely related to radxa/kernel, 1932709cf is the commit for it.
Since the meta package (the one with smaller file size) is closely related to bsp, 3a557f6 is the commit for it.
We now have the following essential commit information:
radxa/kernel: 1932709cf
bsp: 3a557f6
However, fork.conf only takes full commit hash. So click the radxa/kernel link above, and click Browse files button on GitHub page, that will get you the full commit hash in the URL bar: radxa/kernel: 1932709cf7d98d0d92952bba38d990d938fabc58
We can also check the content of overlay.sh to find the commit used for radxa/overlays:
radxa/overlays: 4940ae33e4def0fb9133faf68adf0c3421b61f06
We can now recreate the package:

git clone --recurse-submodules https://github.com/radxa-repo/bsp.git
cd bsp
# switch to bsp commit found above
git switch --detach 3a557f6
# replace BSP_BRANCH with radxa/kernel commit found above
sed -i "s/BSP_BRANCH.*/BSP_COMMIT='1932709cf7d98d0d92952bba38d990d938fabc58'/" linux/rockchip/fork.conf
./bsp linux rockchip
# the prepared kernel tree will be available under .src/linux

bsp