サンプル アプリケーション

プラットフォームには、プラットフォームの使用法を示すサンプル アプリケーションをオプションで含めることができます。この場合、サンプル アプリケーションは、プラットフォームの samples ディレクトリに含まれます。各サンプル アプリケーションは、典型的な SDSoC プラットフォームのディレクトリ構造および description.json で説明されるように、samples の下位ディレクトリに含まれます。

次に、<SDX_Install_Dir>/samples/platforms/arty/samples/arty_arraycopy フォルダーの Arty プラットフォームの array_copy サンプル アプリケーション description.json を示します。

{
    	"example": "Arraycopy",
    	"overview": "Implementation of an array copy core that simply reads from one array and 
   	 writes to another. By default the function arraycopy() is marked for hardware and you
    	can build the project."
    	"board": [ "arty" ],
    	"os": [  "Standalone" ],
    	"runtime": [  "C/C++" ],
    	"accelerators": [ 
        {
            "name": "arraycopy",
            "location": "arraycopy.cpp"
        }
    ],
    "contributors" : [
        {
            "group" : "Xilinx, Inc.",
            "url" : "http://www.xilinx.com"
        }
    ],
    "revision" : [
        {
            "date" : "2018",
            "version" : "1.0",
            "description" : "Initial revision"
        }
    ]
}
description.json ファイルは JSON 形式で、キーと値の組み合わせがカンマで区切られます。JSON 値は、文字列、配列、または入れ子になった JSON オブジェクトになります。上記の例には、次の情報が含まれます。
  • 名前と説明: example (名前) は必須で、overview (説明) は推奨です。
  • プラットフォーム: board はオプションですが、os および runtime は必須です。
  • アクセラレータ: ハードウェア関数名とソース コード ファイルのディレクトリを指定する必要があります。
  • コントリビューター: オプションでソース コード提供者の名前と説明を示します。
  • リビジョン: オプションでバージョン情報を示します。

次の表は、使用可能な属性のリストを示しています。

表 1. description.json 属性
属性 説明
"example" GUI に表示される名前。
"overview" GUI に表示される説明。
"type" ライブラリ プロジェクトなのかアプリケーション プロジェクトなのかを表示。
"board" サポートされるプラットフォームのリスト。指定する場合、プロジェクト プラットフォームはリストのエントリと一致する必要あり。
"os" サポートされるオペレーティング システムのリスト。
"runtime" サポートされるランタイム環境のリスト。
"accelerators" ハードウェア関数名およびソース ファイルのリスト。
"exclude" サンプル プロジェクトにコピーしないファイルおよびディレクトリのリスト。
"compiler" コンパイラ オプションおよびインクルード ディレクトリを指定するための設定。
"linker" リンカー オプション、ライブラリ パス、およびライブラリを指定するための設定。
"system" システム レベルの設定。
"cmd_args" GUI の起動時に使用されるコマンド ライン引数。
"revision" リビジョンのリスト。
"contributors" サンプルの提供者/記述者のリスト。

"example" 属性では、SDx™ GUI に表示するサンプル アプリケーションの名前を定義します。わかりやすい記述にする必要はありますが、長くなりすぎないようにしてください。
"example" : "Array Copy"

概要

"overview" 属性は、サンプル アプリケーションの長いテキスト記述です。値は、1 つの文字列または複数の文字列にできます。
  • 1 つの文字列
    "overview" : "Shows a __median filter__ function accelerated in hardware."
  • 複数の文字列
    "overview" : [
        "This is the first line of the description.",
       "The description supports limited Markdown syntax,",
        "including __bold__, _italics_, and ~~strikethrough~~.",
        "- list item 1",
        "- list item 2",
    ]
ヒント: この説明では、太字/斜体など、および番号付きまたは箇条書きのリストのみがサポートされます。

type

オプションの type 属性では、この example でアプリケーション プロジェクトまたはライブラリ プロジェクトのどちらを作成するかを示します。type 値が library の場合、共有のライブラリ プロジェクトが作成されます。それ以外の場合は、アプリケーション プロジェクトが作成されます。
"type" : "library"

board

board 属性には、このサンプルと互換性のあるすべての開発ボード プラットフォームがリストされます。board 属性がない場合、このサンプルはどのプラットフォームでも使用できます。サンプル アプリケーションは、現在のプラットフォームがリスト内の値のどれかと一致すると使用できます。サンプルがカスタム プラットフォームと一緒に含まれる場合は、そのカスタム プラットフォームにしか使用できないので、board を指定する必要はありません。
"board" : [
    "zc702",
    "zc706"
]

os

os 属性は、選択した SDSoC™ プラットフォームに対応するオペレーティング システムを定義します。OS 値は、Linux、スタンドアロン、FreeRTOS などのサポートされるオペレーティング システムのリストになります。サンプル アプリケーションは、現在のオペレーティング システムがリスト内の値のどれかと一致すると使用できます。

次の例では、Linux、スタンドアロン、または FreeRTOS のいずれかを選択したときにオペレーティング システムとして選択可能なアプリケーションを定義しています。
"os" : [
    "Linux",
    "Standalone",
    "FreeRTOS"
]

runtime

runtime 属性は C/C++ など、この例でサポートされるランタイム環境を定義します。サンプル アプリケーションは、プロジェクトのランタイムがリストの値のどれかと一致すると使用できます。たとえば、上記のサンプルの場合、OpenCL ランタイムで動作しますが、C/C++ ランタイムでは動作しません。

次の例では、ランタイムが C/C++ の場合に選択可能なアプリケーションを定義しています。
"runtime" : [
    "C/C++"
]

accelerators

オプションの Accelerators 属性は、新規プロジェクトを作成する際に設定されるハードウェア関数のリストです。Accelerators 属性には、複数の必須およびオプションのサブタグが含まれます。
  • name: 関数の名前を指定する必須の値。
  • location: 関数を含むソース ファイルへのパスを指定する必須の値。このパスは、プラットフォーム内のサンプル アプリケーション フォルダーに対して相対的に指定します。
  • clkid: デフォルトの代わりに使用するアクセラレータ クロックを指定するオプションの値。
  • hlsfiles: アクセラレータ呼び出しコードがほかのファイルで見つかった場合に、ソース ファイルと一緒にコンパイルされるその他のファイルのリストを指定するオプションの値。SDSoC 環境からは Vivado® HLS が起動し、その関数を含むソース ファイルがコンパイルされます。ソース ファイルがその他のソース ファイルに含まれる関数によって異なる場合、hlsfile でそれらのソース ファイルを指定します。
次の例では、新規プロジェクトを作成したときに、2 つの関数 func1 および func2 がハードウェアに移動するよう指定されます。
"accelerators" : [
    {
        "name" : "func1",
        "location" : "func1.cpp"
    },
    {
        "name" : "func2",
        "location" : "func2.cpp",
        "clkid” : "2",
        "hlsfiles" : [
            "func2_helper_a.cpp",
            "func2_helper_b.cpp"
        ]
    }
]

compiler

compiler 属性はオプションで、次のコンパイラ オプションを指定するのに使用します。
  • includepaths: -I オプションを使用して sds++ コンパイラに渡されるサンプル アプリケーション フォルダーへの相対的なパスのセットを定義します。
  • options: 新規プロジェクトを作成する際のコンパイラのアプリケーション プロジェクト設定を定義します。この値は、アプリケーションをビルドするのに必要なコンパイラ オプションを定義し、SDx 環境の [C/C++ Build Settings] ダイアログ ボックスの [Software Platform] の下にコンパイラの [Inferred Options] ボックスとして表示されます。
  • symbols: プリプロセッサ シンボルのリストを定義します。Eclipse プロジェクト ビルド設定でシンボルをシンボル リストに表示する場合に options の代わりに使用します。
次の例では、SDSoC 環境で -I"../src/myinclude" -I"../src/dir/include" およびコンパイラ オプション -D MYAPPMACROcompiler コマンドに追加されます。
"compiler" : {
    "includepaths” : [
        "myinclude",
        "dir/include"
    ]
    "options" : "-D MYAPPMACRO"
}

linker

linker 属性はオプションで、リンク パスに指示子を追加したり、リンクするライブラリを追加するために使用します。複数のリンカー設定を使用する場合は、それらを同じ linker ノードに追加する必要があります。
  • librarypaths: アプリケーション ビルド ディレクトリ (コンパイルされたアプリケーションのディレクトリ) への相対パスのリストを指定します。指定したパスは -L オプションを使用してリンカーに渡されます。
  • libraries: リンカーに -l オプションを使用して渡される追加ライブラリを定義します。
  • options: 新規プロジェクトを作成する際のリンカーのアプリケーション プロジェクト設定を定義します。値は、アプリケーションをビルドするのに必要なリンカー オプションを定義し、SDx 環境の [C/C++ Build Settings] ダイアログ ボックスにリンカーの [Miscellaneous] オプションとして表示されます。

    SDSoC プロジェクトの場合、sdcard 属性を sds++ -sdcard <path> オプションを指定するために使用します。SD カード パスはビルド ディレクトリに相対的に指定します。

次の設定は、-lmylib1 -lmylib2 および -L"mylibrary" オプションを追加し、リンカー コマンド ラインに -poll-mode 1 リンカー オプションを追加し、-sdcard パスを指定しています。
"linker": {
    "options" : "-poll-mode 1",
    "libraries" : [
        "mylib1"
        "mylib2"
    ],
    "librarypaths" : [
        "mylibrary"
    ]
    "sdcard" : "../sdcard"
}

exclude

exclude 属性は、SDx で新規プロジェクトを作成する際にコピーしないディレクトリとファイルを定義します。これにより、アプリケーションのビルドに必要ないサンプル アプリケーション フォルダー内のファイルまたはディレクトリを除外できます。

次の例では、SDSoC で新規プロジェクトを作成したときに、MyDir および MyOtherDir ディレクトリがコピーされないほか、MyFile.txt および MyOtherFile.txt ファイルもコピーされません。
"exclude" : [
    "MyDir",
    "MyOtherDir",
    "MyFile.txt",
    "MyOtherFile.txt"
]

system

オプションの system 属性は、新規プロジェクトを作成する際のシステムのアプリケーション プロジェクト設定を定義します。dmclkid 属性は、データ モーション クロック ID を定義します。system 属性が指定されていない場合は、データ モーション クロックにデフォルトのクロック ID が使用されます。

次の例では、SDx で新規プロジェクトを作成したときに、データ モーション クロック ID がデフォルトのクロック ID ではなく 2 に設定されます。
"system" : {
    "dmclkid" : “2”
}

cmd_args

オプションの cmd_args は、SDSoC アプリケーションを起動したときのカスタム コマンド ラインを定義します。cmd_args に使用できる変数は、次のとおりです。
  • PROJECT はプロジェクト ディレクトリへのパスに置換されます。
  • BUILD はビルド ディレクトリへのパスに置換されます。

これらの変数は、プロジェクト ルートのデータ ファイルまたはビルド出力ファイルを指定するのに使用できます。

revision

revision 属性はオプションで、サンプル アプリケーションのリビジョンを履歴と共に提供します。この属性には、複数のオプションのサブタグが含まれます。
  • date: サンプル アプリケーションの日付を示すユーザー指定の文字列。
  • version: アプリケーションのバージョンを major.minor[.update] のように数値をピリオドで区切った文字列。たとえば、1.0 または 2.5.1 などのようにします。サンプル アプリケーションが複数バージョンをリストする場合は、大きな数値の方が最新バージョンです。
  • description: リビジョンの簡単な説明を示す文字列。
次は、サンプル アプリケーションの簡単な履歴を示しています。
"revision" : [
    {
        "date" : "2017",
        "version" : "1.2",
        "description" : "Updated the example for the 17.1 release"
    },
    {
        "date" : "2018",
        "version" : "1.0",
        "description" : "original release"
    }
]

contributors

contributors 属性はサンプルの提供者のリストで、次のサブタグが含まれます。
  • group: サンプル アプリケーションの開発者の名前を指定する文字列。
  • url: 提供者の URL を指定。
次に例を示します。
"contributors" : [
    {
        "group" : "Xilinx, Inc.",
        "url" : "http://www.xilinx.com/"
    }
]