エントリポイント関数の入力のプロパティの指定

入力プロパティを指定しなければならない理由

Fixed-Point Designer™ は MATLAB^® ファイル内のすべての変数のプロパティをコンパイル時に判別しなければなりません。MATLAB ファイル内の変数のプロパティを推定するために、Fixed-Point Designer は、"基本" 関数 ("最上位" 関数または "エントリポイント" 関数としても知られる) への入力のプロパティを特定できなければなりません。そのため、基本関数に入力がある場合は、これらの入力のプロパティを Fixed-Point Designer に指定しなければなりません。基本関数が入力パラメーターをもたない場合は、Fixed-Point Designer では MATLAB ファイルを修正せずにコンパイルできます。基本関数から呼び出されるローカル関数または外部関数に対する入力のプロパティは指定する必要はありません。

メモ

基本関数をパッケージ内に含めることはできません。パッケージ外にラッパー関数を基本関数として作成します。新しい関数内の目的の関数を基本関数として呼び出します。

指定するプロパティ

基本関数が入力をもつ場合は、入力ごとに次のプロパティを指定しなければなりません。

対象	指定するプロパティ
	クラス	サイズ	実数/複素数	numerictype	fimath
固定小数点入力
構造体の入力の各フィールド	クラスに応じた各フィールドのプロパティの指定基本入力が構造体のときは、コードジェネレーターは各フィールドを個別の入力として扱います。そのため、基本構造体入力のすべてのフィールドに対して、構造体の定義で指定されている順番で、プロパティを指定しなければなりません。入力構造体の各フィールドに、クラス、サイズおよび実数/複素数を指定します。また、固定小数点クラスである各フィールド、`numerictype` と `fimath` を指定します。
その他の入力

既定のプロパティ値

Fixed-Point Designer では基本関数入力のプロパティに対して次の既定値が割り当てられます。

プロパティ	既定値
クラス	`double`
サイズ	`scalar`
実数/複素数	`real`
`numerictype`	既定値なし
`fimath`	MATLAB 既定の `fimath` オブジェクト

サポートされているクラス

以下の表に Fixed-Point Designer でサポートされているクラス名を示します。

クラス名	説明
`logical`	真および偽の値の論理配列
`char`	文字配列
`int8`	8 ビット符号付き整数配列
`uint8`	8 ビット符号なしの整数配列
`int16`	16 ビット符号付き整数配列
`uint16`	16 ビット符号なしの整数配列
`int32`	32 ビット符号付き整数配列
`uint32`	32 ビット符号なしの整数配列
`int64`	64 ビット符号付き整数配列
`uint64`	64 ビット符号なしの整数配列
`single`	単精度浮動小数点または固定小数点の数値配列
`double`	倍精度浮動小数点または固定小数点の数値配列
`struct`	構造体配列
`embedded.fi`	固定小数点の数値配列

基本入力のプロパティの指定規則

基本入力のプロパティを指定するときは次の規則に従います。

cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。
MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。
MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を -args に渡します。
クラスが固定小数点 (fi) である基本関数入力ごとに、入力の numerictype と fimath プロパティを指定します。
クラスが struct である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。

基本入力のプロパティの定義方法

方法	利点	不便な点
	プロジェクトで作業している場合は、使用が簡単。元の MATLAB コードを変更しない。プロジェクトファイル内に定義を保存する。	大規模な構造体や配列など、大量のメモリを使用する入力を指定する場合は効率的でない。
コマンドラインでの例による入力プロパティの定義メモ MATLAB ファイルでプログラムによって入力プロパティを定義する場合は、この方法は使用できません。	使いやすい。元の MATLAB コードを変更しない。少数の基本入力をもつ関数のプロトタイプを作成するために設計されている。	`fiaccel` を起動するたびにコマンドラインで指定しなければならない (スクリプトを使用しない場合)。大規模な構造体や配列など、大量のメモリを使用する入力を指定する場合は効率的でない。
MATLAB ファイル内でのプログラムによる入力プロパティの定義 (MATLAB Coder)	MATLAB コードと統合されているため、呼び出すたびにプロパティを再定義する必要がない。 MATLAB コード内にプロパティ指定のドキュメンテーションが提供されている。大きな構造体などメモリを大量に使用する入力を指定する場合に効率的である。	複雑な構文を使用する。プロジェクトファイルは、現在、プログラムで定義されたプロパティを認識しない。プロジェクトを使用する場合は、入力の型をプロジェクトに再入力しなければならない。

コマンドラインオプション -args

関数 fiaccel には、基本 (エントリポイント) 関数の入力のプロパティを、値または型の例の cell 配列で指定する -args コマンドラインオプションがあります。cell 配列は、可変またはリテラル配列の一定値を使用できます。このオプションを使用することで、fiaccel を使用して MATLAB 関数のコードを生成すると同時に、入力のプロパティを指定します。

coder.Type オブジェクトは、コード生成の型エディターを使用して対話形式で作成することもできます。コード生成の型エディターを使用した入力の型の作成と編集 (MATLAB Coder)を参照してください。

-args オプションを使用する場合の規則

-args コマンドラインオプションを使用して、例によってプロパティを定義するには次の規則に従います。

cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。
MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。
MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を -args に渡します。
クラスが固定小数点 (fi) である基本関数入力ごとに、入力の numerictype と fimath プロパティを指定します。
クラスが struct である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。

例による基本入力のプロパティの指定

2 つの入力を追加する関数を考えてみます。

function y = emcf(u,v) %#codegen
% The directive %#codegen indicates that you
% intend to generate code for this algorithm
y = u + v;

次の例では、コマンドラインで例によって基本入力 u と v で異なるプロパティを指定する方法を示します。

定数のリテラル cell 配列を使用して、両方の入力が実数スカラーの固定小数点値であるように指定します。
```
fiaccel -o emcfx emcf ...
   -args {fi(0,1,16,15),fi(0,1,16,15)}
```
定数のリテラル cell 配列を使用して、入力 u が符号なし 16 ビットの 1 行 4 列のベクトル、入力 v がスカラーの固定小数点値であるように指定します。
```
fiaccel -o emcfx emcf ...
   -args {zeros(1,4,'uint16'),fi(0,1,16,15)}
```
サンプル値を cell 配列変数に代入し、両方の入力が実数で符号なし 8 ビットの整数ベクトルであるように指定します。
```
a = fi([1;2;3;4],0,8,0)
b = fi([5;6;7;8],0,8,0)
ex = {a,b}
fiaccel -o emcfx emcf -args ex
```

例による基本固定小数点入力のプロパティの指定

固定小数点数の平方根を計算する関数を考えてみます。

function y = sqrtfi(x) %#codegen
y = sqrt(x);

MATLAB コマンドライン上で例によって基本固定小数点入力 x のプロパティを指定するには、以下の手順に従います。

次の例のように、x の numerictype プロパティを定義します。
```
T = numerictype('WordLength',32,...
   'FractionLength',23,'Signed',true);
```

次の例のように、x の fimath プロパティを定義します。

F = fimath('SumMode','SpecifyPrecision',...
    'SumWordLength',32,'SumFractionLength',23,...
    'ProductMode','SpecifyPrecision', ...
     ProductWordLength',32,'ProductFractionLength',23);

次の例のように、定義した numerictype と fimath プロパティをもつ固定小数点変数を作成します。
```
myeg = { fi(4.0,T,F) };
```
次の例のように、fiaccel コマンドを使用して、変数 myeg を -args オプションの引数として渡して、関数 sqrtfi をコンパイルします。
```
fiaccel sqrtfi -args myeg;
```

コマンドラインでの定数入力の指定

基本入力が実行時に変化しないことがわかっている場合、基本入力を定数値として指定することで、生成されたコードのオーバーヘッドを削減できます。定数入力は、通常、アルゴリズムの実行方法を制御するフラグや、データのサイズや型を指定する値に使用されます。

入力に定数を指定するには、-args コマンドラインオプションを coder.Constant オブジェクトと共に使用します。入力に constant_input のサイズ、クラス、実数/複素数および値をもつ定数を指定するには、以下の構文を使用します。

-args {coder.Constant(constant_input)}

定数入力をもつ関数の呼び出し

fiaccel では、生成されるコードに関数への定数入力がコンパイルされます。このため、MEX 関数のシグネチャは MATLAB 関数のシグネチャとは異なります。実行時には、MEX 関数ではなく、MATLAB 関数への定数引数を提供します。

たとえば、入力を出力にコピーする関数 identity を考えてみます。

function y = identity(u) %#codegen
y = u;

定数入力をもつ MEX 関数 identity_mex を生成するには、MATLAB プロンプトで次のコマンドを入力します。

fiaccel -o identity_mex identity...
    -args {coder.Constant(fi(0.1,1,16,15))}

MATLAB 関数を実行するには、定数引数を次のように提供します。

identity(fi(0.1,1,16,15))

次の結果が得られます。

ans =

    0.1000

次に、以下のコマンドを使用して MEX 関数を実行してみます。

identity_mex

ここでも結果は同じになります。

定数入力として構造体を指定

次のように、MATLAB ワークスペースに構造体 tmp を定義することで行列の次元を指定するとします。

tmp = struct('rows', 2, 'cols', 3);

次の MATLAB 関数 rowcol は、構造体入力 p を受け取って行列 y を定義します。

function y = rowcol(u,p) %#codegen
y = fi(zeros(p.rows,p.cols),1,16,15) + u;

次の例は、基本入力 u が double スカラー変数で、基本入力 p が定数構造体であることを指定する方法を示しています。

fiaccel rowcol ...
   -args {fi(0,1,16,15),coder.Constant(tmp)}

このコードを実行するには、以下を使用します。

u = fi(0.5,1,16,15)
y_m = rowcol(u,tmp)

y_mex = rowcol_mex(u)

コマンドラインでの可変サイズ入力の指定

可変サイズデータは実行時にサイズが変わる可能性のあるデータです。MATLAB では、コード生成に対して制限付きと制限なしの可変サイズデータがサポートされています。"制限付き可変サイズデータ" には上限が設定されています。このデータはスタックで静的に割り当てることも、ヒープで動的に割り当てることもできます。"制限なしの可変サイズデータ" には上限が設定されていません。このデータはヒープで割り当てなければなりません。-args オプションと関数 coder.typeof を使用すると、入力が 1 つ以上の可変サイズの次元をもつように定義し、その上限を指定できます。

-args {coder.typeof(example_value, size_vector, variable_dims)}

可変サイズ入力を次のように指定します。

example_value と同じクラスと実数/複素数
size_vector と同じサイズと上限
variable_dims によって指定された可変次元

動的メモリ割り当てが有効な場合は、コンパイル時に、上限が不明な次元のサイズベクトルで Inf を指定できます。

variable_dims がスカラーの場合は、次の例外を除き、すべての次元に適用されます。

次元が 1 または 0 の場合は、固定
次元が制限なしの場合は、常に可変サイズ

可変サイズベクトル入力の指定

ベクトル A の各 n 要素の和を計算し、ベクトル B に格納する関数を作成します。

function B = nway(A,n) %#codegen
% Compute sum of every N elements of A and put them in B.

coder.extrinsic('error');
Tb = numerictype(1,32,24);
if ((mod(numel(A),n) == 0) && ...
  (n>=1 && n<=numel(A)))
    B = fi(zeros(1,numel(A)/n),Tb);
    k = 1; 
    for i = 1 : numel(A)/n
        B(i) = sum(A(k + (0:n-1)));
        k = k + n;
    end
else
    B = fi(zeros(1,0),Tb);
    error('n<=0 or does not divide evenly');
end

最初の入力 A を fi オブジェクトとして指定します。最初の次元のサイズは固定ですが、2 番目の次元は上限 100 まで増やせます。2 番目の入力 n を double スカラーとして指定します。
```
fiaccel nway ...
-args {coder.typeof(fi(0,1,16,15,'SumMode','KeepLSB'),[1 100],1),0}...
-report
```
また、この代わりに、coder.typeof の式を MATLAB 変数に代入し、この変数を -args に引数として渡すこともできます。
```
vareg = coder.typeof(fi(0,1,16,15,'SumMode','KeepLSB'),[1 100],1)
fiaccel nway -args {vareg, double(0)} -report
```

入力の型の指定と `arguments` ブロック

関数の引数の検証 (arguments ブロック) を使用してエントリポイント関数の入力の型を指定することはサポートされていません。エントリポイント関数に入力引数を検証する arguments ブロックが含まれている場合も、基本入力のプロパティの定義方法 (MATLAB Coder)に示す 3 つの方法のいずれかを使用して、それらの入力引数のプロパティを指定する必要があります。

生成コード内のエントリポイント関数の入力の既定値

arguments ブロックを使用すると、1 つ以上の位置入力引数の既定値を指定できます。引数の宣言で既定値を指定すると、関数呼び出しで値を渡さない場合に MATLAB で既定値を使用できるため、位置引数はオプションになります。codegen (MATLAB Coder) コマンドを使用してコードを生成する場合や fiaccel コマンドを使用して固定小数点コードを高速化する場合に、一定の既定値をもつ 1 つ以上のオプションの位置引数について、そのプロパティを指定しないように選択できます。このような場合、それらのオプションの引数の既定値が生成コードにハードコードされ、それらの引数は生成コードのインターフェイスに表示されません。例については、次の表を参照してください。

MATLAB コード	生成コード
function out = useDefaults_1(a,b,c) arguments a (1,1) double = 3 b (1,1) double = 5 c (1,1) double = 7 end out = a + b + c; end	`codegen` コマンド: codegen -config:lib -c useDefaults_1 -args {} -report 生成コード: double useDefaults_1(void) { return 15.0; }
function out = useDefaults_2(a,b,c) arguments a (1,1) double b (1,1) double = 5 c (1,1) double = 7 end out = a + b + c; end	`codegen` コマンド: codegen -config:lib -c useDefaults_2 -args 0 -report 生成コード: double useDefaults_2(double a) { return (a + 5.0) + 7.0; }
`codegen` コマンド: codegen -config:lib -c useDefaults_2 -args {0,0} -report 生成コード: double useDefaults_2(double a, double b) { return (a + b) + 7.0; }

MATLAB コード

生成コード

function out = useDefaults_1(a,b,c)
arguments
    a (1,1) double = 3
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen コマンド:

codegen -config:lib -c useDefaults_1 -args {} -report

生成コード:

double useDefaults_1(void)
{
  return 15.0;
}

function out = useDefaults_2(a,b,c)
arguments
    a (1,1) double
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen コマンド:

codegen -config:lib -c useDefaults_2 -args 0 -report

生成コード:

double useDefaults_2(double a)
{
  return (a + 5.0) + 7.0;
}

codegen コマンド:

codegen -config:lib -c useDefaults_2 -args {0,0} -report

生成コード:

double useDefaults_2(double a, double b)
{
  return (a + b) + 7.0;
}

方法	利点	不便な点
	プロジェクトで作業している場合は、使用が簡単。元の MATLAB コードを変更しない。プロジェクトファイル内に定義を保存する。	大規模な構造体や配列など、大量のメモリを使用する入力を指定する場合は効率的でない。
コマンドラインでの例による入力プロパティの定義メモ MATLAB ファイルでプログラムによって入力プロパティを定義する場合は、この方法は使用できません。	使いやすい。元の MATLAB コードを変更しない。少数の基本入力をもつ関数のプロトタイプを作成するために設計されている。	`fiaccel` を起動するたびにコマンドラインで指定しなければならない (スクリプトを使用しない場合)。大規模な構造体や配列など、大量のメモリを使用する入力を指定する場合は効率的でない。
MATLAB ファイル内でのプログラムによる入力プロパティの定義 (MATLAB Coder)	MATLAB コードと統合されているため、呼び出すたびにプロパティを再定義する必要がない。 MATLAB コード内にプロパティ指定のドキュメンテーションが提供されている。大きな構造体などメモリを大量に使用する入力を指定する場合に効率的である。	複雑な構文を使用する。プロジェクトファイルは、現在、プログラムで定義されたプロパティを認識しない。プロジェクトを使用する場合は、入力の型をプロジェクトに再入力しなければならない。