petalinux-emmc: gate SDK Linux driver integration

petalinux-emmc/SKILL.md

@@ -19,6 +19,14 @@ description: Build, reuse, deploy, recover, and hardware-validate a PetaLinux pr
 
 ## 构建和复用
 
+### 与 SDK→Linux 应用迁移配套的驱动门禁
+
+若正式 TF/eMMC 系统要运行从 SDK 裸机工程移植的 PS 应用，E1 构建前逐项核对该应用所依赖的 PL AXI MMIO、PS/EMIO GPIO、SPI、ADRV9009/Talise、DMA/中断及物理 DDR 邮箱。对照**当前** bit/HDF、目标 DT、`/proc/iomem`、`/dev`、内核 config/模块和应用 ABI，列出已由 Linux 提供的接口与缺失接口。缺失驱动、DT 节点、模块自动加载、固件或用户态 HAL 时，应把源码和 recipe 放入正式 PetaLinux 工程，在 kernel、DT、rootfs 与 FIT 同源构建并纳入 `build_inputs.json`/哈希门禁；不能只在运行板上临时 `modprobe`、`mknod` 或用旧交付 FIT 冒充完成。
+
+尤其不能沿用 SDK 的固定 DDR 地址而直接写 `/dev/mem`：先证明目标范围在 DT `reserved-memory` 中保留，且不与 Linux `System RAM`、kernel code/data、CMA、rootfs 或 DMA buffer 冲突。HJX9009 旧 SDK `0x00400100` 邮箱在 2026-09-16 当前 Linux `/proc/iomem` 中属于 kernel code 范围、DT 无 `reserved-memory`；迁移应用必须停止使用该地址，改为受管理的 IPC/驱动接口或重新协商并保留安全的物理范围。当前板上已有 `/dev/spidev1.0` 和 root 可用的 `/dev/mem`，但这不证明 AD9528/ADRV9009 初始化、JESD 或自动 DPD 控制已移植。若新增 UIO/专用驱动，按新 HDF 确认 `reg` 大小、时钟、复位与中断，加入模块及启动加载规则，并以真实板端探针和功能测试验收。
+
+任何上述改动都会改变正式系统输入，须重做相应 G1–G3 和 E1–E4；旧的 QSPI 救援 FIT 与分区边界不得因应用驱动升级而被无条件覆写。
+
 采用独立正式工程。保持 `boot media = QSPI`、`BOOT.BIN = 同一硬件交付的 FSBL + U-Boot`，正式 `image.ub` 在经验证的 eMMC/TF BOOT 分区，根文件系统在第二分区 ext4；实际 FIT/启动路径必须与板卡检测条件相容。需要早期桥接 initramfs、软件 CD 旁路或根 UUID 时，把源文件、DT、U-Boot overlay、rootfs 配置和启动参数都算作构建输入，不得仅改环境后仍声称镜像相同。`BOOT.BIN` 不自动包含 PL bit 或 FIT。QSPI kernel 分区中的过渡 `image.ub.qspi` 保持可恢复。
 
 先为当前输入生成 `build_inputs.json`，可用 sibling `petalinux-qspi/scripts/qspi_cache.py capture` 的通用指纹捕获接口；HJX9009 使用稳定的 [references/hjx9009-profile.json](references/hjx9009-profile.json) 作 profile 文件。指纹包含 HDF/bit、所有 config/recipe/DT/U-Boot/桥接源、工具版本、BOOT 组成与根文件系统方案；部署时变化的 IP/密码不进指纹。再用 [scripts/emmc_cache.py](scripts/emmc_cache.py) 检查当前指纹与交付的 `BOOT.BIN`、`image.ub`、`rootfs.tar.bz2`、`build_inputs.json`、`summary.json`、`MANIFEST.md` 和 `SHA256SUMS`。构建门禁 G0=输入、G1=HDF 导入、G2=配置、G3=构建打包；仅在检查返回 `reusable=true`、G0–G3 均 PASS、产物与当前硬件输入/启动方案一致时跳过重建。文件存在、mtime、旧 bit 相同或仅有一次启动日志均不足；旧交付缺可核验指纹/清单时补齐证据或重建。复用构建**不能**跳过当前介质和板级部署验收。