インテル® FPGA SDK for OpenCL™プロ・エディション: プログラミング・ガイド

ID 683846
日付 4/01/2019
Public
ドキュメント目次

5.5.6.2. ホストがアクセス可能なパイプカーネル引数にバインドされたcl_memパイプ・オブジェクトと通信するためのAPI関数

clReadPipeIntelFPGAclWritePipeIntelFPGAclMapHostPipeIntelFPGAclUnmapHostPipeIntelFPGAのホストAPI関数を追加すると、ホストプログラムは、ホストがアクセス可能なパイプカーネル引数に (clSetKernelArg引数を使用し) バインドされたcl_memパイプ・オブジェクトに読み書きできるようになります。
  • clReadPipeIntelFPGAおよびclWritePipeIntelFPGA関数は、パイプ幅のシングルワードで動作します。
  • clMapHostPipeIntelFPGA関数は、ホストパイプで多数のワードの読み取りまたは書き込みを実行する際のレイテンシーとオーバーヘッドを低減する高度なメカニズムです。
  • clUnmapHostPipeIntelFPGA関数を使用すると、ホストプログラムは、先にclMapHostPipeIntelFPGA関数呼び出しが作成したマップ領域の一部、または全体に、書き込みもしくは読み出しを行ったことをOpenCLランタイムに通知することができるようになります。
表 1.  バインドされたcl_memオブジェクトのAPI関数
関数 説明
cl_int clReadPipeIntelFPGA (cl_mem pipe, 
                            gentype *ptr);

以下の特性を持つパイプからデータパケットを読み取ります。

  1. CL_MEM_HOST_READ_ONLYフラグで作成されている
  2. write_only定義とintel_host_accessibleカーネル引数属性を持つカーネル引数にバインドされている

clReadPipeIntelFPGA関数呼び出しは、1パケットをパイプから読み取ります。動作はノンブロッキングであり、データがパイプ内で正常に読み取れるようになるまで待機しません。

cl_int clWritePipeIntelFPGA (cl_mem pipe, 
                             gentype *ptr);

次の特性を持つパイプにデータパケットを書き込みます。

  1. CL_MEM_HOST_WRITE_ONLYフラグを使用し作成されている
  2. read_only定義とintel_host_accessible引数属性を持つカーネル引数にバインドされている

clWritePipeIntelFPGA関数呼び出しは、1パケットをパイプに書き込みます。動作はノンブロッキングであり、正常に書き込める容量がパイプにできるまで待機しません。返されるステータスのCL_SUCCESSは、カーネルの読み取りにデータが利用可能なことを意味するわけではありません。ホストパイプに以前にマップされたバッファーのマップが解除されると、データは最終的にカーネルの読み取りに利用可能になります。

void * clMapHostPipeIntelFPGA (cl_mem pipe,
                               cl_map_flags map_flags,
                               size_t requested_size,
                               size_t * mapped_size,
                               cl_int * errcode_ret);

ホストアドレス空間に、void *を返します。CL_MEM_HOST_WRITE_ONLYフラグで作成されている場合、パイプはこのアドレス空間にデータを書き込むことができます。また、CL_MEM_HOST_READ_ONLYフラグで作成されている場合、パイプはこのアドレス空間からデータを読み取ることができます。

mapped_size引数は、メモリーのランタイムによって決定する、ホストがアクセス可能な最大バイト数を指定します。mapped_sizeで指定される値は、呼び出し側が指定するrequested_size引数以下の値になります。

返されたvoid *に対する読み出しまたは書き込み後、ホストは1回以上のclUnmapHostPipeIntelFPGA関数呼び出しを実行し、デバイスに転送するデータが準備できていること (書き込み時) および、メモリーを再利用できること (読み込みおよび書き込みに時) をランタイムに通知する必要があります。前回のclMapHostPipeIntelFPGA関数呼び出しでマッピングされたメモリーを、clUnmapHostPipeIntelFPGA関数が解除する前に新たにclMapHostPipeIntelFPGA関数が呼び出された場合、2回目のclMapHostPipeIntelFPGA関数呼び出しで返されるバッファーは、最初の呼び出しで返されたバッファーと重複しません。

cl_int clUnmapHostPipeIntelFPGA (
                            cl_mem pipe, 
                            void * mapped_ptr,
                            size_t size_to_unmap,
                            size_t * unmapped_size
							);
clMapHostPipeIntelFPGA関数によって返された、ホストがアドレス指定可能なバッファーのsize_to_unmapバイトを、ホストがすでに使用していないことをランライムに通知します。書き込み可能なホストパイプの場合、clUnmapHostPipeIntelFPGAを呼び出すと、マッピングが解除されたデータをカーネルが利用できるようになります。size_to_unmapの値がclMapHostPipeIntelFPGA関数で指定されたmapped_sizeの値より小さい場合、clUnmapHostPipeIntelFPGA関数を複数回呼び出し、バッファー全容量のマッピングを解除する必要があります。clUnmapHostPipeIntelFPGA関数呼び出しを複数回含め、clMapHostPipeIntelFPGA関数呼び出しで返されたバッファーの一連のバイトのマッピングを、clMapHostPipeIntelFPGA呼び出しで定義されたmapped_sizeの値まで解除することができます。