Files
Palladium_Z2-ice_top-demo/README.md
T

190 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Cadence Palladium Z2 硬件仿真 Demo:可编程定时器外设(SA & ICE 双模式)
本仓库提供了一个可在 **Cadence Palladium Z2** 硬件仿真器上真正跑通的完整工程 Demo。设计以一个带 APB 风格寄存器总线的定时器外设(DUT)为核心,完整演示了 Palladium Z2 在 **SA(Simulation Acceleration,仿真加速)** 与 **ICE(In-Circuit Emulation,在线硬件仿真)** 两种核心工作模式下的编译、下载、时序驱动与调试全流程。
---
## 1. 这个 Demo 可以干什么?
本 Demo 主要用于团队内 **熟悉 Palladium Z2 流程、上机环境验证、自动化回归脚本基线以及 SA/ICE 选型对比**。
### 1.1 DUT 核心功能
DUT 是一个完整可综合的定时器外设,具备丰富的可观察行为:
- **总线读写**:标准的 APB 风格总线接口(`paddr`, `pwdata`, `prdata`, `pwrite`, `psel`, `penable`,单拍快速响应);
- **倒计数定时器**:由使能位控制,从 `LOAD` 预置值逐拍递减到 0;
- **比较器与中断**:计数器匹配到 `CMP` 时产生单拍 `cmp_hit` 脉冲;计数递减到 0 触发中断 `irq` 并自动重载;
- **状态标志与 W1C**:超时标志与比较标志支持写 1 清零(Write-1-to-Clear);
- **动态跑马灯(GPIO 旋转)**:开启图案使能后,每次超时中断会自动将 8 位图案寄存器向左循环移位一次——在波形或引脚上呈现出跑马灯效果,用于最直观判断硬件是否真正走时;
- **身份标识寄存器**:固定只读值 `0x5A32_0001`,用于验证总线通路完整性。
### 1.2 寄存器映射表(Base: 8-bit offset)
| 偏移地址 | 寄存器名称 | 读写属性 | 复位默认值 | 详细说明 |
|:---:|:---:|:---:|:---:|:---|
| `0x00` | **CTRL** | RW | `0x0000_0000` | `[0]` 计数使能 (`enable`)<br>`[1]` 中断使能 (`irq_en`)<br>`[2]` 跑马灯使能 (`pattern_en`) |
| `0x04` | **LOAD** | RW | `0x0000_0009` | 计数器重载值;写入该寄存器会同时同步预置当前计数器 |
| `0x08` | **COUNT** | RO | `0x0000_0009` | 实时当前倒计数值 |
| `0x0C` | **CMP** | RW | `0x0000_0003` | 比较匹配值(当 `COUNT == CMP` 时置标志) |
| `0x10` | **STATUS** | W1C | `0x0000_0000` | `[0]` 超时中断标志位 (`timeout`)<br>`[1]` 比较匹配标志位 (`cmp`),写 1 清除 |
| `0x14` | **GPIO** | RW | `0x0000_0001` | 8 位输出图案寄存器,每次超时左移一位 |
| `0x18` | **ID** | RO | `0x5A32_0001` | 外设硬件版本特征常量,用于快速确认通信通路 |
---
## 2. SA 模式 vs ICE 模式深度对比
本工程最大的特点是**同一份 DUT 代码,实现 SA 与 ICE 双模式跑通**:
```
[同一份硬件设计 DUT: z2_demo_top.v]
│
┌─────────────────────────┴─────────────────────────┐
▼ ▼
【SA 模式 (仿真加速)】 【ICE 模式 (硬件在线仿真)】
┌──────────────────────┐ ┌─────────────────────────────────┐
│ Host 侧 (Xcelium) │ │ Palladium 硬件内部 │
│ tb_z2_demo.v │ │ ┌─────────────────────────────┐ │
│ (时钟/复位/激励) │ │ │ 内置硬件自检 FSM (激励/检查)│ │
└──────────┬───────────┘ │ └──────────────┬──────────────┘ │
│ (InfiniBand 协同通信) │ (纯硬件内部总线互联) │
▼ ▼ │
┌──────────────────────┐ │ ┌─────────────────────────────┐ │
│ Palladium 硬件 │ │ │ z2_demo_top (DUT) │ │
│ z2_demo_top (DUT) │ │ └──────────────┬──────────────┘ │
└──────────────────────┘ │ │ 引脚输出 │
│ led_pass / led_fail / led_gpio │
└─────────────────────────────────┘
```
| 维度对比 | SA 模式(Simulation Acceleration) | ICE 模式(In-Circuit Emulation) |
|:---|:---|:---|
| **代码位置** | 根目录(`rtl/`、`tb/`、`scripts/`) | `ice/` 目录(`ice/rtl/`、`ice/scripts/`) |
| **Testbench 归属** | 留在 Host 工作站(Xcelium 仿真器),为软件 TB | **没有软件 TB**,激励是硬件化的可综合 FSM,与 DUT 一同烧入硬件 |
| **时钟与复位** | TB 内部由软件时钟驱动(`always #5 clk = ~clk`) | 依赖机台时钟/外部 Target/脚本强制注入激励 |
| **编译命令** | `ixcom -ua +dut+z2_demo_top -f rtl.f -f tb.f` | `ixcom -clean -ua +dut+z2_demo_ice_top ...` (触发 xeCompile) |
| **测试结果读取** | 在 `xeDebug.log` / 终端中打印 `CHECK OK / TEST PASSED` | 读取顶层引脚信号:`led_pass=1`, `led_fail=0`, `led_gpio=0x02` |
| **适用工程场景** | 复杂软件驱动、UVM 测试平台、调试验证逻辑功能 | 接真实 Target 板、芯片全系统上电、长时运行跑马灯或操作系统引导 |
---
## 3. 工程代码结构
```text
palladium_z2_demo/
├── .gitignore # 过滤所有 Palladium/Xcelium 编译数据库与波形文件
├── README.md # 本说明文档
├── README_中文教程.md # SA 模式中文教程
├── README_ICE对比_中文教程.md # ICE 模式对比教程
├── rtl.f / tb.f # SA 模式文件列表清单
│
├── rtl/ # 【DUT 源码】
│ └── z2_demo_top.v # 定时器外设 RTL
├── tb/ # 【SA 模式 Testbench】
│ └── tb_z2_demo.v # 软件 TB(发 APB 读写、等中断、自动判读)
├── scripts/ # 【SA 模式脚本】
│ ├── env_z2.sh # 环境变量模板(XE_HOST, XE_BOARDS)
│ ├── compile_sa.sh # SA 模式 IXCOM 编译脚本
│ ├── run_xedebug.tcl # SA 模式运行脚本(xc on -run)
│ └── run_local.sh # SA 本地免硬件验证(iverilog/xrun)
│
└── ice/ # 【ICE 模式专区】
├── rtl/
│ ├── z2_demo_top.v # DUT 副本(与根目录逐字节相同)
│ └── z2_demo_ice_top.v # ICE 顶层(集成硬件自检 FSM + 判读 LED)
├── tb/
│ └── tb_z2_demo_ice.v # 本地离线验证 ICE FSM 的脚手架
├── scripts/
│ ├── compile_ice.sh # ★ ICE 模式 Palladium 硬件编译主脚本(已调通)
│ ├── run_xedebug_ice.tcl # ★ ICE 模式 Palladium 上机下载与测试判读脚本(已调通)
│ └── run_local_ice.sh # ICE 本地离线功能验证脚本
└── sim_local/
└── ice_run.log # 本地验证参考通过日志
```
---
## 4. ICE 模式上机全操作指南(已实测跑通)
### 4.1 步骤 1:本地免硬件离线验证(可选)
在没有分配到 Emulator 硬件时,可先离线验证硬件自检状态机逻辑:
```bash
./ice/scripts/run_local_ice.sh
```
*预期输出:`== ICE LOCAL RUN: PASS ==`,日志保存在 `ice/sim_local/ice_run.log`。*
### 4.2 步骤 2:Palladium 硬件全编译
指定目标机台的主机名和板卡编号,执行一键编译脚本:
```bash
XE_HOST=scz2_emu XE_BOARDS=18.0 ./ice/scripts/compile_ice.sh
```
*底层机制:脚本会自动调用 `ixcom -clean -ua +dut+z2_demo_ice_top`,拉起 AVS 与 `xeCompile` 进行芯片级映射,编译成功将显示 `Successfully built target (xeCompile)` 并生成 `AxisWork` 与 `xc_work` 硬件数据库。*
### 4.3 步骤 3:上机下载与测试
在工程根目录下启动 `xeDebug` 并加载执行脚本:
```bash
xeDebug -f ice/scripts/run_xedebug_ice.tcl
```
*(也可以启动交互模式 `xeDebug`,在 `XE>` 提示符下执行 `source ice/scripts/run_xedebug_ice.tcl`)*
#### 运行流程自动化说明:
1. **`debug .`**:绑定当前工程的硬件特征签名;
2. **`host scz2_emu`**:建立到 Emulator 的 InfiniBand 高速链路并载入数据库;
3. **`xc on` / `download`**:将综合网表下载烧入物理机台;
4. **复位释放序列**:通过 `force z2_demo_ice_top.rst_n_in 0` $\to$ `run 20` $\to$ `force 1` 注入上电复位;
5. **运行时钟推进**:执行 `run 1000` 时钟周期,内置激励 FSM 会自动执行寄存器配置、中断比对、跑马灯移位验证并锁定状态;
6. **自动读取结果并判定**:
```text
=======================================================
Palladium Z2 ICE 运行测试结果
=======================================================
led_done : 1 (测试序列是否完成,预期: 1)
led_pass : 1 (全硬件检查是否通过,预期: 1)
led_fail : 0 (是否有硬件检查失败,预期: 0)
led_gpio : 0x02 (跑马灯寄存器旋转值,预期: 0x02)
-------------------------------------------------------
>>> [SUCCESS] ICE DEMO 全部硬件自检测试通过! <<<
=======================================================
```
---
## 5. SA 模式上机简要指南
1. **设置环境变量**:
```bash
. ./scripts/env_z2.sh # 填入 XE_HOST, XE_BOARDS
```
2. **IXCOM 协同编译**:
```bash
./scripts/compile_sa.sh # 产物生成在 ixcom_db/
```
3. **运行协同仿真**:
```bash
cd ixcom_db
xeDebug -f ../scripts/run_xedebug.tcl
```
4. **查验日志**:
```bash
grep -n "TEST PASSED" xeDebug.log
```
---
## 6. 核心排障与踩坑经验总结
在本次 Demo 的调通调试中,总结了以下 4 个关键工程经验,供后续项目参考:
1. **纯硬件编译必须声明 DUT 边界**:
- *问题现象*:仅传 `ixcom +top+z2_demo_ice_top`,编译虽然显示 SUCCESS 但只跑了 `nc elaborate`,运行 `xeDebug` 报 `no signature`,且找不到硬件数据库文件。
- *解决原因*:IXCOM 必须带 `-ua +dut+<top>` 才会调用 AVS/xeCompile 生成真实的硬件比特流和特征签名。
2. **`xeDebug` 下 `host` 命令的前置依赖**:
- *问题现象*:直接输入 `host scz2_emu` 报错 `the 'host' command is available only after debug command`。
- *解决原因*:在你的工具版本中,必须先执行 `debug .` 载入本地工程的特征签名上下文,然后才能调用 `host` 连入 Emulator 物理机。
3. **编译参数与脚本语法隔离**:
- *问题现象*:命令行乱传 `-qel` 报 `Illegal option`;或在 Tcl 大括号内加双引号导致底层当作带引号文件名寻找失败。
- *解决原因*:IXCOM 原生通过环境变量接收机台与板卡资源;Tcl 脚本中路径统一使用绝对路径 `$ROOT/...` 并且无需加内部引号。
4. **ICE 模式的时钟与复位注入**:
- *问题现象*:ICE 模式没有软件 Testbench 产生时钟或释放复位。
- *解决原因*:在无真实物理板卡输入时,可通过 `xeDebug` 脚本在下载后通过 `force rst_n_in 0` $\to$ `run` $\to$ `force rst_n_in 1` 注入上电脉冲,确保状态机正常跳出复位进入执行态。