エントリポイント関数の入力のプロパティの指定
入力プロパティを指定しなければならない理由
C および C++ は静的型付き言語であるため、MATLAB® Coder™ ではコンパイル時に MATLAB ファイル内の変数すべてのプロパティを決定しなければなりません。MATLAB ファイル内の変数のプロパティを推定するために、MATLAB Coder は、"基本" 関数 ("最上位" 関数または "エントリポイント" 関数としても知られる) への入力のプロパティを特定できなければなりません。そのため、基本関数に入力がある場合は、これらの入力のプロパティを MATLAB Coder に指定しなければなりません。基本関数が入力パラメーターをもたない場合は、MATLAB Coder では MATLAB ファイルを修正せずにコンパイルできます。基本関数から呼び出されるローカル関数または外部関数に対する入力のプロパティは指定する必要はありません。
メモ
基本関数をパッケージ内に含めることはできません。パッケージ外にラッパー関数を基本関数として作成します。新しい関数内で望ましい関数を基本関数として呼び出します。
チルダ (~) 文字を使用して未使用の関数入力を指定する場合は、以下を行います。
MATLAB Coder プロジェクトで、生成されるコードに異なる型を表示させる場合は、その型を指定します。それ以外の場合は、入力は既定で実数のスカラーの double になります。
codegen
を使用してコードを生成する場合は、-args
オプションを使用してこれらの入力の型を指定しなければなりません。
指定するプロパティ
基本関数が入力をもつ場合は、入力ごとに次のプロパティを指定しなければなりません。
対象 | 指定するプロパティ | ||||
---|---|---|---|---|---|
クラス | サイズ | 実数/複素数 | numerictype | fimath | |
固定小数点入力 |
|
|
|
|
|
構造体の入力の各フィールド | |||||
その他の入力 |
|
|
|
既定のプロパティ値
MATLAB Coder では基本関数入力のプロパティに対して次の既定値が割り当てられます。
プロパティ | 既定値 |
---|---|
クラス | double |
サイズ | scalar |
実数/複素数 | real |
numerictype | 既定値なし |
fimath | MATLAB 既定の fimath オブジェクト |
構造体フィールドに対する既定値の指定. ほとんどの場合、プロパティに対して明示的に値が指定されていないときは、MATLAB Coder では、構造体フィールドを除き、既定値が使用されます。構造体内のフィールドに名前を付けるには、そのプロパティの少なくとも 1 つを設定することが唯一の方法です。したがって、構造体フィールドのプロパティに対しては既定値を指定しなければならない場合があります。例については、スカラー構造体のクラスとサイズの指定と構造体配列のクラスとサイズの指定を参照してください。
MEX 関数に対する既定の fimath 値の指定. MATLAB Coder を使用して生成された MEX 関数は、実際にはコンパイル時に既定の fimath
値を使用します。既定の fimath
値を指定しない場合、MATLAB Coder は、MATLAB の既定の fimath
を使用します。MATLAB 出荷時の既定のプロパティは以下のとおりです。
RoundingMethod: Nearest OverflowAction: Saturate ProductMode: FullPrecision SumMode: FullPrecision CastBeforeSum: true
既定の fimath
値に依存する MEX 関数を実行しているときは、MATLAB セッション中にこの値を変更しないでください。変更すると、コンパイル時と実行時の fimath
の値が一致していないという警告を受け取ります。
たとえば、次の MATLAB 関数 test
を定義するとします。
function y = test %#codegen y = fi(0);
関数 test
は、fimath
オブジェクトを明示的に指定することなく fi
オブジェクトを構築します。したがって、test
は、実際にはコンパイル時に既定の fimath
オブジェクトに依存することになります。MATLAB プロンプトで、MEX 関数 text_mex
を生成して MATLAB の既定の fimath
の工場出荷時の設定を使用します。
codegen test % codegen generates a MEX function, test_mex, % in the current folder
次に、test_mex
を実行して MATLAB の既定の fimath
値を表示します。
test_mex ans = 0 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 16 FractionLength: 15
ここで、ローカルの MATLAB の fimath
値を作成します。これ以降は既定値は使用しません。
F = fimath('RoundingMethod','Floor');
最後に、メモリから MEX 関数をクリアして、再度実行します。
clear test_mex test_mex
不一致が検出され、エラーが発生します。
??? This function was generated with a different default fimath than the current default. Error in ==> test_mex
MEX 関数に対する複数のシグネチャの指定. エントリポイント関数から複数シグネチャの MEX 関数を生成するには、同じエントリポイント関数に対して複数の -args
を指定します。生成された MEX 関数は、コード生成中に指定した複数のシグネチャで動作します。複数シグネチャの MEX の詳細については、複数のシグネチャに対する 1 つの MEX 関数の生成を参照してください。
サポートされているクラス
以下の表に MATLAB Coder でサポートされているクラス名を示します。
クラス名 | 説明 |
---|---|
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 ファイルでプログラムによって入力プロパティを定義する場合は、この方法は使用できません。 |
|
|
|
|
コマンド ラインでの例による入力プロパティの定義
コマンド ライン オプション -args
関数 codegen
には、基本 (エントリポイント) 関数の入力のプロパティを、値または型の例の cell 配列で指定する -args
コマンド ライン オプションがあります。cell 配列は、可変またはリテラル配列の一定値を使用できます。このオプションを使用することで、codegen
を使用して MATLAB 関数のコードを生成すると同時に、入力のプロパティを指定します。
あるエントリポイント関数の出力の型を別の関数の入力として渡すことができます。入力としてのエントリポイント関数出力の受け渡しを参照してください。cell 配列入力の指定の詳細は、コマンド ラインでの cell 配列入力の指定を参照してください。
必要な型を使用してエントリポイント MATLAB 関数を呼び出すテスト関数またはスクリプトがある場合は、coder.getArgTypes
を使用して、関数入力の型を決定できます。coder.getArgTypes
は、coder.Type
オブジェクトの cell 配列を返します。この cell 配列は -args
オプションを使用して codegen
に渡すことができます。codegen
の詳細は、基本入力の一般的なプロパティの指定を参照してください。
coder.Type
オブジェクトは、コード生成の型エディターを使用して対話形式で作成することもできます。コード生成の型エディターを使用した入力の型の作成と編集を参照してください。
-args オプションを使用する場合の規則
-args
コマンド ライン オプションを使用して、例によってプロパティを定義するには次の規則に従います。
cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。
MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。
MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を
-args
に渡します。クラスが固定小数点 (
fi
) である基本関数入力ごとに、入力のnumerictype
とfimath
プロパティを指定します。クラスが
struct
である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。
コマンド ラインでの例による基本入力のプロパティの指定
2 つの入力を追加する MATLAB 関数を考えてみます。
function y = mcf(u,v) %#codegen y = u + v;
次の例では、コマンド ラインで例によって基本入力 u
と v
で異なるプロパティを指定する方法を示します。
定数のリテラル cell 配列を使用して、両方の入力が実数スカラーの double であるように指定します。
codegen mcf -args {0,0}
定数のリテラル cell 配列を使用して、入力
u
が符号なしの 16 ビットの 1 行 4 列のベクトル、入力v
がスカラーの double であるように指定します。codegen mcf -args {zeros(1,4,'uint16'),0}
サンプル値を cell 配列変数に代入し、両方の入力が実数で符号なし 8 ビットの整数ベクトルであるように指定します。
a = uint8([1;2;3;4]) b = uint8([5;6;7;8]) ex = {a,b} codegen mcf -args ex
コマンド ラインでの例による基本固定小数点入力のプロパティの指定
固定小数点 MATLAB コードの MEX 関数または C/C++ コードを生成するには、Fixed-Point Designer™ ソフトウェアをインストールしなければなりません。
固定小数点数の平方根を計算する MATLAB 関数を考えてみます。
%#codegen function y = sqrtfi(x) y = sqrt(x);
例によって基本固定小数点入力 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) };
次の例のように、
codegen
コマンドを使用して、変数myeg
を-args
オプションの引数として渡して、関数sqrtfi
をコンパイルします。codegen sqrtfi -args myeg;
コマンド ラインでの定数入力の指定
基本入力が実行時に変化しないことがわかっている場合、基本入力を定数値として指定することで、生成されたコードのオーバーヘッドを削減できます。定数入力は、通常、アルゴリズムの実行方法を制御するフラグや、データのサイズや型を指定する値に使用されます。
入力に定数を指定するには、-args
コマンド ライン オプションを coder.Constant
オブジェクトと共に使用します。入力に constant_input
のサイズ、クラス、実数/複素数および値をもつ定数を指定するには、以下の構文を使用します。
-args {coder.Constant(constant_input
)}
定数入力をもつ関数の呼び出し
コード ジェネレーターでは、生成されるコードに関数への定数入力がコンパイルされます。生成された C または C++ コードでは、関数シグネチャに定数入力は含まれません。既定では、MEX 関数のシグネチャに定数入力を含めます。MEX 関数を呼び出す場合、コンパイル時の値と一致する値を指定しなければなりません。MEX 関数のシグネチャに定数入力が含まれているかどうかや、定数入力に指定する値を MEX 関数がチェックするかどうかを制御できます。MEX 関数での定数入力のチェックを参照してください。
定数入力として構造体を指定
次のように、MATLAB ワークスペースに構造体 tmp
を定義することで行列の次元を指定するとします。
tmp = struct('rows', 2, 'cols', 3);
次の MATLAB 関数 rowcol
は、構造体入力 p
を受け取って行列 y
を定義します。
function y = rowcol(u,p) %#codegen y = zeros(p.rows,p.cols) + u;
次の例は、基本入力 u
が double スカラー変数で、基本入力 p
が定数構造体であることを指定する方法を示しています。
codegen rowcol -args {0,coder.Constant(tmp)}
コマンド ラインでの可変サイズ入力の指定
可変サイズ データは実行時にサイズが変わる可能性のあるデータです。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 の場合は、固定
次元が制限なしの場合は、常に可変サイズ
詳細は、「coder.typeof
」および可変サイズ データのためのコード生成を参照してください。
可変サイズ ベクトル入力の指定
ベクトル
A
の各n
要素の平均を計算し、ベクトルB
に格納する関数を作成します。function B = nway(A,n) %#codegen % Compute average of every N elements of A and put them in B. coder.extrinsic('error'); if ((mod(numel(A),n) == 0) && (n>=1 && n<=numel(A))) B = ones(1,numel(A)/n); k = 1; for i = 1 : numel(A)/n B(i) = mean(A(k + (0:n-1))); k = k + n; end else B = zeros(1,0); error('n <= 0 or does not divide number of elements evenly'); end
最初の入力
A
を double 値のベクトルとして指定します。最初の次元のサイズは固定ですが、2 番目の次元は上限 100 まで増やせます。2 番目の入力n
を double スカラーとして指定します。codegen -report nway -args {coder.typeof(0,[1 100],1),1}
また、この代わりに、
coder.typeof
の式を MATLAB 変数に代入し、この変数を-args
に引数として渡すこともできます。vareg = coder.typeof(0,[1 100],1) codegen -report nway -args {vareg, 0}
入力の型の指定と arguments
ブロック
関数の引数の検証 (arguments
ブロック) を使用してエントリポイント関数の入力の型を指定することはサポートされていません。エントリポイント関数に入力引数を検証する arguments
ブロックが含まれている場合も、基本入力のプロパティの定義方法に示す 3 つの方法のいずれかを使用して、それらの入力引数のプロパティを指定する必要があります。
生成コード内のエントリポイント関数の入力の既定値
arguments
ブロックを使用すると、1 つ以上の位置入力引数の既定値を指定できます。引数の宣言で既定値を指定すると、関数呼び出しで値を渡さない場合に MATLAB で既定値を使用できるため、位置引数はオプションになります。codegen
コマンドを使用してコードを生成する場合や fiaccel
(Fixed-Point Designer) コマンドを使用して固定小数点コードを高速化する場合に、一定の既定値をもつ 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 -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 -config:lib -c useDefaults_2 -args 0 -report 生成コード: double useDefaults_2(double a) { return (a + 5.0) + 7.0; } |
codegen -config:lib -c useDefaults_2 -args {0,0} -report 生成コード: double useDefaults_2(double a, double b) { return (a + b) + 7.0; } |