# Cadence Palladium Z3 硬件仿真 Demo:定时器外设(SA & ICE 双模式)
本仓库提供了一个可在 **Cadence Palladium Z3** 硬件仿真器上真正跑通的完整工程 Demo。设计以一个带 APB 风格总线的定时器外设(DUT)为核心,完整演示了 Palladium Z3 在 **SA(Simulation Acceleration,仿真加速)** 与 **ICE(In-Circuit Emulation,在线硬件仿真)** 两种核心工作模式下的编译、下载、时序驱动与调试全流程。
> 📘 **特别推荐**:针对 **WXE24.05.000 / IXCOM24.05.000** 版本下出现的 `ASSERT_RESET` 缺失、`HDLICE_HOME` 未设、`xeCompile -z3` 识别异常、`ver2hdl` 找不到以及 Z3 硬件配置文件冲突等系列疑难杂症,请查阅完整复盘方案:
> 👉 **[docs/PALLADIUM_Z3_24.05_SOLUTION.md](docs/PALLADIUM_Z3_24.05_SOLUTION.md)**
---
## 1. Palladium Z3 与 Z2 的关键区别与避坑指南
### 1.1 软件版本与底层动态库架构
- **Z2 架构**:工具链多基于早期的 VXE/WXE 版本,底层依赖位于 `tools.lnx86/lib/z2/64bit/`。
- **Z3 架构**:必须使用 25H1/WXE25.08+(例如 `WXE25.08.s003`),其针对 Z3 的底层通信与数据库核心库位于:
```bash
$WXE_HOME/tools.lnx86/lib/z3/64bit/
```
### 1.2 避坑:解决 `Cannot find 'et3lib' library in DBIN path`
在 Palladium Z3 上运行 `test_server` 或启动编译调试时,若仅按 Z2 配置,常会遇到以下严重报错:
```text
40 DATABASE | Cannot find 'et3lib' library in DBIN path
Critical Error: Severe error in db2, TERMINATING PROCESS.
Possible reasons - the configmgr is not running or has an incorrect IP address.
- wrong version of test_server. WXE sw is Palladium Z2 compatible only.
Error: BEDB SEVERE ERROR
```
**原因与解决方案**:
1. **动态库路径缺失**:系统动态链接器和后端数据库(DB2/BEDB)在 `DBIN` 路径下未找到 `et3lib`。
在环境变量中必须加入:
```bash
export LD_LIBRARY_PATH=/home/software/WXE25.08.s003/tools.lnx86/lib/z3/64bit:$LD_LIBRARY_PATH
export DBIN=/home/software/WXE25.08.s003/tools.lnx86/lib/z3/64bit:$DBIN
```
2. **硬件代际声明**:明确设置环境变量声明当前目标机型为 Z3:
```bash
export XE_TARGET="z3"
export PALLADIUM_TARGET="z3"
export CDS_PALLADIUM_SERIES="z3"
```
3. **后台管理进程 `configmgr`**:`test_server` 依赖后台的 Config Manager 进程,需确认 `configmgr` 监听正常且与机箱管理网口通信正常。
> 本工程提供了一键自检脚本 `scripts/check_z3_server.sh`,可全自动排查上述问题!
---
## 2. 工程目录结构
```text
palladium_z3_demo/
├── .gitignore # 过滤编译与仿真生成的中间库
├── README.md # 本说明文档
├── rtl.f / tb.f # SA 模式文件列表清单
│
├── rtl/ # 【DUT 硬件源码】
│ └── z3_demo_top.v # 定时器外设 RTL (ID: 0x5A33_0001)
├── tb/ # 【SA 模式 Testbench】
│ └── tb_z3_demo.v # 宿主机端软件 TB (APB 激励、中断等待与判读)
├── scripts/ # 【工程与上机脚本】
│ ├── env_z3.sh # ★ 核心环境配置文件 (集成 Z3 动态库与 DBIN)
│ ├── check_z3_server.sh # ★ test_server / configmgr 连通性一键体检脚本
│ ├── compile_sa.sh # SA 模式 IXCOM 硬件加速编译脚本
│ ├── run_xedebug.tcl # SA 模式 xeDebug 上机加载与运行脚本
│ └── run_local.sh # SA 本地免硬件验证脚本 (iverilog/xrun)
│
└── ice/ # 【ICE 全硬件仿真模式】
├── rtl/
│ ├── z3_demo_top.v # DUT 副本
│ └── z3_demo_ice_top.v # ICE 顶层 (集成硬件自检 FSM 与状态 LED 输出)
├── tb/
│ └── tb_z3_demo_ice.v # 本地验证 ICE 自检状态机的仿真测试平台
└── scripts/
├── compile_ice.sh # ★ ICE 模式硬件全逻辑编译脚本
├── run_xedebug_ice.tcl # ★ ICE 模式上机下载与状态读取判断脚本
└── run_local_ice.sh # ICE 本地离线免硬件验证脚本
```
---
## 3. 硬件 DUT 规格(z3_demo_top)
DUT 是一个可综合的标准 APB 从设备,具备丰富的交互特性:
- **基地址偏移 8 位**;
- **只读特征码**:`0x18` 偏移处的 ID 寄存器为 `0x5A33_0001`(Z3 专属 Signature);
- **倒计数器与重载**:`CTRL[0]` 使能计数,从 `LOAD`(`0x04`)递减至 0 并自动重载;
- **中断与比较**:`COUNT == CMP` 触发 `cmp_hit` 脉冲并置位标志;计数归零触发 `irq` 中断;
- **状态写 1 清零(W1C)**:`STATUS`(`0x10`)超时标志与比较标志支持写 1 清除;
- **跑马灯(GPIO 旋转)**:`CTRL[2]=1` 时,每次倒计数超时将自动左移 8 位图案,便于在波形/引脚上直观监测。
### 寄存器映射表
| 偏移地址 | 寄存器名称 | 读写属性 | 复位值 | 详细说明 |
|:---:|:---:|:---:|:---:|:---|
| `0x00` | **CTRL** | RW | `0x00` | `[0]` 计数使能 (`enable`)
`[1]` 中断使能 (`irq_en`)
`[2]` 跑马灯使能 (`pattern_en`) |
| `0x04` | **LOAD** | RW | `0x09` | 计数器重载值 (写入时直接同步预置当前计数) |
| `0x08` | **COUNT** | RO | `0x09` | 当前实时倒计数值 |
| `0x0C` | **CMP** | RW | `0x03` | 比较匹配值 |
| `0x10` | **STATUS** | W1C | `0x00` | `[0]` 超时中断标志
`[1]` 比较匹配标志 |
| `0x14` | **GPIO** | RW | `0x01` | 8 位输出图案寄存器 (超时自动循环移位) |
| `0x18` | **ID** | RO | `0x5A33_0001` | **Palladium Z3 硬件签名** |
---
## 4. 模式一:SA 模式(仿真加速)快速上手
在 SA 模式下,**DUT 运行在 Palladium Z3 物理硬件中**,而**Testbench 运行在 Host 主机端(Xcelium)**,两者通过高速通道协同交互。
### 第一步:排查并确保硬件服务连通
```bash
# 1. 导入 Z3 专用环境变量
source scripts/env_z3.sh
# 2. 运行一键体检脚本,确保 test_server 与 configmgr 正常
./scripts/check_z3_server.sh
```
### 第二步:编译硬件与软件协同工程
```bash
./scripts/compile_sa.sh
```
该脚本将生成 `ixcom_db/` 目录以及映射进 Z3 的硬件网表和 Host 端仿真数据库。
### 第三步:上机下载与测试
```bash
cd ixcom_db
xeDebug -f ../scripts/run_xedebug.tcl
```
运行输出将显示在终端和 `xeDebug.log` 中:
```text
[PASS] Check 1: Z3 ID register match (0x5A330001)
[PASS] Check 2: Default COUNT is 9
[PASS] Check 3: Timer interrupt (irq) asserted!
[PASS] Check 4: STATUS register bits set (timeout & cmp: 0x00000003)
[PASS] Check 5: STATUS cleared via W1C
[PASS] Check 6: GPIO pattern rotated to 0x02
==========================================================
TEST PASSED: ALL 6 CHECKS COMPLETED ON Z3 !
==========================================================
```
---
## 5. 模式二:ICE 模式(在线硬件仿真)快速上手
在 ICE 模式下,**没有 Host 端的软件 Testbench**。激励生成、总线访问与断言判读由纯硬件状态机(`z3_demo_ice_top.v`)在机台内部全速自主完成。
### 第一步:编译 ICE 顶层全硬件网表
```bash
source scripts/env_z3.sh
./ice/scripts/compile_ice.sh
```
### 第二步:下载进 Palladium Z3 并自动判读
```bash
xeDebug -f ice/scripts/run_xedebug_ice.tcl
```
脚本将硬件引脚读回终端:
- `led_done = 1`:自检执行完毕;
- `led_pass = 1`,`led_fail = 0`:所有硬件级断言均通过;
- `led_gpio = 0x02`:跑马灯正常移位。
---
## 6. 本地离线免硬件验证(Smoke Test)
如果当前没有连接到 Palladium Z3 硬件,可随时在工作站上离线验证逻辑:
```bash
# 验证 SA 模式逻辑:
./scripts/run_local.sh
# 验证 ICE 模式硬件状态机逻辑:
./ice/scripts/run_local_ice.sh
```
两者均支持 Icarus Verilog (`iverilog`) 或 Cadence Xcelium (`xrun`)。