# opiz3

**Repository Path**: yangdonggit/opiz3

## Basic Information

- **Project Name**: opiz3
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Orange Pi Zero 3 (H618) Yocto 工程 — opiz3

纯 OpenEmbedded-Core 自建工程：**Yocto LTS 6.0 "Wrynose"**，不使用 meta-poky，自建 DISTRO；主线内核 / U-Boot；init 为 sysvinit（busybox）。板卡：Orange Pi Zero 3（Allwinner H618）。上游层以 **git submodule** 管理，仓库只含自有内容。

## 1. 工程结构

```
opiz3/                        # 仓库根（git clone --recursive）
├── build_distro/             # ★ 统一输出目录（不入库，首次构建自动创建）
│   ├── opiz3/                #   opiz3（core-image-base）
│   │   └── tmp/deploy/images/orange-pi-zero3/   # 镜像产物
│   └── opiz3-mini/           #   opiz3-mini（core-image-minimal）
│       └── tmp/deploy/images/orange-pi-zero3/
├── sources/
│   ├── openembedded-core/    # submodule · wrynose（基础层）
│   ├── bitbake/              # submodule · master 2.19.1
│   ├── meta-openembedded/    # submodule · wrynose（meta-oe + meta-python）
│   ├── meta-arm/             # submodule · wrynose（TFA 2.14.1）
│   ├── meta-sunxi/           # submodule · master（机器定义/主线内核/固件）
│   └── meta-opiz3/           # ★ 自建层（priority 15，入库）
│       ├── conf/layer.conf
│       ├── conf/distro/opiz3.conf         # 自建发行版（sysvinit）
│       ├── conf/distro/opiz3-mini.conf    # mini 最简发行版（继承+裁剪）
│       ├── recipes-kernel/linux/
│       │   ├── linux-mainline_%.bbappend  # 内核 fragment 合并
│       │   └── files/opiz3.cfg            # dwmac/PHY/TRNG/裁剪配置
│       ├── recipes-bsp/u-boot/
│       │   └── u-boot_%.bbappend          # TFA 依赖 + USB 裁剪 + boot.scr 定制
│       └── recipes-core/
│           ├── dropbear/                  # key 预生成 + 后台生成
│           └── init-ifupdown/             # eth0 关闭 udhcpc（-b 后台，快速启动）
├── build.sh                  # ★ 统一构建入口（多 distro 交互选择，并行度 16）
├── .gitmodules               # 5 个上游 submodule 声明
├── .gitignore
└── README.md
```

## 2. 版本信息

| 组件 | 版本 | 来源（submodule） |
|---|---|---|
| openembedded-core | wrynose (LTS 6.0, 2026-05) `883075157987` | github.com/openembedded/openembedded-core |
| bitbake | 2.19.1 (master) `046a90b0e9b7` | github.com/openembedded/bitbake |
| meta-openembedded | wrynose `47d7dbdd1089` | github.com/openembedded/meta-openembedded |
| meta-arm | wrynose（TFA 2.14.1）`9dab8bdd4991` | **git.yoctoproject.org/meta-arm**（github 镜像 401） |
| meta-sunxi | master `fa1f75af1697` | github.com/linux-sunxi/meta-sunxi |
| 内核 | linux-mainline **6.18.40**（=y 内建，Image.gz） | kernel.org / meta-sunxi |
| U-Boot | **2026.01**（主线 + sunxi） | oe-core / meta-sunxi |

## 3. 编译命令（统一入口 build.sh）

```bash
./build.sh -h                 # 列出支持的 distro
./build.sh                    # 列出 distro 并等待选择后构建
./build.sh opiz3              # 直接构建 opiz3（core-image-base）
./build.sh opiz3-mini         # 直接构建 opiz3-mini（core-image-minimal）
./build.sh opiz3 -c cleanall  # 追加 bitbake 参数
./build.sh --deps             # 仅安装 Ubuntu/Debian 构建依赖（需 sudo）
```

自动完成：校验 submodule → 首次自动生成 `build_distro/<distro>/conf`（相对路径）→ 加载 oe-init-build-env → bitbake。

底层等价：
```bash
cd build_distro/opiz3
export PATH=$PWD/../../sources/bitbake/bin:$PWD/../../sources/openembedded-core/scripts:$PATH
source ../../sources/openembedded-core/oe-init-build-env .
bitbake core-image-base
```

## 4. 层依赖关系

```
meta-opiz3（priority 15，最后解析，LAYERDEPENDS=sunxi）
    ▲
meta-sunxi（priority 10，LAYERDEPENDS=core/meta-python/meta-arm）
    ▲
meta-arm / meta-arm-toolchain / meta-python / meta-oe（priority 5）
    ▲
openembedded-core/meta（priority 5，最先解析）
```

**为什么 meta-opiz3 最后**：优先级最高（15>10>5），bbappend 覆盖优先生效；`LAYERDEPENDS=sunxi` 保证上游先加载。**bitbake 解析顺序**：machine → distro/opiz3.conf → defaultsetup.conf（故 `INIT_MANAGER="sysvinit"` 不被 `??= systemd` 覆盖）。

## 5. 内核配置（opiz3.cfg，全部 =y 内建）

### 5.1 必要功能（=y 内建，不可裁剪）

```ini
CONFIG_STMMAC_ETH=y        # DWMAC_SUN8I 依赖核心（否则驱动被降级 =m）
CONFIG_STMMAC_PLATFORM=y
CONFIG_DWMAC_SUN8I=y       # dwmac-sun8i 编译进内核（5020000.ethernet）
CONFIG_PHY_MOTORCOMM=y     # 板载 PHY YT8531C
CONFIG_MOTORCOMM_PHY=y
CONFIG_CRYPTO_DEV_SUN8I_CE=y        # H616 硬件 TRNG（crng 快速初始化）
CONFIG_CRYPTO_DEV_SUN8I_CE_TRNG=y
CONFIG_MMC=y / MMC_SUNXI=y / MMC_SDHCI=y   # SD/eMMC（rootfs 挂载）
```

### 5.2 已裁剪（`is not set`，按功能点）

| 功能 | 配置 | 原因 |
|---|---|---|
| 虚拟化/KVM | VIRTUALIZATION / KVM | 无虚拟机场景 |
| NFC | NFC | 无 NFC 硬件 |
| 蓝牙 | BT（连带 ecdh/ecc 自动关闭） | 已裁剪 |
| 射频/无线 | RFKILL / CFG80211 / WLAN | 已裁剪（无 WiFi 模组） |
| IPv6 | IPV6 | 纯 IPv4 环境 |
| USB 子系统 | USB_SUPPORT | 无 USB 设备需求 |
| ALSA 声卡 | SOUND / SND | 无音频 |
| 9p/virtio | 9P_FS / VIRTIO 全系 | 无虚拟化 |
| 显示 | DRM / FB | 无 HDMI/LCD |
| **NFS** | **NFS_FS / NFS_V2..V4_2 / ROOT_NFS / IP_PNP(+DHCP/BOOTP/RARP)** | **已移除，不再挂载 NFS** |

> 曾尝试第二轮深度裁剪（SPI / x86 网卡 E1000/E1000E/IGB/SKY2/THUNDER / VFIO / TUN / LOOP / SQUASHFS / EDAC / SCSI / ATA / 非 sunxi MMC），因在目标板出现启动异常已**整体回退**，保持主线默认（详见 §8.9）。

## 6. mini 最简配置（opiz3-mini）

`require conf/distro/opiz3.conf` 继承，在 distro conf 中裁剪：

- `DISTRO_FEATURES:remove = "bluetooth wifi nfc 3g zeroconf pci alsa pulseaudio keyboard ldconfig"`
- `MACHINE_FEATURES:remove = "keyboard"`（去掉 kbd/loadkeys/keymap，~1MB）
- `VIRTUAL-RUNTIME_dev_manager = "busybox-mdev"`（udev→mdev，省 ~1.2MB + 启动更快）
- `IMAGE_INSTALL:remove = "udev kmod modutils-initscripts"`（kmod 连带 libcrypto 5.6MB 消失）
- `IMAGE_OVERHEAD_FACTOR = "1.0"` + `IMAGE_ROOTFS_EXTRA_SPACE = "0"`（wic 紧凑化）
- `KERNEL_IMAGETYPE = "Image.gz"`（压缩内核镜像）
- 镜像 `core-image-minimal`，输出 `build_distro/opiz3-mini/`

| 维度 | opiz3 | opiz3-mini |
|---|---|---|
| 镜像 | core-image-base | core-image-minimal |
| 打包数量 | 123 | 32 |
| wic.gz | 53.6 MB | **15.5 MB**（build17，回退后） |
| Image.gz | — | **12.76 MB**（6.18.40） |
| init | sysvinit/busybox | sysvinit/busybox |

## 7. 构建产物

```
build_distro/opiz3-mini/tmp/deploy/images/orange-pi-zero3/
├── core-image-minimal-orange-pi-zero3.rootfs-*.wic.gz   # 15.5 MB，烧 SD 卡
├── Image.gz--6.18.40-r0-orange-pi-zero3-*.bin           # 12.76 MB（压缩内核）
├── u-boot-sunxi-with-spl.bin-orange-pi-zero3-2026.01-r0
├── sun50i-h618-orangepi-zero3.dtb / boot.scr
└── trusted-firmware-a/bl31.bin
```

## 8. 关键排障记录

1. **meta-arm master 与 wrynose 不兼容**（1009 LICENSE 解析错误）→ 切 `wrynose` 分支。
2. **u-boot 缺 BL31**：meta-sunxi 的 task-flag 在 bitbake 2.19 失效 → meta-opiz3 补 `do_compile[depends] += "trusted-firmware-a:do_deploy"`。
3. **`DWMAC_SUN8I=y` 被降级 =m**：依赖 `STMMAC_ETH=m` → 同时置 `STMMAC_ETH=y` + `STMMAC_PLATFORM=y`。
4. **`debug-tweaks` 是 poky 专属** → 改用 oe-core 特性组合。
5. **fragment 路径**：kernel-yocto 解包到 `${WORKDIR}/sources/`，merge 指向 `sources/opiz3.cfg`（经 bbappend `SRC_URI:append = " file://opiz3.cfg"` 引用，勿直接 cat 覆盖 bbappend）。
6. **root 空密码失败（wrynose 特性改名）**：`empty-root-password` 控制 root 置空与串口自动登录（`allow-empty-password` 只管 SSH）→ 已固化到 distro：`IMAGE_FEATURES:append = " empty-root-password allow-empty-password allow-root-login serial-autologin-root"`。
7. **"Starting kernel" 后无任何输出（假卡死）**：boot.cmd 模板 `console=${console}` 依赖 U-Boot 环境变量但未定义 → bootargs 无 `console=`，内核无串口控制台。修复：bbappend 硬编码 `console=ttyS0,115200`。
8. **内核层强制清理须用 `cleanall`**：`cleansstate` 会残留损坏源码（Makefile 缺失 → kernel_version 显示 "."、dts patch 失败），`cleanall` 连同工作区清空重解包（下载源在共享 `downloads/`，无需重下）。
9. **第五阶段内核裁剪回退**：SPI/x86 网卡/SCSI/ATA 等一批裁剪在目标板出现启动异常（未最终定位到具体项），已整体回退到主线默认；NFS 移除保留。
10. **`PACKAGE_EXCLUDE kbd` 会冲突**：keymaps 硬依赖 kbd → 改 `MACHINE_FEATURES:remove = "keyboard"`（`.conf.append` 不被 bitbake 加载，须写 distro conf）。
11. **modutils.sh 归属**：来自 oe-core `modutils-initscripts`（recipes-kernel 目录），经 `IMAGE_INSTALL:remove` 移除；若仍有残留属间接依赖链，可改用 `PACKAGE_EXCLUDE`。

## 9. 拉取仓库与初始化

```bash
# 方式 A：克隆时自动拉取全部 submodule（推荐）
git clone --recursive https://gitee.com/yangdonggit/opiz3.git && cd opiz3

# 方式 B：已克隆但未带 --recursive，补拉 submodule
cd opiz3
git submodule update --init --recursive

# 检查 submodule 状态：前缀为空格=正常；'-'=未初始化（补拉）；'+'=commit 漂移（勿改内部代码）
git submodule status
```

> 5 个上游层以 submodule 固定 commit；其中 meta-arm 走 `git.yoctoproject.org`（github 镜像 401 不可用），需可访问该域名。初始化完成后直接构建：

```bash
./build.sh --deps     # 可选：装 Ubuntu/Debian 构建依赖（需 sudo）
./build.sh -h         # 查看支持的 distro
./build.sh            # 交互选择后构建（或 ./build.sh opiz3 / opiz3-mini）
```

要求：Ubuntu/Debian 64 位、可访问 github.com 与 git.yoctoproject.org、磁盘 ≥ 40 GB（全新构建约 1.5–2 小时）。

## 10. Git 仓库（gitee）

- 仓库：`https://gitee.com/yangdonggit/opiz3`（main 分支）
- 上游 5 层为 submodule（gitlink），仓库仅含自有内容：`meta-opiz3/`、`build.sh`、`.gitmodules`、`.gitignore`、`README.md`
- 拉取：`git clone --recursive https://gitee.com/yangdonggit/opiz3.git`（见第 9 节）

## 11. 后续计划

- [ ] 板端实测 build17（回退后）启动时间与稳定性
- [ ] 若需继续压缩：在 build17 基础上逐个重试第五阶段裁剪项（先 SPI → 再 x86 网卡组 → 再 SCSI/ATA 组），定位异常项后选择性恢复
- [ ] UWE5622 / AW859A WiFi-BT 已按裁剪移除；如回归需恢复 BT/RFKILL/CFG80211 fragment