HLS-QCNN 板端运行命令说明
========================

一、先说明清楚：板端不运行 HLS
----------------------------

HLS、Vivado 都是在电脑上运行的工具，用来生成硬件文件：

  hls_qcnn.bit
  hls_qcnn.hwh

PYNQ-Z2 板端只运行 Python 脚本，加载 bit/hwh，然后调用 FPGA 推理。

板端需要的文件是：

  hls_qcnn.bit
  hls_qcnn.hwh
  hls_qcnn_weights_flat.npy
  hls_qcnn_inference.py
  test_images/

其中 test_images 是验证图片目录，结构应该是：

  test_images/class_0/*.jpg
  test_images/class_1/*.jpg
  ...
  test_images/class_9/*.jpg


二、SSH 登录板子
---------------

在电脑 CMD 或 PowerShell 中执行：

  ssh xilinx@板子IP

例如：

  ssh xilinx@192.168.1.3

默认账号密码：

  用户名：xilinx
  密码：xilinx


三、进入工作目录并检查文件
------------------------

登录板子后执行：

  cd /home/xilinx/hls_qcnn_test
  ls

应该能看到：

  hls_qcnn.bit
  hls_qcnn.hwh
  hls_qcnn_weights_flat.npy
  hls_qcnn_inference.py
  test_images

如果缺文件，需要先从电脑上传。


四、最重要：运行脚本必须带参数
----------------------------

不要直接运行：

  python3 hls_qcnn_inference.py

这样会报错：

  error: the following arguments are required: --bitstream, --weights

正确运行时必须带：

  --bitstream hls_qcnn.bit
  --weights hls_qcnn_weights_flat.npy


五、单张图片测试命令
------------------

在板端执行：

  cd /home/xilinx/hls_qcnn_test

然后执行：

  echo xilinx | sudo -S env XILINX_XRT=/usr PYTHONPATH=/home/xilinx python3 hls_qcnn_inference.py --bitstream hls_qcnn.bit --weights hls_qcnn_weights_flat.npy --image test_images/class_0/10.jpg

也可以写成多行，方便看：

  echo xilinx | sudo -S env XILINX_XRT=/usr PYTHONPATH=/home/xilinx \
  python3 hls_qcnn_inference.py \
  --bitstream hls_qcnn.bit \
  --weights hls_qcnn_weights_flat.npy \
  --image test_images/class_0/10.jpg

正常情况下会输出：

  predicted class: 0
  logits: [...]
  inference time: xxxx ms

当前 class_0/10.jpg 的参考 logits 是：

  [8262, 7193, 1266, -4729, -6985, -7235, -7197, -2445, -1752, -1996]


六、100 张验证集测试命令
---------------------

在板端执行：

  cd /home/xilinx/hls_qcnn_test

然后执行：

  echo xilinx | sudo -S env XILINX_XRT=/usr PYTHONPATH=/home/xilinx python3 hls_qcnn_inference.py --bitstream hls_qcnn.bit --weights hls_qcnn_weights_flat.npy --test_dir test_images

多行版本：

  echo xilinx | sudo -S env XILINX_XRT=/usr PYTHONPATH=/home/xilinx \
  python3 hls_qcnn_inference.py \
  --bitstream hls_qcnn.bit \
  --weights hls_qcnn_weights_flat.npy \
  --test_dir test_images

当前正式测试结果是：

  accuracy: 79.00% (79/100)
  average time: 约 18797 ms
  fps: 0.05

注意：这一版一张图大约 18.8 秒，100 张大约需要半小时。


七、三次重复实验命令
------------------

如果要连续跑三次 100 张测试，在板端创建脚本：

  cd /home/xilinx/hls_qcnn_test

  cat > run100x3.sh <<'EOF'
  #!/bin/bash
  set -u
  cd /home/xilinx/hls_qcnn_test || exit 1
  : > run100_summary.txt
  for i in 1 2 3; do
    printf '===== run %s start %s =====\n' "$i" "$(date '+%F %T')" | tee -a run100_summary.txt
    echo xilinx | sudo -S env XILINX_XRT=/usr PYTHONPATH=/home/xilinx python3 hls_qcnn_inference.py --bitstream hls_qcnn.bit --weights hls_qcnn_weights_flat.npy --test_dir test_images > "run100_${i}.log" 2>&1
    rc=$?
    printf '===== run %s end %s rc=%s =====\n' "$i" "$(date '+%F %T')" "$rc" | tee -a run100_summary.txt
    tail -n 20 "run100_${i}.log" | tee -a run100_summary.txt
    printf '\n' | tee -a run100_summary.txt
    if [ "$rc" -ne 0 ]; then
      exit "$rc"
    fi
  done
  EOF

  chmod +x run100x3.sh
  ./run100x3.sh

后台运行版本：

  nohup ./run100x3.sh > run100_job.log 2>&1 &

查看进度：

  ps aux | grep hls_qcnn_inference.py | grep -v grep
  tail -n 80 run100_summary.txt
  ls -lh run100_*.log run100_summary.txt


八、常见 warning 和错误
---------------------

1. xbutil failed to run

如果看到：

  /home/xilinx/pynq/pl_server/xrt_device.py:88: UserWarning: xbutil failed to run - unable to determine XRT version

这通常只是 warning，可以先忽略。只要后面 Overlay 能加载、脚本能继续运行即可。


2. 缺少 --bitstream 和 --weights

如果看到：

  error: the following arguments are required: --bitstream, --weights

说明你直接运行了：

  python3 hls_qcnn_inference.py

正确命令必须带：

  --bitstream hls_qcnn.bit --weights hls_qcnn_weights_flat.npy


3. 找不到 pynq 包或 Overlay 加载失败

请使用这个完整运行前缀：

  echo xilinx | sudo -S env XILINX_XRT=/usr PYTHONPATH=/home/xilinx python3 ...

原因：

  sudo：加载 overlay 需要 root 权限
  XILINX_XRT=/usr：PYNQ v2.7 环境需要
  PYTHONPATH=/home/xilinx：有些 PYNQ 镜像需要这个路径才能找到 pynq 包


4. 找不到图片

检查 test_images 目录：

  find test_images -type f | wc -l

正式 100 张验证应该输出：

  100


九、电脑端和板端分工
------------------

电脑端做：

  Vitis HLS
  Vivado
  生成 hls_qcnn.bit / hls_qcnn.hwh

PYNQ-Z2 板端做：

  python3 hls_qcnn_inference.py
  加载 hls_qcnn.bit / hls_qcnn.hwh
  读取 hls_qcnn_weights_flat.npy
  对 test_images 里的图片做 FPGA 推理

所以：板端不需要打开 HLS，也不需要打开 Vivado。

