From 03c83c85cc41bb242609872a9b9a7c87550dc8bc Mon Sep 17 00:00:00 2001 From: xzl Date: Fri, 19 Dec 2025 18:51:24 +0800 Subject: [PATCH 1/2] feat: new kernel build docs --- docs/common/dev/_dev-env.mdx | 178 ++++++++ docs/common/dev/_dev-kernel.mdx | 153 +++++++ docs/rock5/rock5b/low-level-dev/dev-env.md | 10 + docs/rock5/rock5b/low-level-dev/kernel.md | 6 +- docs/rock5/rock5b/low-level-dev/u-boot.md | 2 +- .../current/common/dev/_dev-env.mdx | 180 ++++++++ .../current/common/dev/_kernel-dev.mdx | 386 ++++++++++++++++++ .../rock5/rock5b/low-level-dev/dev-env.md | 10 + .../rock5/rock5b/low-level-dev/kernel.md | 6 +- 9 files changed, 924 insertions(+), 7 deletions(-) create mode 100644 docs/common/dev/_dev-env.mdx create mode 100644 docs/common/dev/_dev-kernel.mdx create mode 100644 docs/rock5/rock5b/low-level-dev/dev-env.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/common/dev/_kernel-dev.mdx create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/rock5/rock5b/low-level-dev/dev-env.md diff --git a/docs/common/dev/_dev-env.mdx b/docs/common/dev/_dev-env.mdx new file mode 100644 index 000000000..71ebbf42d --- /dev/null +++ b/docs/common/dev/_dev-env.mdx @@ -0,0 +1,178 @@ +本文档介绍如何在 **x86 主机** 上搭建可用于 **Radxa Linux 内核 / U-Boot** 构建的 ARM64 开发环境。 + +## 推荐环境方案概览 + +根据 Radxa 内部实践和社区使用情况，推荐以下三种环境方案： + +| 方案 | 特点 | 适用场景 | +| ------------------------- | -------------- | ------------------ | +| VS Code Dev Container | 最简单、零污染 | 日常开发、补丁调试 | +| ARM64 Docker 容器 | 稳定、可脚本化 | CI / 自动化构建 | +| systemd-nspawn ARM64 容器 | 无 Docker | 企业 / 受限环境 | + +--- + +## 方案一：VS Code Dev Container + +这是 **最方便部署环境** 的方式。 + +### 前置条件 + +- Docker / Docker Desktop +- Visual Studio Code +- VS Code 插件：`Remote - Containers` + +### 使用方式 + +进入内核或 U-Boot 源码目录： + + + +``` +code . +``` + + + +若目录中存在 `.devcontainer/devcontainer.json`，VS Code 会提示： + +``` +Reopen in Container +``` + +确认后，VS Code 会自动拉起 ARM64 构建容器并进入开发环境。 + +该环境中已包含常用交叉编译工具链和构建依赖。 + +--- + +## 方案二：ARM64 Docker 容器（命令行 / CI 推荐） + +适合命令行用户或 CI 系统使用。 + +### 安装 docker/podman + + + +``` +sudo apt install -y docker.io +sudo systemctl start docker +``` + + + +### 启用多架构支持（仅首次） + + + +``` +sudo apt install -y qemu-user-static binfmt-support +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + + + +### 启动 ARM64 Debian 容器 + + + +``` +docker run -it --rm \ + --platform linux/arm64 \ + -v "$(pwd):/workspace" \ + -w /workspace \ + arm64v8/debian:12 \ + bash +``` + + + +### 安装基础构建依赖 + + + +```bash +apt update +apt install -y \ + build-essential bc kmod cpio flex bison \ + libssl-dev libelf-dev \ + debhelper dh-make \ + git +``` + + + +该容器环境适用于： + +- Linux Kernel 构建 +- U-Boot 构建 +- Debian 内核包生成 + +--- + +## 方案三：systemd-nspawn ARM64 容器（无 Docker） + +适用于无法使用 Docker 的 Linux 主机环境。 + +### 安装工具 + + + +```bash +sudo apt install -y \ + systemd-container \ + qemu-user-static \ + debootstrap \ + debian-archive-keyring +``` + + + +### 创建 ARM64 rootfs + + + +```bash +sudo debootstrap --arch=arm64 \ + bookworm /var/lib/machines/debian12-arm64 \ + http://deb.debian.org/debian +``` + + + +:::tip +若网络遇到问题，可将 `http://deb.debian.org/debian` 替换为国内镜像源，例如： `https://mirrors.tuna.tsinghua.edu.cn/debian/` +::: + +### 进入容器 + + + +```bash +sudo systemd-nspawn -D /var/lib/machines/debian12-arm64 +``` + + + +### 安装构建依赖 + + + +```bash +apt update +apt install -y \ + build-essential bc kmod cpio flex bison \ + libssl-dev libelf-dev \ + debhelper dh-make \ + git +``` + + + +--- + +## 注意事项 + +- 若在 **ARM64 原生设备** 上开发，可直接编译，无需 QEMU +- 构建环境仅用于 **编译**，不涉及刷机或启动配置 +- Kernel 与 U-Boot 构建流程在后续文档中分别说明 diff --git a/docs/common/dev/_dev-kernel.mdx b/docs/common/dev/_dev-kernel.mdx new file mode 100644 index 000000000..f37d2b7f6 --- /dev/null +++ b/docs/common/dev/_dev-kernel.mdx @@ -0,0 +1,153 @@ +本文档介绍如何使用 **Radxa 官方 Linux 内核仓库** 构建 ARM64 内核，并生成可安装的 Debian 内核包。 + +:::tip +请先确保已配置好开发环境，并且在容器内进行操作。具体请参考：[ARM64 内核开发环境准备](./dev-env) +::: + +## 选择正确的内核仓库 + +Radxa 为不同平台维护独立内核仓库，命名格式为： + +``` +https://github.com/radxa-pkg/linux- +``` + +#### Profile 对照表 + +| 设备 | Profile | +| ------------------------------------- | ------------ | +| ROCK 5A / 5B / 5B\+ / 5C / 5T / 5 ITX | rk2410 | +| ROCK 2A/ROCK 2F/ E20C/E24C | rk2312 | +| E52C / E54C / NX5 / CM5 | rk2410 | +| ROCK 3 系列 / ZERO 3 / CM3 | rk2410-nocsf | +| ROCK Pi 4 / ROCK 4（除 4D） | rk2501 | +| ROCK 4D | rk2410-nocsf | +| Dragon Q6A | qcom | +| AIRBox Q900 | qc2509 | +| Cubie A7A / A7Z | a733 | +| Orion O6 / O6N | sky1 | + +--- + +## 克隆内核源码 + +:::tip +请先确保已配置好开发环境，并且在容器内进行操作。 +::: + +克隆时必须包含子模块： + + + +``` +git clone --recurse-submodules \ + https://github.com/radxa-pkg/linux-rk2410.git +cd linux-rk2410 +``` + + + +若克隆时遗漏子模块，可在仓库目录中补齐： + + + +``` +git submodule update --init --recursive +``` + +## + +## 构建 Debian 内核包（推荐） + +适用于 RadxaOS / Debian / Ubuntu 系统，推荐优先使用该方式。 + +#### 安装构建依赖 + + + +``` +sudo apt build-dep . +``` + + + +#### 配置内核 + +- 如果你需求修改内核源码，可直接编辑 `src` 目录下的源码文件。 +- 如果你需求修改内核配置文件，可以修改 `/debian/patches/linux/`目录下的 patch 文件 + +#### 构建内核包 + + + +``` +make deb +``` + + + +生成的文件包括： + +- linux-image-\*.deb +- linux-headers-\*.deb + +--- + +## 手动构建（高级） + +适用于需要自定义内核配置或不生成 Debian 包的高级场景。 + + + +``` +cd src +make menuconfig +make -j"$(nproc)" +``` + + + +--- + +## 安装与验证 + +### 安装内核 + +需要退出容器环境，并将产物拷贝到 SBC 板端系统 + + + +``` +exit +``` + + + +后面的步骤在 SBC 板端系统进行： + + + +```bash +sudo dpkg -i linux-image-*.deb linux-headers-*.deb +sudo reboot +``` + + + +### 验证 + + + +``` +uname -r +zcat /proc/config.gz | grep CONFIG_XXX +``` + + + +--- + +## 注意事项 + +- 克隆仓库时必须使用 `--recurse-submodules`，否则可能因缺失子模块导致构建失败。 +- 内核安装后是否生效，取决于启动加载器和启动配置是否正确加载了新内核。 diff --git a/docs/rock5/rock5b/low-level-dev/dev-env.md b/docs/rock5/rock5b/low-level-dev/dev-env.md new file mode 100644 index 000000000..6c7e833a1 --- /dev/null +++ b/docs/rock5/rock5b/low-level-dev/dev-env.md @@ -0,0 +1,10 @@ +--- +sidebar_position: 2 +description: "Radxa 开发环境配置" +--- + +import DEVENV from '../../../common/dev/\_dev-env.mdx' + +# 开发环境准备 + + diff --git a/docs/rock5/rock5b/low-level-dev/kernel.md b/docs/rock5/rock5b/low-level-dev/kernel.md index fc4f8f48a..45fb9ae82 100644 --- a/docs/rock5/rock5b/low-level-dev/kernel.md +++ b/docs/rock5/rock5b/low-level-dev/kernel.md @@ -1,10 +1,10 @@ --- sidebar_position: 3 -description: "用 Radxa BSP 工具，轻松构建个性化 Linux 内核，享受定制化硬件开发的乐趣" +description: "Radxa kernel 开发" --- -import KERNEL from '../../../common/dev/\_kernel.mdx' +import KERNEL from '../../../common/dev/\_dev-kernel.mdx' # Kernel 开发 - + diff --git a/docs/rock5/rock5b/low-level-dev/u-boot.md b/docs/rock5/rock5b/low-level-dev/u-boot.md index 59252df28..1ae86a954 100644 --- a/docs/rock5/rock5b/low-level-dev/u-boot.md +++ b/docs/rock5/rock5b/low-level-dev/u-boot.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 4 description: "用 Radxa BSP 工具，轻松构建个性化 U-boot，开启智能硬件的创新之旅" --- diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx new file mode 100644 index 000000000..bedf9d0b4 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx @@ -0,0 +1,180 @@ +# ARM64 Kernel Build Environment Setup + +This document describes how to set up an ARM64 build environment on an **x86 host** for building the **Radxa Linux kernel / U-Boot**. + +## Overview of Recommended Options + +Based on internal Radxa practices and community usage, we recommend the following three options: + +| Option | Highlights | Typical Scenarios | +| ------------------------------ | ----------------------------- | ------------------------------------ | +| VS Code Dev Container | Easiest, no pollution to host | Daily development, patch debugging | +| ARM64 Docker container | Stable, scriptable | CI / automated builds | +| systemd-nspawn ARM64 container | No Docker required | Enterprise / restricted environments | + +--- + +## Option 1: VS Code Dev Container + +This is the **most convenient** way to prepare the environment. + +### Prerequisites + +- Docker / Docker Desktop +- Visual Studio Code +- VS Code extension: `Remote - Containers` + +### Usage + +Enter the kernel or U-Boot source tree directory: + + + +``` +code . +``` + + + +If the directory contains `.devcontainer/devcontainer.json`, VS Code will show a prompt: + +``` +Reopen in Container +``` + +After confirming, VS Code will automatically start an ARM64 build container and attach to it. + +The container already includes commonly used cross compilation toolchains and build dependencies. + +--- + +## Option 2: ARM64 Docker Container (CLI / CI Recommended) + +Suitable for command-line users or CI systems. + +### Install docker / podman + + + +``` +sudo apt install -y docker.io +sudo systemctl start docker +``` + + + +### Enable Multi-Architecture Support (Once Only) + + + +``` +sudo apt install -y qemu-user-static binfmt-support +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + + + +### Start an ARM64 Debian Container + + + +``` +docker run -it --rm \ + --platform linux/arm64 \ + -v "$(pwd):/workspace" \ + -w /workspace \ + arm64v8/debian:12 \ + bash +``` + + + +### Install Basic Build Dependencies + + + +```bash +apt update +apt install -y \ + build-essential bc kmod cpio flex bison \ + libssl-dev libelf-dev \ + debhelper dh-make \ + git +``` + + + +This container environment is suitable for: + +- Linux kernel builds +- U-Boot builds +- Building Debian kernel packages + +--- + +## Option 3: systemd-nspawn ARM64 Container (No Docker) + +Suitable for Linux hosts where Docker cannot be used. + +### Install Tools + + + +```bash +sudo apt install -y \ + systemd-container \ + qemu-user-static \ + debootstrap \ + debian-archive-keyring +``` + + + +### Create an ARM64 rootfs + + + +```bash +sudo debootstrap --arch=arm64 \ + bookworm /var/lib/machines/debian12-arm64 \ + http://deb.debian.org/debian +``` + + + +:::tip +If network access is slow, you can replace `http://deb.debian.org/debian` with a closer mirror, for example: `https://mirrors.tuna.tsinghua.edu.cn/debian/`. +::: + +### Enter the Container + + + +```bash +sudo systemd-nspawn -D /var/lib/machines/debian12-arm64 +``` + + + +### Install Build Dependencies + + + +```bash +apt update +apt install -y \ + build-essential bc kmod cpio flex bison \ + libssl-dev libelf-dev \ + debhelper dh-make \ + git +``` + + + +--- + +## Notes + +- If you are developing on an **ARM64 native device**, you can build directly without QEMU. +- These environments are only for **building** images, not for flashing or boot configuration. +- The detailed build flows for kernel and U-Boot are described in their respective documents. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_kernel-dev.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_kernel-dev.mdx new file mode 100644 index 000000000..35c9e112a --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_kernel-dev.mdx @@ -0,0 +1,386 @@ +# ARM64 Kernel Development Guide Based on Radxa Kernel Repository + +This document explains how to obtain the official Radxa Linux kernel source code and perform ARM64 kernel development and compilation on an x86 host in various ways. It includes source code acquisition, development environment setup (4 options), compilation, and deployment. + +## Obtaining the Kernel Source Code for Your Device + +Radxa maintains separate kernel repositories for different hardware platforms. The repository naming format is: + +```bash +https://github.com/radxa-pkg/linux- +``` + +Select the correct `` based on your device model. Common mappings are as follows: + +| # | Device Model (Product) | Profile | +| :-: | :---------------------------------------: | :-----------: | +| 1 | ROCK 5A / 5B / 5B\+ / 5C / 5T / 5 ITX | rk2410 | +| 2 | ROCK 2A/ROCK 2F/ E20C/E24C | rk2312 | +| 3 | E52C / E54C / NX5 / CM5 Series | rk2410 | +| 4 | ROCK 3A / 3B / 3C / ZERO 3 CM3 | rk2410\-nocsf | +| 5 | ROCK Pi 4 / ROCK 4 Series (except ROCK4D) | rk2501 | +| 6 | ROCK4D | rk2410\-nocsf | +| 7 | Dragon Q6A | qcom | +| 8 | AIRBox Q900 | qc2509 | + +:::info +Submodules must be cloned recursively + +Radxa kernel repositories rely on multiple submodules (e.g., kernel source code). Failure to properly initialize submodules may result in compilation failures or missing critical files. +::: + +Example (using ROCK 5B): + +```bash +git clone --recurse-submodules https://github.com/radxa-pkg/linux-rk2410.git +cd linux-rk2410 +``` + +If you have already cloned but not initialized submodules, you can run: + +```bash +git submodule update --init --recursive --progress +``` + +:::tip +If you encounter network issues, you can try using a proxy (e.g., `https://gh-proxy.com/`) to speed up cloning. If submodule cloning fails, you can try editing the `.gitmodules` file to replace the submodule URLs with proxy addresses. + +Additionally, we have mirrored these repositories on the Chinese git platform gitcode. The address formats are: + +- `https://gitcode.com/radxa-pkg/linux-` +- `https://gitcode.com/radxa/kernel.git` + +You can choose to use them as needed. +::: + +--- + +## Development Environment Setup (Four Options) + +### Option 1: Using VS Code Dev Container (Recommended, Lightweight and Convenient) + +1. Ensure the following are installed: + - Docker (Docker Desktop or Docker Engine) + - Visual Studio Code + - Remote - Containers extension +2. Open VS Code in the project root directory: + + ```bash + code . + ``` + +3. If `.devcontainer/devcontainer.json` exists, VS Code will prompt "Reopen in Container." Click to enter the pre-configured ARM64 development environment. + +:::tip +If you encounter network issues, it is recommended to uncomment the code under `Uncomment below to speed up container building in China` in `devcontainer.json`. +::: + +--- + +### Option 2: Manually Running ARM64 Docker Container (Flexible and Controllable) + +#### Step 1: Enable Multi-Architecture Support (Only Once) + +Run the following on the host: + +```bash +sudo apt-get install -y qemu-user-static binfmt-support +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + +#### Step 2: Start the Container and Mount the Source Code + +Ensure you are in the directory with the fully cloned (including submodules) source code: + +```bash +docker run -it --rm \ + --platform linux/arm64 \ + -v "$(pwd):/workspace" \ + -w /workspace \ + arm64v8/debian:12 \ + bash +``` + +#### Step 3: Switch to Debian Mirror Sources + +If you have fast access to the official Debian software sources, you can skip this step. + +```bash +sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak +cat < diff --git a/i18n/en/docusaurus-plugin-content-docs/current/rock5/rock5b/low-level-dev/kernel.md b/i18n/en/docusaurus-plugin-content-docs/current/rock5/rock5b/low-level-dev/kernel.md index f99f96e50..5e8d22279 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/rock5/rock5b/low-level-dev/kernel.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/rock5/rock5b/low-level-dev/kernel.md @@ -1,10 +1,10 @@ --- sidebar_position: 3 -description: "Easily build personalised Linux kernels and enjoy custom hardware development with the Radxa BSP tool" +description: "Radxa kernel development guide" --- -import KERNEL from '../../../common/dev/\_kernel.mdx' +import KERNEL from '../../../common/dev/\_kernel-dev.mdx' # Kernel Development - + From 6e30c32c8f99eda390e83dbc5951e9b1219717c2 Mon Sep 17 00:00:00 2001 From: xzl Date: Mon, 22 Dec 2025 11:11:16 +0800 Subject: [PATCH 2/2] fix: Add more detailed explanations. --- docs/common/dev/_dev-env.mdx | 10 +++++++--- .../rock5b/low-level-dev/{kernel.md => dev-kernel.md} | 0 .../current/common/dev/_dev-env.mdx | 8 ++++++-- 3 files changed, 13 insertions(+), 5 deletions(-) rename docs/rock5/rock5b/low-level-dev/{kernel.md => dev-kernel.md} (100%) diff --git a/docs/common/dev/_dev-env.mdx b/docs/common/dev/_dev-env.mdx index 71ebbf42d..fb212d4a8 100644 --- a/docs/common/dev/_dev-env.mdx +++ b/docs/common/dev/_dev-env.mdx @@ -24,7 +24,9 @@ ### 使用方式 -进入内核或 U-Boot 源码目录： +请参照 [内核开发](./dev-kernel.md) 克隆所需的源码 + +进入内核源码目录： @@ -34,7 +36,7 @@ code . -若目录中存在 `.devcontainer/devcontainer.json`，VS Code 会提示： +radxa 提供的内核目录中存在 `.devcontainer/devcontainer.json`，VS Code 会提示： ``` Reopen in Container @@ -42,7 +44,9 @@ Reopen in Container 确认后，VS Code 会自动拉起 ARM64 构建容器并进入开发环境。 -该环境中已包含常用交叉编译工具链和构建依赖。 +如果没有提示，可以自行按`F1`或者`Ctrl+Shift+P`，输入 `DevContainers: Reopen in Container` 来启动容器。 + +该环境中已包含常用交叉编译工具链和构建依赖，无需手动安装。 --- diff --git a/docs/rock5/rock5b/low-level-dev/kernel.md b/docs/rock5/rock5b/low-level-dev/dev-kernel.md similarity index 100% rename from docs/rock5/rock5b/low-level-dev/kernel.md rename to docs/rock5/rock5b/low-level-dev/dev-kernel.md diff --git a/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx b/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx index bedf9d0b4..51342befe 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/common/dev/_dev-env.mdx @@ -26,7 +26,9 @@ This is the **most convenient** way to prepare the environment. ### Usage -Enter the kernel or U-Boot source tree directory: +Please refer to [Kernel Development](./dev-kernel.md) to clone the required source code. + +Then enter the kernel or U-Boot source tree directory: @@ -44,7 +46,9 @@ Reopen in Container After confirming, VS Code will automatically start an ARM64 build container and attach to it. -The container already includes commonly used cross compilation toolchains and build dependencies. +If there is no prompt, you can press `F1` or `Ctrl+Shift+P`, then run `DevContainers: Reopen in Container` to start the container manually. + +The container already includes commonly used cross compilation toolchains and build dependencies, so you do not need to install them manually. ---