syn.directive.interface - 2025.2 简体中文 - UG1399

描述

仅限顶层函数才支持 syn.directive.interface 指令。对于 HLS 组件的子函数，您无法使用该指令。INTERFACE 编译指示或指令会指定在接口综合期间函数实参创建 RTL 端口的方式。请参阅 Vitis 高层次综合用户指南(UG1399) 的“定义接口”章节。Vitis HLS 工具会自动确定任何子函数使用的 I/O 协议。

RTL 实现中的端口来自以下要素。

• 顶层函数与函数返回的实参的数据类型和方向。
• HLS 组件的 flow_target。
• 由 syn.interface.xxx 指定的默认接口配置设置（请参阅 接口配置）。
• syn.directive.interface。

每个函数实参均可包含其自己的 I/O 协议（例如，有效握手或确认握手）。

该接口还定义了 HLS 组件的执行控制协议。欲知详情，请参阅 Vitis 高层次综合用户指南(UG1399) 的“块级控制协议”章节。控制协议用于控制 HLS 组件（或块）何时开始执行，以及该块在完成操作后何时处于空闲状态并准备就绪以接收新输入。

语法

syn.directive.interface=[OPTIONS] <location> <port>

• <location> 对应位置，在此位置中，可指定函数接口或寄存的输出（格式为 function[/label]）。
• <port> 是用于对接口进行综合的参数（函数实参）。下列块控制模式无需端口名称：ap_ctrl_chain、ap_ctrl_hs 或 ap_ctrl_none。

选项

mode=<mode>

以下三个类别演示了这些模式以及工具如何在 RTL 中实现这些模式。

1. 端口级协议：

   ap_none

   无端口协议。此接口是简单的数据端口。

   ap_stable

   无协议。此接口是简单的数据端口。Vitis HLS 工具假定复位后数据端口始终保持稳定。允许通过优化来移除不必要的寄存器。

   ap_vld

   用于实现含关联 valid 信号的数据端口，以指示何时数据有效且可供读取或写入。

   ap_ack

   用于实现含关联 acknowledge 信号的数据端口，以确认数据写入或读取。

   ap_hs

   用于实现同时包含 valid 信号和 acknowledge 信号的数据端口，提供两路握手以指示数据何时有效且可供读取和写入。确认数据已被读取或写入

   ap_ovld

   用于实现含关联 valid 信号的输出数据端口，以指示何时数据有效且可供读取或写入。

   提示： 对于 ap_ovld，Vitis HLS 通过 ap_none 模式来实现输入实参或任意读取/写入实参的输入部分。

   ap_memory

   用于实现阵列实参（作为标准 RAM 接口）。如果在 Vivado IP integrator 中使用 RTL 设计，请将组成该接口的各端口分离。

   ap_fifo

   使用含关联低电平有效 FIFO empty 端口和 full 端口的数据输入和输出端口来实现含标准 FIFO 接口的端口。

   注释： 您只能对读取实参或写入实参使用 ap_fifo 接口。ap_fifo 模式不支持双向读写实参。

2. AXI 接口协议：

   s_axilite

   用于将该端口作为 AXI4-Lite 接口来实现。为 HLS 组件导出生成的 RT 时，该工具会生成一组关联的 C 语言驱动程序文件。

   m_axi

   用于将该端口作为 AXI4 接口来实现。您可使用 syn.interface.m_axi_addr64 命令来指定 32 位（默认）地址端口或 64 位地址端口，并控制任何地址偏移。

   axis

   用于将该端口作为 AXI4-Stream 接口来实现。

3. 块级控制协议：

   ap_ctrl_chain

   实现一组块级控制端口，以执行下列操作。

   • 使用 start 表示开始设计操作
   • 指示何时设计处于 idle 状态
   • 指示何时设计处于 done 状态
   • 使用 ready 表示接收新输入数据

   ap_ctrl_hs

   实现一组块级控制端口以通过 start 开始设计操作。同时指示何时设计处于 idle、done 和 ready 状态（接收新输入数据）。

   ap_ctrl_none

   无块级 I/O 协议。

   注释： 使用 ap_ctrl_none 模式可阻止使用 C/RTL 协同仿真来验证设计。

bundle=<string>

默认情况下，HLS 工具会将兼容的函数实参组合（或捆绑）到 RTL 代码中的单个接口端口内。含兼容选项（例如，mode、offset 和 bundle）的所有接口端口都组合到单一接口端口内。

提示： 此默认行为可使用 syn.interface.m_axi_auto_max_ports 命令来进行更改。

bundle=<string> 选项允许您定义捆绑，用于将端口组合在一起，这会覆盖默认行为。<string> 用于指定捆绑名称。mode 与 bundle 的组合可在生成的 RTL 中提供端口名称。name 也可指定端口名称。

重要： 您必须使用小写字符来指定 bundle 名称。

clock=<string>

默认情况下，AXI4-Lite 接口时钟与系统时钟为相同时钟。该选项会为 AXI4-Lite 接口指定独立时钟。如果使用 bundle 选项将多个顶层函数实参组合到单一 AXI4-Lite 接口中，那么只需在其中一个捆绑成员上指定时钟选项即可。

channel=<string>

要在 m_axi 接口上启用多个通道，请指定通道 ID。您可使用不同的通道 ID 将多个 m_axi 接口组合为单个 m_axi 适配器。

depth=<int>

指定供测试平台处理的最大采样数。此设置用于指示 HLS 工具为 RTL 协同仿真所创建的验证适配器中所需 FIFO 的最大大小。

提示： 虽然 depth 选项通常为可选，但需要通过该选项来为 RTL 协同仿真指定指针实参大小。

interrupt=<int>

仅限 ap_vld/ap_hs 才会使用该选项。该选项会启用中断中的 I/O 管理。该选项会在 s_axilite 寄存器文件中的 ISR 和 IER 中创建对应的位。整数值 N=16..31 用于指定这两个寄存器中的位元位置。默认情况下，位元的位置是从 16 开始连续分配的。

latency=<value>

该选项可用于 ap_memory 和 m_axi 接口。

• 在 ap_memory 接口中，该选项用于指定驱动接口的 RAM 资源的读取时延。默认执行 1 个时钟周期的读取操作。该选项允许对读取时延超过 1 个时钟周期的外部 RAM 进行建模。
• 在 m_axi 接口中，该选项用于指定 AXI4 接口的目标时延，允许设计先发起总线请求，然后在经过指定的周期数（时延）后再执行所期望的读取或写入操作。如果该值太低，设计可能过早达成就绪状态，并且可能停滞并等待总线；如果该值太高，总线访问可能处于空闲状态并等待设计发起访问。

max_read_burst_length=<int>

该选项适用于 m_axi 接口，可指定突发传输期间读取的数据值的最大数量。如需了解更多信息，请参阅 Vitis 高层次综合用户指南(UG1399) 的“AXI 突发传输”章节。

max_write_burst_length=<int>

该选项适用于 m_axi 接口，可指定突发传输期间写入的数据值的最大数量。

max_widen_bitwidth=<int>

自动拓宽接口时，请指定接口可用的最大位宽。此设置将覆盖由 syn.interface.m_axi_max_bitwidth 命令指定的默认值。如需了解更多信息，请参阅Vitis 高层次综合用户指南(UG1399) 的“端口宽度自动调整”章节。

name=<string>

指定端口名称以供生成的 RTL 使用。mode 与 bundle 组合即可指定端口名称。但以 name 指定名称时则是例外。

num_read_outstanding=<int>

该选项适用于 m_axi 接口，用于指定在设计停滞前可对 AXI4 总线发起的读取请求数量（无响应）。此操作暗示设计中的内部存储空间，且 FIFO 大小为：

num_read_outstanding*max_read_burst_length*word_size

num_write_outstanding=<int>

搭配 m_axi 接口一起使用。该选项指定 AXI4 总线在设计停滞之前可以接受的写请求（无响应）数量。此操作暗示设计中的内部存储空间，且 FIFO 大小为：

num_write_outstanding*max_write_burst_length*word_size

offset=<string>

为指定端口控制 AXI4-Lite (s_axilite) 和 AXI4 存储器映射 (m_axi) 接口中的地址偏移。

• 在 s_axilite 接口中，<string> 用于指定寄存器映射中的地址。
• 在 m_axi 接口中，该选项会覆盖 config_interface -m_axi_offset 选项和 <string> 所指定的全局选项。请参阅下文以获取详细信息。
  • off：不生成偏移端口。
  • direct：生成标量输入偏移端口。
  • slave：生成偏移端口并自动将其映射到 AXI4-Lite 从接口。这是默认偏移。

register

寄存信号和所有关联的协议信号。指示各信号保持不变直至至少完成函数执行的最后一个周期为止。syn.interface.register_io 命令用于控制顶层函数上的所有接口的默认寄存，该选项则允许您覆盖当前接口的默认设置。该选项适用于以下接口模式：

• s_axilite
• ap_fifo
• ap_none
• ap_stable
• ap_hs
• ap_ack
• ap_vld
• ap_ovld

提示： register 选项不适用于函数的返回端口 (port=return)。请改用 syn.directive.latency。

register_mode=(both|forward|reverse|off)

该选项适用于 AXI4-Stream 接口，它会指定是否在以下位置布局寄存器。

• 在正向路径上布局寄存器（TDATA 和 TVALID），或者
• 在反向路径 (TREADY) 上布局寄存器，在两条路径上都布局寄存器 (both)，或者
• 不在任何端口信号上布局寄存器 (off).

默认值为 register_mode=both。

提示： AXI4-Stream 旁路信号为数据信号。寄存 TDATA 时也会寄存器这些信号。

storage_impl=<impl>

该选项仅适用于 mode=s_axilite，用于定义分配给该接口的存储实现。受支持的 <impl> 值包括：auto、bram 和 uram。默认值为 auto。

提示： uram 是同步存储器，能为两个端口提供单一时钟（仅限某些器件上可用）。因此不能将 uram 指定用于含 2 个时钟的 s_axilite 适配器，当指定部件不支持 uram 时也不可用。

storage_type=<type>

该选项仅适用于 mode=ap_memory 或 mode=bram，用于定义要分配给变量的存储类型（例如，RAM_T2P）。

受支持的类型包括：ram_1p、ram_1wnr、ram_2p、ram_s2p、ram_t2p、rom_1p、rom_2p 和 rom_np。

提示： 对于顶层函数上的对象，可使用 syn.directive.bind_storage 定义该选项。

示例 1

此示例用于演示为 func 函数禁用函数级握手。

syn.directive.interface=mode=ap_ctrl_none func return

示例 2

函数 func 中的实参 InData 具有 ap_vld 接口。需寄存输入。

syn.directive.interface=func InData mode=ap_vld register

另请参阅

• syn.directive.bind_storage
• syn.directive.latency