chipsalliance/adams-bridge

_*SPDX-License-Identifier: Apache-2.0


Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.*_
# **Adam's Bridge 动手指南** ## **后量子密码学 IP 核** _*最后更新: 2025/08/29*_ ## **发布与集成** 之前的正式版本可在以下地址获取：https://github.com/chipsalliance/adams-bridge/releases
发布以标签（tag）形式提供，并包含可下载的资源（但不应使用这些资源）。 集成商不应下载发布附带的资源，而应通过从关联标签处拉取仓库代码来使用 AdamsBridge 的发布版本，原因请参考：https://github.com/chipsalliance/caliptra-rtl/issues/471。 ## **使用的工具** 操作系统： - 构建说明假设使用 Linux 环境 静态检查： - Synopsys Spyglass - `Version S-2021.09-1` - Real Intent AscentLint - `Version 2019.A.p15 for RHEL 6.0-64, Rev 116515, Built On 12/18/2020` 仿真： - Synopsys VCS 与 Verdi - `Version R-2020.12-SP2-7_Full64` - Verilator - `Version 5.012` - Mentor Graphics QVIP - `Version 2021.2.1` 的 AHB 模型 - UVM 安装 - `Version 1.1d` - Mentor Graphics UVM-Frameworks - `2022.3` 综合： - Synopsys Fusion Compiler - `Version 2022.12-SP3` GCC： - 用于生成内存初始化文件的 RISCV 工具链 - `Version 2023.04.29` - `riscv64-unknown-elf-gcc (g) 12.2.0` - G++ 用于编译 Verilator 对象和测试固件 - `g++ (GCC) 11.2.0` CDC： - Questa CDC - `2023.3 5624840 linux_x86_64 19-Jul-2023` RDC： - Real Intent Meridian - `2019.A.P16` RDL 编译器： - systemrdl-compiler==1.27.3 - peakrdl-systemrdl==0.3.0 - peakrdl-regblock==0.21.0 - peakrdl-uvm==2.3.0 - peakrdl-ipxact==3.4.3 - peakrdl-html==2.10.1 - peakrdl-cheader==1.0.0 - peakrdl==1.1.0 其他： - Playbook（微软内部的工作流管理工具） ## **环境变量** 仿真所需： `CALIPTRA_WORKSPACE`：定义将创建 Verilator “scratch” 输出目录的绝对路径。建议将其定义为包含子目录 “chipsalliance” 的目录的绝对路径，该子目录又包含项目仓库根目录（称为 “adams-bridge”）
`ADAMSBRIDGE_ROOT`：定义项目仓库根目录（称为 “adams-bridge”）的绝对路径。建议将其定义为 `${CALIPTRA_WORKSPACE}/chipsalliance/caliptra-rtl/submodules/adams-bridge`
## **仓库概览** ``` adams-bridge |-- LICENSE |-- README.md |-- Release_Notes.md |-- SECURITY.md |-- docs | |-- AdamsBridgeHardwareSpecification.md | |-- Side-Channel Countermeasures for Adam’s Bridge Accelerator.docx | `-- images |-- src | |-- abr_libs | |-- abr_prim | |-- abr_prim_generic | |-- abr_sha3 | |-- decompose | |-- embedded_top | |-- exp_mask | |-- makehint | |-- abr_sampler_top | |-- abr_top | |-- norm_check | |-- ntt_top | |-- pk_decode | |-- power2round | |-- rej_bounded | |-- rej_sampler | |-- sample_in_ball | |-- sig_decode_z | |-- sig_encode_z | |-- sigdecode_h | |-- sk_decode | `-- sk_encode `-- tools |-- README |-- scripts `-- templates ``` 仓库根目录的结构如上所示，深度为 2 层。
每个子组件都附带一个文件列表摘要（位于 src//config/.vf），其中包含编译该组件所需的所有文件名，以及可选的单元测试级仿真测试台文件列表。
VF 文件提供指向每个编译目标的绝对文件路径（由 `ADAMSBRIDGE_ROOT` 环境变量前缀），对应相关组件。
“abr_top” 子组件包含 AdamsBridge 的顶层文件集。`src/abr_top/config/compile.yml` 定义了该构建目标所需的文件集和子组件依赖关系。所有文件/依赖项均在 `src/abr_top/config/abr_top_tb.vf` 中明确列出。用户可以仅使用此 VF 文件列表编译整个设计。
## **Verilog 文件列表** Verilog 文件列表通过 VCS 生成，并包含在每个单元的 config 目录中。添加到设计中的新文件必须包含在 vf 列表中。它们可以手动包含，也可以通过使用 VCS 重新生成 vf 文件。文件列表定义了构建和仿真给定模块或测试台所需的编译源（包括所有依赖项），集成商应用于仿真、静态检查和综合使用。 ## **脚本说明** `reg_gen.py`：用于将 RDL 文件编译/导出为寄存器源代码
`reg_gen.sh`：用于调用 `reg_gen.py` 的包装脚本，针对 AdamsBridge 中的所有 IP 核
`rdl_post_process.py`：后处理功能，使 RDL 生成的 SystemVerilog 文件兼容于静态检查/Verilator 要求
## **仿真流程** 按照此处描述的 Caliptra 仿真流程操作：https://github.com/chipsalliance/caliptra-rtl/tree/main?tab=readme-ov-file#simulation-flow ### 单元仿真 VCS 步骤： 1. 设置工具并添加到 PATH 2. 定义上述所有环境变量 3. 为构建输出创建一个运行文件夹（并进入该文件夹） 4. 使用 `src//config/_tb.vf` 作为编译目标，在 VCS 中编译完整项目。运行 `vcs` 命令生成 simv 时，用户应确保 `_tb` 在命令中显式指定为顶层组件，以确保这是唯一被仿真的 “顶层”。 5. 将测试生成脚本或测试向量复制到运行输出目录 6. 使用 `_tb` 作为顶层目标模拟项目 ### UVM 单元测试步骤：
**说明**：
UVM 框架生成工具用于为 AdamsBridge 内的每个 IP 组件创建基线 UVM 测试台。以下 IP 块已支持 UVM 测试台： - [MLDSA87](src/abr_top/uvmf) - [MLKEM1024](src/abr_top/uvmf) **先决条件**：
- QVIP 2021.2.1（适用于 Mentor Graphics，提供 AHB VIP） - UVM 1.1d 安装 - Mentor Graphics UVM-Framework 安装 **步骤**：
1. 编译 UVM 1.1d 库 2. 编译 AHB QVIP 源代码 3. 编译 Mentor Graphics UVM-Framework 基础库 4. 编译 `src/abr_libs/uvmf` 中的 AHB UVMF 包装器 5. 编译目标测试台提供的 `verification_ip` 6. 所有编译步骤均可通过 `src//uvmf_/config/.vf` 中找到的文件列表完成 7. 注意：`adams-bridge/src//uvmf_/uvmf_template_output/project_benches//tb/testbench/hdl_top.sv` 是系统的顶层 TB 包装器 8. 将测试生成脚本复制到运行输出目录： - [src/abr_top/uvmf/Dilithium_ref/dilithium/ref/test/test_dilithium5](src/abr_top/uvmf/Dilithium_ref/dilithium/ref/test/test_dilithium5) * MLDSA87 单元测试所必需 9. 从 `adams-bridge/src/abr_top/uvmf_/uvmf_template_output/project_benches/` 参数 ## **回归测试** 按照此处描述的 Caliptra 回归测试操作：https://github.com/chipsalliance/caliptra-rtl/blob/main/README.md#regression-tests ## **备注** * 内部寄存器在 [GitHub 页面](https://chipsalliance.github.io/caliptra-rtl/main/internal-regs/?p=clp.abr_reg) 上自动渲染 * 重要：渲染的文档基于 Adams Bridge 子模块的版本（位于 [caliptra-rtl 仓库](https://github.com/chipsalliance/caliptra-rtl/tree/main/submodules)），**不是** Adams Bridge 主分支的最新提交。对主分支的更改可能不会反映在文档中，直到子模块更新为止。

标签：Adam's Bridge, AscentLint, ASIC, Chips Alliance, Crystals-Dilithium, CVE, FPGA, Fusion Compiler, GCC, IP Core, Mentor Graphics QVIP, Questa CDC, RISCV, SPDX-License-Identifier, Spyglass, Synopsys, UVM, VCS, Verilator, Verilog, VHDL, 代码走查, 公钥密码, 后量子密码, 安全芯片, 密码学, 工具链, 开源硬件, 开源许可证, 形式验证, 手动系统调用, 抗量子攻击, 数字签名, 测试平台, 硬件安全, 硬件验证, 综合, 逆向工具, 集成电路, 静态时序分析