Add shared PetaLinux PL bit and PS app deployment skills

petalinux-pl/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: petalinux-pl
+description: Convert a current Vivado PL .bit into a Zynq FPGA-manager-loadable .bin, deliver it to a PetaLinux board, optionally program PL at runtime, and verify or recover the result. Use for PR26 PL bit-to-bin and hardware deployment, not for QSPI BOOT.BIN or Linux application deployment.
+---
+
+# Petalinux-pl：PL bit→bin 与板端发布
+
+目标是把**当前 Vivado 交付**的 PL bit 转成板端可用的 bin、放到实际消费者的位置，并按请求完成运行时 FPGA 加载与硬件验收。PR26 的两个路径代表不同接口：`/aw/fpgabin/fpga_atsc3` 是历史应用管理的文件位置；`/lib/firmware/<name>` 加 `/sys/class/fpga_manager/fpga0/firmware` 是 Linux FPGA manager 加载路径。**复制成功不等于 PL 已配置。**本 skill 不重打包 QSPI `BOOT.BIN`，不部署 PS/Linux 应用；若用户明确要求上电时由 BootROM/FSBL 加载 bit，先审阅 `petalinux-qspi`/`petalinux-emmc` 的 BOOT 组成与回退，而不是悄悄改启动链。
+
+## 输入与板卡门禁
+
+从用户请求、项目 bmem/PR26 和现场枚举确定板卡/PCB 版本；未指明时先取得板卡身份。HJX9009、emv9.3、ipots、其他板不能共用器件号、bit/HDF 或加载接口。取得本轮 `.bit`、相配 HDF/XSA、Vivado/Bootgen 版本、目标 Linux/kernel/DT、当前 PL 与 FPGA manager 状态、已知良好 bit/bin 和恢复路径。记录 SHA-256、大小、构建标识，确认 bit 的器件/接口与目标板匹配；当前 bit 不应只凭文件名或 mtime 推定。若 PL 新增/移动了 PS 可见 IP、时钟或中断，还要审阅目标 Linux 设备树/驱动兼容性；bin 可加载不等于系统能正确使用新 PL。
+
+HJX9009 的 `Petalinux/delivery/pr26_tf_20260915/MANIFEST.md` 仅证明 FPGA manager 节点存在，**没有**证明 PL bit 发布或 DPD 应用运行通过。`E:\tmp\bit2bin_fpga` 的 BIF/批处理以及 `E:\tmp\qspi-emmc\tftp_dir_emmc` 只作语法/资产参考：它们对应历史 bit，脚本写死旧路径并删除输出/日志，不得直接拿它们当当前交付执行。PR26/Notion 中的 IP、bit 名称和 `/aw` 路径也需现场验证。
+
+## 转换与复用
+
+在隔离的工作目录复制**唯一当前 bit**并核对副本哈希，为副本生成只含该 bit 的 BIF（`all: { <current-bit-copy> }`），确保 Bootgen 不会在源码/历史交付目录旁意外覆盖同名输出。使用与目标硬件版本匹配的 Bootgen。Zynq-7000 的历史/官方接口是 `bootgen -image <BIF> -arch zynq -process_bitstream bin`；`-arch` 必须按板卡实际 SoC 选择，不能把 HJX9009 命令套到 ZynqMP/其他器件。保存 BIF、完整 stdout/stderr、退出码、工具版本、输入 bit/HDF SHA-256、输出 `.bit.bin` 的实际名称/大小/SHA-256；命令失败或输出为空立即停止。`.bin` 是处理过的配置数据，大小/哈希不要求与带头部的 `.bit` 相同。不要用旧批处理的 `del *.log`、`del fpga` 或静默重命名覆盖结果。
+
+若已有 bin，只有 bit/HDF、板卡 profile、转换选项/工具版本和输出 SHA-256 均与冻结 manifest 一致时可跳过转换；仍要重做本轮目标板传输、加载和验收。输出可在 TFTP 根目录以 `name.bit.bin` 发布，应用管理要求的最终名称另行确定，不用历史 `fpga_atsc3` 名称冒充最新设计。
+
+## 板端交付、加载与验收
+
+1. 现场确认 Windows/VM/TFTP 绑定、板端 IP 与根文件系统来源。若根是 QSPI initramfs，复制到 `/lib/firmware` 或 `/aw` 只存在于 RAM，不能报告“断电后持久”；需要持久部署时先走正式 TF/eMMC 根文件系统。用实际 TFTP 下载到**独立暂存文件**，检查返回值、字节数和两端 SHA-256；任何传输失败停止，不允许用旧同名文件继续。
+2. 按已验证消费者选择目标。应用管理模式先查 `/aw/fpgabin` 的挂载、启动脚本和实际文件读取合同；保存旧文件，在同一文件系统内校验暂存 bin、原子替换、按最低必要权限（数据文件通常 `0644`）设置并 `sync`，再证明消费者读取新哈希。直接 FPGA manager 模式先确认 `/sys/class/fpga_manager/fpga0`、`/lib/firmware` 和固件文件查找规则；以同样的备份/校验/替换发布到已确认的 firmware 目录，然后执行 `echo <actual-basename> > /sys/class/fpga_manager/fpga0/firmware`，逐条检查写入结果、`state`/内核日志以及板上 PL 标识寄存器或功能探针。不要因为历史示例 `chmod 777` 或 `sync` 两次就省略这些验证。
+3. 运行时重配置前辨认依赖 PL 的 Linux 服务/驱动，按目标应用的已知停止/恢复合同协调；需要停止应用时可用 `petalinux-ps`，但不得顺带终止无关服务。若新 bin 加载/功能探针失败，保留日志并用已知良好 bin、JTAG/冷启动路径恢复；只恢复磁盘文件不会自动恢复当前 FPGA 内容。
+4. 若要求上电自动加载，另核对启动脚本/设备树与 bin 名称，至少两次完整断电启动证明实际加载和功能，不以一次 sysfs 写入代替持久启动验收。仅请求“发布文件”时状态记为 `FILE_DEPLOYED`，不能记 `PL_ACTIVE_PASS`。
+
+在项目 `Notes/auto/` 保存自动日志/manifest：bit/HDF/bin 哈希、Bootgen/BIF、板号、实际网络、目标路径、加载方式、旧版备份、FPGA manager/寄存器/功能证据和回退结果。按项目 bmem 协议沉淀会话与持久结论并同步；不得把账号口令写进 skill、TFTP 文件或日志。
+
+依据：项目 `Notes/PR26.md`、[Notion 历史两步法](https://app.notion.com/p/a16f43e721f08223a8b4811f36b10ac1)；AMD [Bootgen `-process_bitstream`](https://docs.amd.com/r/2022.1-English/ug1283-bootgen-user-guide/process_bitstream) 和 [FPGA Manager 用法](https://docs.amd.com/r/2020.2-English/ug1144-petalinux-tools-reference-guide/FPGA-Manager-Configuration-and-Usage-for-Zynq-7000-Devices-and-Zynq-UltraScale-MPSoC)。文档版本仅作语义依据，目标工具/内核仍以实测版本为准。

petalinux-ps/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: petalinux-ps
+description: Deliver or stop a compiled Linux user-space application on a PetaLinux Zynq board, verifying its ARM ABI, target process identity, persistent storage, launch contract, health, and rollback. Use for PR26 PS application deployment or a scoped zq_server stop; not for bare-metal PS firmware, QSPI images, or PL bitstreams.
+---
+
+# Petalinux-ps：Linux 应用发布与定向停止
+
+本 skill 的“PS”是**运行于 PetaLinux 的用户态应用**，不是 SDK 裸机 `s1app.elf`/FSBL，也不负责 PL bit、QSPI 或 TF/eMMC 系统镜像。用户给出已编译程序时直接做 ABI、传输、发布和板端验收；若只要求停止应用，执行定向停止与确认，不擅自替换文件或重启。PR26 的 `killall zq_server` 是一个历史例子，**进程名不等于 ELF 文件名或服务名**，不能在未识别目标前照搬。
+
+## 识别当前交付
+
+从项目 bmem、PR26、现板进程/启动配置确定板卡、Linux 版本、rootfs 挂载、目标应用的绝对路径和当前版本。要求本轮编译好的二进制及 SHA-256/构建来源、预期 ARM 架构/EABI、动态解释器/共享库、命令行参数、环境变量、工作目录、配置文件、端口、依赖 PL/外设、服务管理方式和开机自启动合同。可用 `readelf`/等价工具检查 ELF class、endianness、machine、ABI/interpreter/NEEDED，并在目标系统核对实际 loader/库；**ARM ELF magic 单独不证明可在这版 PetaLinux 运行**。缺少启动合同先通过现板 `/proc/<pid>/cmdline`、进程树、SysV/systemd 脚本和日志取证；无法识别时只可安全暂存，不得猜测启动参数。
+
+`E:\tmp\qspi-emmc\tftp_dir_emmc` 含旧 `zq_cttb_server_cttb`、`zq_cttb_server_dvbt`、`zq_dvbt_server.elf` 样本；本机读到它们是 32-bit little-endian ARM ELF，但**未**证明属于当前 Vivado/TF 根系统，也未证明对应进程名 `zq_server`。不能以旧样本、旧 IP 或文件名相似替代用户当前交付。HJX9009 的 `pr26_tf_20260915` 交付只证明 Linux/网络/SSH/TF 持久根可启动；PR26 的 PS 应用尚无本板实测 PASS 记录。
+
+## 仅停止目标应用
+
+先核对 PID、完整 cmdline、exe inode/路径、所属服务和实例数量。优先按已知服务合同停止；无服务管理器时向**确认为目标应用的 PID** 发送 TERM、等待退出并检查端口/子进程。只有在请求范围内仍未退出时才考虑 KILL，记录实际 PID 和结果。`killall zq_server` 仅在全部同名实例均属于用户指定目标、且服务不会自动拉起时可作为等价方式；不能用其误杀其它实例。确认停止不等于程序文件已删除或开机启动已禁用，分别报告。
+
+## 发布与切换门禁
+
+1. 只读基线：确认目标 rootfs 是持久介质（如 HJX9009 已验证的 TF ext4），记录挂载、空闲容量、旧二进制/配置/服务哈希和现有进程状态；QSPI initramfs 中暂存的应用断电即消失，不能叫持久部署。现场验证 TFTP 服务地址和目标通信，拒绝 PR26/旧目录的固定 IP。
+2. 先把**全部**当前文件传到独立暂存目录，逐项核对下载退出码、大小、SHA-256、ABI 与依赖；若任一缺失或校验失败立即停止，旧运行版本继续保留。目标安装路径应从真实 service/应用合同取得，不默认 `/aw`；检查意外 symlink、权限和空间。若当前板上二进制哈希与交付完全相同，可跳过替换但仍做健康与持久启动验收。
+3. 冻结旧版可恢复副本和启动合同。按上节精确停止目标进程，等待退出，再把已校验新文件在**同一文件系统**内原子替换到目标，设置最低必要可执行权限（通常 `0755`）、`sync` 并读回哈希。不要先删旧文件，不能因 TFTP 失败把旧暂存 ELF 发布为新版本。
+4. 使用确认过的服务/命令行启动，不猜参数或以后台 PID 存在判成功。核对 `/proc/<pid>/exe` 是否指向新 inode、依赖库/日志/端口/健康响应以及应用自己的功能探针；如涉及 PL，核对 bit/寄存器版本与应用兼容。失败时定向停新版、恢复旧二进制/配置并按旧合同重启，保留失败证据。若用户要求断电保持或自启动，至少两次完整断电启动验收，证明持久根、启动服务和功能都仍正确。
+
+自动日志放项目 `Notes/auto/`：目标板/rootfs、来源与目标 SHA-256、ABI/库、实际网络、进程 PID/exe/命令行、旧版备份、安装/停止/重启/功能/断电门禁与回退结果。密码不得进入文件或回显；按项目 bmem 协议记录会话并同步。只有文件哈希、进程身份、健康及用户请求的重启持久化门禁全部 PASS，才报告 `APP_DEPLOYED_PASS`；单独停止请求只能报告 `APP_STOPPED_PASS`。