pragma HLS interface - 2025.2 简体中文 - UG1399

描述

仅支持对顶层函数使用 INTERFACE 编译指示或指令，无法将其用于 HLS 组件的子函数。它可指定在接口综合期间如何根据函数实参创建 RTL 端口，如 定义接口 所述。Vitis HLS 工具会自动确定任何子函数使用的 I/O 协议。

RTL 实现中的端口衍生自顶层函数和函数返回的实参的数据类型和方向、HLS 组件的 flow_target、config_interface 及 INTERFACE 编译指示或指令所指定的默认接口配置设置。每个函数实参均可指定为包含其自己的 I/O 协议（例如，有效握手或确认握手）。

该接口还定义了 HLS 组件的执行控制协议，如 块级控制协议 中所述。控制协议用于控制 HLS 组件（或块）何时开始执行，以及该块在完成操作后何时处于空闲状态并准备就绪以接收新输入。

语法

将编译指示布局在函数边界内。

#pragma HLS interface mode=<mode> port=<name> direct_io=<value>[OPTIONS]

其中：

mode=<mode>

受支持的模式以及该工具在 RTL 中实现这些模式的方式均可细分为如下 3 个类别：

1. 端口级协议：
   • ap_none：无端口协议。此接口是简单的数据端口。
   • ap_vld：用于实现含关联 valid 信号的数据端口，以指示何时数据有效且可供读取或写入。
   • ap_ack：用于实现含关联 acknowledge 信号的数据端口，以确认数据已读取或写入。
   • ap_hs：用于实现同时包含 valid 信号和 acknowledge 信号的数据端口，提供两路握手以指示数据有效且可供读取和写入，并确认数据已读取或写入。
   • ap_ovld：用于实现含关联 valid 信号的输出数据端口，以指示何时数据有效且可供读取或写入。
     提示： 对于 ap_ovld，Vitis HLS 通过 ap_none 模式来实现输入实参或任意读取/写入实参的输入部分。
   • direct_io=<true/false>：针对 INTERFACE 应用到的函数实参，指定值为 true。请参阅 将直接 I/O 串流映射到 SAXI Lite 接口 章节以获取该选项的用例。
   • ap_memory：用于实现阵列实参（作为标准 RAM 接口）。如果在 Vivado IP integrator 中使用 RTL 设计，那么该接口将由多个不同端口组成。
   • bram：用于实现阵列实参（作为标准 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 接口来实现。您可使用 config_interface -m_axi_addr64 命令来指定 32 位（默认）地址端口或 64 位地址端口，并控制任何地址偏移。
   • axis：用于将该端口作为 AXI4-Stream 接口来实现。
3. 块级控制协议：
   • ap_ctrl_chain：实现块级控制端口以启动 (start) 设计操作、continue 操作，以及指示设计何时处于 idle、done 和 ready 状态，以便处理新输入数据。
   • ap_ctrl_hs：实现块级控制端口以启动 (start) 设计操作，并指示设计何时处于 idle、done 和 ready 状态，以便处理新输入数据。
   • ap_ctrl_none：无块级 I/O 协议。
     注释： 使用 ap_ctrl_none 模式可阻止使用 C/RTL 协同仿真来验证设计。

port=<name>

用于指定 INTERFACE 编译指示所应用到的函数实参或函数返回的名称。

提示： 块级 I/O 协议（ap_ctrl_none、ap_ctrl_hs 或 ap_ctrl_chain）可分配到端口，以供函数 return 值使用。

选项

bundle=<string>

默认情况下，HLS 工具会将函数实参与兼容选项组合或捆绑到 RTL 中的接口端口内。所有 AXI4-Lite (s_axilite) 接口都会尽可能捆绑到 AXI4-Lite 端口内。同样，默认指定为 AXI4 (m_axi) 接口的所有函数实参也都会捆绑到单一 AXI4 端口内。

含兼容选项（例如，mode、offset 和 bundle）的所有接口端口都组合到单一接口端口内。端口名称自动衍生自模式与捆绑的组合，或者可通过 -name 来指定名称。

重要： 指定 bundle 名称时，应使用全小写字符。

channel=<string>

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

clock=<name>

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

depth=<int>

指定供测试平台处理的最大采样数。此设置用于指示 HLS 工具为 RTL 协同仿真所创建的验证适配器中所需 FIFO 的最大大小。基于顶层端口实参，该选项接受简单的表达式，例如：

int dut(int *arr, int height, int width)
{
#pragma HLS interface m_axi port=arr depth=height*width
...

提示： 虽然 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 接口的期望时延，允许设计发起总线请求的时间比执行期望的读取或写入操作早 <value> 个周期（时延）。如果该值太低，设计将过早达成就绪状态，可能停滞并等待总线；如果该值太高，总线访问可能处于空闲状态并等待设计发起访问。

max_read_burst_length=<int>

该选项适用于 M_AXI 接口，可指定突发传输期间读取的数据值的最大数量。如需了解更多信息，请参阅 AXI 突发传输。

max_write_burst_length=<int>

• 对于 AXI4 (m_axi) 接口，该选项用于指定突发传输期间写入的数据值的最大数量。
  提示： 如果此端口为只读端口，则请设置 num_write_outstanding=1 和 max_write_burst_length=2 以节省存储器资源。对于仅限写入的端口，请设置 num_read_outstanding=1 和 max_read_burst_length=2。

max_widen_bitwidth=<int>

自动拓宽接口时，请指定接口可用的最大位宽。此设置将覆盖由 config_interface -m_axi_max_bitwidth 命令指定的全局值。

name=<string>

指定将在生成的 RTL 中使用的端口的名称。

num_read_outstanding=<int>

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

num_read_outstanding*max_read_burst_length*word_size

num_write_outstanding=<int>

对于 AXI4 (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 从接口。这是默认偏移。

autorestart

启用在 AXI4-Lite 适配器中生成 auto-restart 计数器的操作。

当该选项设为“true”时，编译后的内核必须通过测试平台中的 hls::autorestart 类来驱动。该选项适用于以下使用约束：

• mode 必须设为 s_axilite
• port 必须设为 return
• 内核的顶层协议必须设为 ap_ctrl_hs

register

此可选关键字可用于寄存信号和任何相关协议信号，并导致保持直至至少完成函数执行的最后一个周期为止。config_interface 命令的 -register_io 选项用于全局控制在顶层函数上寄存所有输入/输出的操作。该选项适用于以下接口模式：

• ap_fifo
• ap_none
• ap_hs
• ap_ack
• ap_vld
• ap_ovld

提示： 不支持在函数的返回端口 (port=return) 上使用寄存器选项。请改为使用 LATENCY 编译指示或指令：

#pragma HLS LATENCY min=1 max=1

register_mode=<forward|reverse|both|off>

该选项适用于 AXI4-Stream 接口，并用于指定寄存器布局到正向路径（TDATA 和 TVALID）、反向路径 (TREADY) 或同时布局到这两条路径（TDATA、TVALID 和 TREADY）上，或者不寄存任何端口信号 (off)。默认值为 both。AXI4-Stream 旁路信号被视为数据信号，随 TDATA 一起寄存。

storage_impl=<impl>

仅限搭配 s_axilite 一起使用。该选项可定义要分配给接口的存储实现。

受支持的实现值包括 auto、bram 和 uram。默认值为 auto。

提示： uram 是同步存储器，对于两个端口仅含单个时钟。因此，针对含第二个时钟的 s_axilite 适配器不能指定 uram。

storage_type=<value>

仅限搭配 ap_memory 接口一起使用。该选项用于指定要分配给变量的存储类型（即，RAM_T2P）。

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

提示： 对于不在接口上的对象，也可以使用 BIND_STORAGE 编译指示或指令来指定该选项。

示例 1

在此示例中，两个函数实参都是使用 AXI4-Stream 接口来实现的：

void example(int A[50], int B[50]) {
  //Set the HLS native interface types
  #pragma HLS INTERFACE mode=axis port=A
  #pragma HLS INTERFACE mode=axis port=B
  int i;
  for(i = 0; i < 50; i++){
    B[i] = A[i] + 5;
  }
}

示例 2

以下设置会关闭块级 I/O 协议，并分配至函数返回值：

#pragma HLS interface mode=ap_ctrl_none port=return

指定函数实参 InData 以使用 ap_vld 接口，并指示应寄存输入：

#pragma HLS interface mode=ap_vld register port=InData

示例 3

此示例定义了顶层 transpose 函数的端口的 INTERFACE 标准。请注意，其中使用了 bundle= 选项来对信号进行分组。

// TOP LEVEL - TRANSPOSE
void transpose(int* input, int* output) {
	#pragma HLS INTERFACE mode=m_axi port=input offset=slave bundle=gmem0
	#pragma HLS INTERFACE mode=m_axi port=output offset=slave bundle=gmem1

	#pragma HLS INTERFACE mode=s_axilite port=input bundle=control
	#pragma HLS INTERFACE mode=s_axilite port=output bundle=control
	#pragma HLS INTERFACE mode=s_axilite port=return bundle=control

	#pragma HLS dataflow

另请参阅

• set_directive_interface
• pragma_HLS_bind_storage