syn.directive.interface - 2025.1 日本語 - UG1399

Vitis 高位合成ユーザー ガイド (UG1399)
Document ID
UG1399
Release Date
2025-09-10
Version
2025.1 日本語

説明

syn.directive.interface は最上位関数にのみ使用でき、HLS コンポーネントの下位関数には使用できません。 『Vitis 高位合成ユーザー ガイド』 (UG1399) の「インターフェイスの定義」セクションで説明するように、INTERFACE プラグマまたは指示子は、インターフェイス合成で関数引数からどのように RTL ポートが作成されるかを指定します。下位関数で使用される I/O プロトコルは Vitis HLS ツールにより自動的に決定されます。

RTL インプリメンテーションのポートは、最上位関数と関数リターンの引数のデータ型と方向、HLS コンポーネントの flow_target、syn.interface.xxx コマンド (インターフェイス コンフィギュレーション を参照) および syn.directive.interface で指定されたデフォルトのインターフェイス コンフィギュレーション設定によって決まります。各関数引数は、有効ハンドシェイクや承認ハンドシェイクなどの独自の I/O プロトコルを持つように指定できます。

ヒント: インターフェイスに必要なグローバル変数は、 『Vitis 高位合成ユーザー ガイド』 (UG1399) の「グローバル変数」セクションで説明するように、最上位関数の引数として明示的に定義する必要があります。ただし、グローバル変数がアクセスされても、すべての読み出しおよび書き込みがデザインのローカルである場合は、リソースはデザイン内に作成され、RTL に I/O ポートは必要ありません。

また、このインターフェイスは、 『Vitis 高位合成ユーザー ガイド』 (UG1399) の「ブロックレベル制御プロトコル」で説明されるように、HLS コンポーネントの実行制御プロトコルも定義します。制御プロトコルは、HLS コンポーネント (またはブロック) が実行を開始するタイミングを制御し、ブロックが動作を完了すると、アイドル状態になって新しい入力に対応できるようにします。

構文

syn.directive.interface=[OPTIONS] <location> <port>
  • <location>: 関数インターフェイスまたはレジスタを指定する場所を function[/label の形式で指定します。
  • <port>: インターフェイスを合成するパラメーター (関数引数) を指定します。ブロック制御モードが指定されている場合、ポート名 (ap_ctrl_chain、ap_ctrl_hs、ap_ctrl_none) は必要ありません。

オプション

ヒント: 次に示す多くのオプションには、syn.interface.xxx コマンドで定義されたデフォルト値があります。ここで定義したインターフェイスにローカル値を定義すると、デフォルト値をオーバーライドできます。
mode=<mode>

サポートされているモードと、それをツールが RTL でどのようにインプリメントするかは、次のように 3 つのカテゴリに分類されます。

  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 インテグレーターで RTL デザインを使用する場合、インターフェイスが別々のポートで構成されます。
    ap_fifo
    標準 FIFO インターフェイスのポートが、アクティブ Low FIFO の empty および full ポートが関連付けられたデータ入力および出力ポートを使用してインプリメントされます。
    注記: ap_fifo インターフェイスは、読み出し引数または書き込み引数のみに使用できます。ap_fifo モードでは双方向の読み出し/書き込み引数はサポートされません。
  2. AXI インターフェイス プロトコル:
    s_axilite
    ポートが AXI4-Lite インターフェイスとしてインプリメントされます。ツールは、HLS コンポーネントの生成された RT をエクスポートする際に、関連する C ドライバー ファイルのセットを生成します。
    m_axi
    ポートが AXI4 インターフェイスとしてインプリメントされます。32 ビット (デフォルト) または 64 ビットのアドレス ポートを指定し、アドレス オフセットを制御するには、syn.interface.m_axi_addr64 コマンドを使用できます。
    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 の協調シミュレーションを使用してデザインを検証できなくなることがあります。
bundle=<string>

デフォルトでは、HLS ツールで互換性のある関数引数が RTL コードの単一のインターフェイス ポートにグループ化 (またはバンドル化) されます。mode、offset、bundle などのオプションに互換性があるすべてのインターフェイスは、1 つのインターフェイス ポートにまとめられます。

ヒント: このデフォルトは syn.interface.m_axi_auto_max_ports コマンドを使用すると変更できます。

この bundle=<string> オプションを使用すると、デフォルトの動作を上書きして、ポートをグループ化するバンドルを定義できます。<string> は、バンドル名を指定します。生成される RTL コードで使用されるポート名は、mode と bundle の組み合わせから自動的に指定されるか、nameで指定された名前になります。

重要: bundle 名は、小文字で指定する必要があります。
clock=<string>
デフォルトでは、AXI4-Lite インターフェイス クロックはシステム クロックと同じです。このオプションを使用すると、AXI4-Lite インターフェイスに別のクロックを指定できます。bundle オプションを使用して複数の最上位関数引数を 1 つの AXI4-Lite インターフェイスにまとめている場合は、-clock オプションはバンドル メンバーの 1 つにのみ指定します。
channel=<string>
m_axi インターフェイスで複数のチャネルを有効にするには、チャネル ID を指定します。複数の m_axi インターフェイスを、別々のチャネル ID を使用して 1 つの m_axi アダプターに統合できます。
depth=<int>
テストベンチで処理されるサンプルの最大数を指定します。この設定は、HLS ツールで RTL 協調シミュレーション用に作成される検証アダプターに必要な FIFO の最大サイズを示します。
ヒント: 通常、depth はオプションですが、RTL 協調シミュレーションではポインター引数のサイズを指定する必要があります。
interrupt=<int>
ap_vld/ap_hs のみで使用します。このオプションは、s_axilite レジスタ ファイルの ISR と IER に対応するビットを作成することで、割り込みで管理される I/O を有効にします。整数値 N=16...31 は、両レジスタのビット位置を指定します (デフォルトでは 16 から連続して割り当てられます)。
latency=<value>
このオプションは、ap_memory および m_axi インターフェイスで使用できます。
  • ap_memory インターフェイスでは、インターフェイスを駆動する RAM リソースの読み出しレイテンシを指定します。デフォルトでは、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 で使用されるポートの名前を指定します。デフォルトでポート名は、name で指定されてなければ、mode と bundle の組み合わせから自動的に付けられます。
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)、またはその両方のパスに配置するか、レジスタをどの信号にも配置しないか (off) を指定します。デフォルトは register_mode=both です。
ヒント: AXI4-Stream サイドチャネル信号はデータ信号と認識され、TDATA にレジスタが付けられると、レジスタが付けられます。
storage_impl=<impl>
このオプションは、mode=s_axilite にのみ使用する場合、インターフェイスに割り当てるストレージ インプリメンテーションを定義します。サポートされる <impl> 値は auto、bram、および uram です。デフォルトは auto です。
ヒント: uram は、特定のデバイスでのみ使用できる 2 つのポートに対して 1 つのクロックのみを持つ同期メモリです。このため、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 インターフェイスを含め、入力にレジスタを付けます。

set_directive_interface=func InData mode=ap_vld register

関連項目