CSV ファイル形式 - 2023.2 日本語

AI エンジン ツールおよびフロー ユーザー ガイド (UG1076)
Document ID
UG1076
Release Date
2023-12-04
Version
2023.2 日本語

PLIO ベースのシミュレーションの場合、AI エンジン シミュレータは CSV ファイル形式をサポートします。この新しい形式は、トランザクションをより詳細に制御し、AI エンジンへのサイクルごとのトラフィック挿入を可能にします。このファイル形式は高い柔軟性を備えており、トラフィック挿入に空のクロック サイクルを追加する、STALL コマンドを使用して複数の空のサイクルを挿入する、および TLAST と TKEEP の値を明示的に指定することが可能です。このような機能により、複雑なシナリオをシミュレーションし、デザインのビヘイビアーを解析できます。

CSV ファイルを PLIO ベースの入力または出力に関連付けるには、グラフ PLIO の作成時に CSV ファイルを指定する必要があります。

adf::input_plio in = adf::input_plio::create("DataIn", adf::plio_32_bits, "data/input.csv");
adf::input_plio out = adf::output_plio::create("DataOut", adf::plio_32_bits, "data/output.csv");

入力ファイル

AI エンジン シミュレータへの入力 CSV ファイルは、カンマ区切りの複数のデータ列として定義できます。ファイルの最初の行は、ヘッダーです。ヘッダー行は、CMD 列、データ D 列、TLAST 列、TKEEP 列として定義されます。データ D 列の数は、入力されるカーネル データの PLIO バス幅/データ幅と等しくする必要があります。たとえば、次のヘッダーは、PLIO のバス幅が 32 ビット、データ幅が int16 で提供されるデータに対応しています。したがって、ヘッダー行に 2 つのデータ サンプル D 列があります。

CMD, D, D, TLAST, TKEEP

ヘッダー行に続く行にデータ入力を提供するには、DATA コマンドを使用する必要があります。

CMD, D, D, TLAST, TKEEP
DATA, 16, 20, 0, -1
DATA, 15, 11, 0, -1

STALL コマンドは、データ トラフィックに挿入される空サイクル数を指定するために使用する必要があります。このコマンドは、入力トラフィックのバック プレッシャーを模倣するため、実際のデータ入力をシミュレーションするのに役立ちます。

CMD, D, D, TLAST, TKEEP
DATA, 16, 20, 0, -1
DATA, 15, 11, 0, -1
STALL:100

既存の TXT ファイル形式を CSV 形式に変換するには、python スクリプト aiesim_convert_plio_txt2csv.pyを次のように使用します。

$XILINX_VITIS/data/emulation/scripts/aiesim_convert_plio_txt2csv.py -txt <input txt file> --datawidth <n> --buswidth <n>
  • --datawidth <n> オプション: AI エンジン カーネルのデータ幅をビット単位で指定します。このオプションは必須です。
  • --buswidth <n> オプション: PLIO のバス幅をビット単位で指定します。このオプションは必須です。
  • --complex: オプションの引数であり、AI エンジン カーネルのデータ型を複素数型に指定します。
表 1. 入力列
列 説明
CMD

パーサーが処理する定義済みキーワード セット。有効な値は、DATA、STALL:<n>、COMMENT です。

  • DATA: このコマンドの後には、DATA:<n> のように、コロンで区切られたオプションの引数 <n> が続きます。
    • <n> は、AI エンジンへの入力としてデータを何回繰り返す必要があるかを示します。<n> のデフォルト値は 1 です。
  • STALL: このコマンドは空の PL サイクルを表し、STALL:<n> のように、コロンで区切られたオプションの引数 <n> が続きます。
    • STALL:100 と指定すると、100 サイクル間、PL ドメインからデータは駆動されません。PL 周波数が 100 MHz の場合、PL 側から 1000 ns のストール期間が生じます。
    • 引数値 <n> を指定しない場合、STALL のデフォルト値は 1 です。
  • COMMENT: コメントを示します。
D
  • AI エンジン カーネルに送信されるデータ値を、カーネルのデータ幅に基づいて示します。たとえば、INT8 または INT32 です。
  • データ列は、データ幅と PLIO バス幅の組み合わせに基づいて繰り返すことができます。D 列の数は、PLIO buswidth/datawidth と等しくなります。
  • D 列に指定されたデータは、CSV ファイルで指定された順序で AI エンジンに送信されます。
TKEEP

TKEEP 列を使用して、D (データ) 列の処理方法を指定できます。PLIO バス幅によって、TKEEP 列の設定可能な値とその影響は異なります。TKEEP の値は空にできます。空の場合、データ値への影響はありません。

32 ビットの PLIO バス幅:

  • 設定可能な値: 0x0 ～ 0xF
  • 影響: AI エンジン PLIO バス幅が 32 ビットの場合、TKEEP 値は無視されます。

64 ビットの PLIO バス幅:

  • 設定可能な値: 0x0 ～ 0xFF
  • 影響:
    • 0x0 <= TKEEP <= 0x0F → 下位 32 ビットが有効
    • 0x0F < TKEEP <= 0xFF → 64 ビット全体が有効

128 ビットの PLIO バス幅:

  • 設定可能な値: 0x0 ～ 0xFFFF
  • 影響:
    • 0x0000 <= TKEEP <= 0x000F → 下位 32 ビットが有効
    • 0x000F < TKEEP <= 0x00FF → 下位 64 ビットが有効、つまり 2 つの 32 ビット ワードが有効。
    • 0x00FF < TKEEP <= 0x0FFF → 下位 96 ビットが有効、つまり 3 つの 32 ビット ワードが有効。
    • 0x0FFF < TKEEP <= 0xFFFF → 128 ビットすべてが有効、つまり 4 つの 32 ビット ワードが有効。
次の例では、32 ビットのデータ型、64 ビットの PLIO バス幅を表す CSV ファイルについて、TKEEP の適切な組み合わせと、シミュレーション時のその影響 (コメント) を示します。
CMD, D, D, TKEEP, TLAST
COMMENT, All 64 bit is valid
DATA, 1234, 5543, -1, 0
DATA, 1234, 5543, 0x0F, 0
DATA, 1234, 5543, 0xFF, 1
DATA, 1234, 5543, 0xFF, 0

COMMENT, Only lower 32 bit is valid
DATA, 1234, 5543, 0x0F, 1

COMMENT, Empty D column with 0x0<=TKEEP<=0x0F and TLAST=1
COMMENT, Only 1234 is valid
DATA, 1234,  , 0x0F, 1
TLAST
  • TLAST 列は、データ ストリームの最後に達したかどうかを示すために使用されます。TLAST 値が指定されていない場合、値は 0 となります。
  • TLAST 値は、0 または 1 に設定できます。TLAST のデフォルト値は 0 です。
  • TLAST = 1 は、データ ストリームの終わりを示します。
注記: CSV ファイルでは、空の値が指定されていても、列ヘッダーとそれらが対応する値はカンマで区切る必要があります。次に、空の TLAST と TKEEP を含む CSV ファイルの例を示します。
CMD,D,D,TLAST,TKEEP
DATA,3,2, ,
表 2. データ型および PLIO 幅
データ型 PLIO 32 ビット PLIO 64 ビット PLIO 128 ビット
adf::input_plio in = adf::input_plio::create("DataIn1", adf::plio_32_bits, "input.csv"); adf::input_plio in = adf::input_plio::create("DataIn1", adf::plio_64_bits, "input.csv"); adf::input_plio in = adf::input_plio::create("DataIn1", adf::plio_128_bits, "input.csv");
int8 4 つのデータ列が想定されます。次に例を示します。
CMD, D,D,D,D,TKEEP,TLAST
DATA, 6,8,3,2,-1,0
 8 つのデータ列が想定されます。次に例を示します。
CMD, D,D,D,D,D,D,D,D, TKEEP,TLAST
DATA, 6,8,3,2,6,8,3,2, -1,0
 16 のデータ列が想定されます。次に例を示します。
CMD, D,D,D,D,D,D,D,D,D,D,D,D,D,D,D,D, TKEEP,TLAST
DATA, 6,8,3,2,6,8,3,2,6,8,3,2,6,8,3,2, -1,0
int16 2 つのデータ列が想定されます。次に例を示します。
CMD,D,D, TKEEP,TLAST
DATA, 24,18, -1,0
 4 つのデータ列が想定されます。次に例を示します。
CMD, D,D,D,D, TKEEP,TLAST
DATA, 24,18,24,18, -1,0
 8 つのデータ列が想定されます。次に例を示します。
CMD,D,D,D,D,D,D,D,D,TKEEP,TLAST
DATA,24,18,24,18,24,18,24,18,-1,0
int32 1 つのデータ列が想定されます。
CMD, D, TKEEP, TLAST
DATA, 2386, -1, 0
 2 つのデータ列が想定されます。次に例を示します。
CMD, D, D, TKEEP, TLAST
DATA, 2386, 2386, -1, 0
 4 つのデータ列が想定されます。次に例を示します。
CMD,D,D,D,D,TKEEP,TLAST
DATA,2386,2386,2386,2386,-1,0
int64 N/A 1 つのデータ列が想定されます。
CMD, D, TKEEP, TLAST
DATA, 45678, -1, 0
 2 つのデータ列が想定されます。次に例を示します。
CMD, D, D, TKEEP, TLAST
DATA, 45678, 95578, -1, 0
cint16 2 つのデータ列で 1 つの cint 値 (real, imag) を表すことが想定されます。次に例を示します。
CMD, D,D,TKEEP, TLAST
DATA,1980,485,-1,0
 4 つのデータ列で 2 つの cint 値 (実数、虚数) を表すことが想定されます。次に例を示します。
CMD, D,D,D,D, TKEEP, TLAST
DATA, 1980, 45, 180, 85, -1, 0
 8 つのデータ列で 4 つの cint 値 (実数、虚数) を表すことが想定されます。次に例を示します。
CMD, D,D,D,D,D,D,D,D, TKEEP, TLAST
DATA, 1980,485,180,85,980,48,190,45,-1,0
cint32 N/A 2 つのデータ列で 1 つの cint 値 (実数、虚数) を表すことが想定されます。次に例を示します。
CMD, D, D, TKEEP, TLAST
DATA, 1980, 485, -1, 0
 4 つのデータ列で 2 つの cint 値を表すことが想定されます。次に例を示します。
CMD, D, D, D, D, TKEEP, TLAST
DATA, 1980, 45, 180, 85, -1, 0
float 1 つのデータ列が想定されます。次に例を示します。
CMD, D, TKEEP, TLAST
DATA, 893.5689, -1, 0
 2 つのデータ列が想定されます。次に例を示します。
CMD, D, D, TKEEP, TLAST
DATA, 893.5689, 3459.3452, -1, 0
 4 つのデータ列が想定されます。次に例を示します。
CMD, D, D, D, D, TKEEP, TLAST
DATA,893.5689,39.32,459.352,349.345,-1,0
cfloat N/A 2 つのデータ列で 1 つの浮動小数点 cfloat 値を表すことが想定されます。次に例を示します。
CMD, D, D, TKEEP, TLAST
DATA, 893.5689,24156.456, -1, 0
 4 つのデータ列で 2 つの浮動小数点 cfloat 値を表すことが想定されます。次に例を示します。
CMD, D, D, D, D, TKEEP, TLAST
DATA, 893.5689,24156.456,93.689,256.46, -1, 0
bfloat16 2 つのデータ列が想定されます。次に例を示します。
CMD,D,D,TKEEP,TLAST
DATA,3.14062,3.14062,-1,0
 4 つのデータ列が想定されます。次に例を示します。
CMD,D,D,D,D,TKEEP,TLAST
DATA,3.14062,3.14062,3.14062,3.14062,-1,0
 8 つのデータ列が想定されます。次に例を示します。
CMD,D,D,D,D,D,D,D,D,TKEEP,TLAST
DATA,3.14062,3.14062,3.14062,3.14062,3.14062,3.14062,3.14062,3.14062,-1,0
注記: 整数データ型の場合、入力/出力の CSV 形式では 10 進数と 16 進数の両方のデータ形式がサポートされます。16 進数の形式を使用するには、adf::input_plio::create() API で bool hex パラメーターを True に設定してください。詳細は、 『AI エンジン カーネルおよびグラフ プログラミング ガイド』 (UG1076) の input_plio/output_plio を参照してください。
注記: 浮動小数点データ型の場合、入力 CSV ファイルでは浮動小数点と指数の両方のデータ形式がサポートされます。

CSV ファイル形式とシミュレーション時のエラー チェック

CSV に正しくないデータが含まれている場合、AI エンジン シミュレーションの実行時にエラー メッセージが表示されます。次に、CSV ファイルを入力とした場合のシミュレーション時のエラー チェック条件を一部示します。

ヒント: CSV の最初の行は、コメント以外である必要があります。ヘッダーのみとなるようにしてください。
表 3. CSV ファイル エラー
エラーのシナリオ CSV 入力 エラー メッセージ
データ列の数が PLIO のバス幅/データ幅と等しくない たとえば、buswidth = 64 および datawidth = 16 の場合、4 つの D 列が必要です。

D 列が少ない:

CMD, D, D, D, TKEEP, TLAST
DATA, 10, 100, 64, -1, 0
 [ERROR]: In <filename>, number of D columns is less than expected.Expected <expected_number>
D 列が多い:
CMD, D, D, D, D, D, TKEEP, TLAST
DATA, 10, 50, 150, 100, 90, -1, 0
 [ERROR]: In <filename>, number of D columns is more than expected.Expected <expected_number>
CSV のデータ列に部分的なデータしか提供されない たとえば、buswidth = 64、datawidth = 16 の場合、4 つの D 列が必要です。4 つの D 列すべてにデータ サンプルを提供する必要があります。部分的なデータを提供する場合は、TLAST=1 に設定した適切な TKEEP を設定する必要があります。TKEEP の値によって、下位 32 ビットが有効か、または 64 ビットすべてが有効かを指定します。

1 つのデータ サンプルが不足:

CMD, D, D, D, D, TKEEP, TLAST
DATA, 10, 30, 60, , -1, 0

2 つのデータ サンプルが不足:

CMD, D, D, D, D, TKEEP, TLAST
DATA, , , 50, 64, -1, 0
 [ERROR]: In <filename>, in line <linenumber> , partial data is being fed to plio.To feed partial data, provide appropriate TKEEP value with TLAST = 1
CSV ファイルに空の行がある 空の行:
CMD, D, D, D, D, TKEEP, TLAST
This line is ignored by the tool.
CMD 列または D 列に無効な値が指定されている CMD 列の無効なコマンド:
CMD, D, D, D, D, TKEEP, TLAST
DATA:*(#$, 10, 20, 30, 40, -1, 0

D 列の無効なデータ サンプル:

CMD, D, D, D, D, TKEEP, TLAST
DATA, D, 20, 30, 40, -1, 0
CMD, DATA, DATA, DATA, DATA, TKEEP
 [ERROR]: In <filename>, invalid command at <line number>
データ列の順序が正しくない D 列が隣どうしの横並びになっていません (順序が正しくない)。
CMD, D, TKEEP, TLAST, D, D, D
DATA, 10, -1, 0, 20, 30, 40
 [ERROR]: In <filename>, in the header row, DATA columns should be packed together.
特定のデータ型についてデータ値が範囲外となっている たとえば、データ型が int8、バス幅が 32 の場合、データ サンプル 2323 は範囲外となります。

次のデータ値 2323 は範囲外です。

CMD, D, D, D, D, TKEEP, TLAST
DATA, 34, 2323, 23, 21, -1, 0
 [ERROR]: In <filename>, out of range value is present.Datatype is <datatype_provided_from_graph>.Range is <corresponding_range>
提供されるデータ値が無効 D 列の無効なデータ サンプル:
CMD, D, D, D, D, TKEEP, TLAST
DATA, 1.23#$#, 10, 10, 10, -1, 0
 [ERROR]: In <filename>, invalid data value is provided at <line number>.

出力ファイル

入力 CSV ファイルと同様に、PLIO の出力ポートに対して生成される CSV ファイルについても指定できます。シミュレータは、適切な PLIO ポートに対応するシミュレーション出力を、指定された出力 CSV ファイルに書き込みます。

adf::output_plio out1 = adf::output_plio::create("DataOut1",adf::plio_32_bits,"output1.csv");
adf::output_plio out2 = adf::output_plio::create("DataOut2",adf::plio_64_bits,"output2.csv");
adf::output_plio out3 = adf::output_plio::create("DataOut3",adf::plio_128_bits,"output3.csv");

CSV ファイル出力には、TLAST と TKEEP データの両方が含まれます。各出力行にはタイムスタンプも含まれるため、シミュレーション実行時のデータ スループットを見積もることができます。タイムスタンプは、出力 CSV ファイルの最後の列として ns 単位で出力されます。

...
CMD, D, D, TLAST, TKEEP, TIME_NS
DATA:1, 0, 1, 0, -1, 720
DATA:1, 2, 3, 0, -1, 918.4
DATA:1, 4, 5, 0, -1, 1116.8
DATA:1, 6, 7, 0, -1, 1315.2
DATA:1, 8, 9, 0, -1, 1513.6
DATA:1, 10, 11, 0, -1, 1712
DATA:1, 12, 13, 0, -1, 1910.4
DATA:1, 14, 15, 0, -1, 2108.8
DATA:1, 16, 17, 0, -1, 2307.2
DATA:1, 18, 19, 0, -1, 2505.6
DATA:1, 20, 21, 0, -1, 2704
DATA:1, 22, 23, 0, -1, 2902.4
DATA:1, 24, 25, 0, -1, 3100.8
DATA:1, 26, 27, 0, -1, 3299.2
DATA:1, 28, 29, 0, -1, 3497.6
DATA:1, 30, 31, 0, -1, 3696
DATA:1, 32, 33, 0, -1, 3894.4
DATA:1, 34, 35, 0, -1, 4092.8
DATA:1, 36, 37, 0, -1, 4291.2
DATA:1, 38, 39, 0, -1, 4489.6
DATA:1, 40, 41, 0, -1, 4688
DATA:1, 42, 43, 0, -1, 4886.4
DATA:1, 44, 45, 0, -1, 5084.8
DATA:1, 46, 47, 0, -1, 5283.2
DATA:1, 48, 49, 0, -1, 5481.6
DATA:1, 50, 51, 0, -1, 5680
DATA:1, 52, 53, 0, -1, 5878.4
DATA:1, 54, 55, 0, -1, 6076.8
DATA:1, 56, 57, 0, -1, 6275.2
DATA:1, 58, 59, 0, -1, 6473.6
DATA:1, 60, 61, 0, -1, 6672
DATA:1, 62, 63, 0, -1, 6870.4
DATA:1, 0, 1, 0, -1, 7068.8
DATA:1, 2, 3, 0, -1, 7267.2
DATA:1, 4, 5, 0, -1, 7465.6
DATA:1, 6, 7, 0, -1, 7664
DATA:1, 8, 9, 0, -1, 7862.4
DATA:1, 10, 11, 0, -1, 8060.8
DATA:1, 12, 13, 0, -1, 8259.2
DATA:1, 14, 15, 0, -1, 8457.6
...
注記: 浮動小数点データ型の場合、出力ファイルでは指数のデータ形式のみがサポートされます。たとえば、浮動小数点 (32 ビット) データ型の出力 CSV ファイル形式は次のようになります。
CMD, D, TLAST, TKEEP, TIME_NS
DATA:1, 2.002000093e+00, 0, 0, 3264
DATA:1, 4.004000187e+00, 0, 0, 3267.2
DATA:1, 6.006000042e+00, 0, 0, 3270.4
DATA:1, 8.008000374e+00, 0, 0, 3273.6
DATA:1, 1.001000023e+01, 0, 0, 3276.8
DATA:1, 1.201200008e+01, 0, 0, 3280
DATA:1, 1.401399994e+01, 0, 0, 3283.2
DATA:1, 1.601600075e+01, 0, 0, 3286.4
DATA:1, 1.801799965e+01, 0, 0, 3328
DATA:1, 2.002000046e+01, 0, 0, 3331.2
DATA:1, 2.202199936e+01, 0, 0, 3334.4
DATA:1, 2.402400017e+01, 0, 0, 3337.6
DATA:1, 2.602599907e+01, 0, 0, 3340.8
DATA:1, 2.802799988e+01, 0, 0, 3344
DATA:1, 3.003000069e+01, 0, 0, 3347.2
DATA:1, 3.203200150e+01, 0, 0, 3350.4
DATA:1, 3.403400040e+01, 0, 0, 3395.2

Vitis 統合 IDE の [Analysis] ビューでストールを表示

AI エンジンを実行し、シミュレーション トレース データの生成を選択した後、CSV ファイルで STALL コマンドを使用すると、Vitis 統合 IDE でシミュレーション実行サマリを開いてストールを表示させることができます。STALL:<n> は、PL ドメインから n の空サイクル間ストールを挿入します。PL 周波数に基づいたストール期間を確認できます。たとえば、PL 周波数が 100 MHz の場合、STALL:100 は 1000 ns 間、PL から 100 の空サイクルを挿入します。

例 1: 直接ストリーム接続 (バッファーなし) を使用するデザインでは、指定された 500 空サイクル (PL ドメインから) のストリーム ストールが発生します。

図 1. 500 空サイクルのストールが発生する CSV エントリ

図 2. Vitis 統合 IDE の [Analysis] ビューに表示される 500 空サイクルのストリーム ストール

例 2: バッファーを介してストリームが接続されているデザインでは、指定された 1000 空サイクル (PL ドメインから) のロック ストールが発生します。

図 3. 1000 空サイクルのストールが発生する CSV エントリ
図 4. Vitis 統合 IDE の [Analysis] ビューに表示される 1000 空サイクルのロック ストール