Main Content

buildInstrumentedMex

ログ作成可能な計測機能を含んだコンパイル済み C コード関数の生成

ページ内をすべて折りたたむ

構文

buildInstrumentedMex fcn -options
buildInstrumentedMex fcn_1... fcn_n -options -coder

説明

例

buildInstrumentedMex fcn -options は、MATLAB® ファイル fcn.m を MEX 関数に変換し、すべての名前付きの変数と中間変数の両方の最小値と最大値のログを作成する計測機能を有効にします。オプションで、名前付きの値、中間値および式の値すべての log2 ヒストグラムに対するインストルメント化を有効にできます。buildInstrumentedMex および fiaccel の一般的な構文とオプションは同じですが、buildIntstrumentedMex は fi オブジェクトの制限がなく、'-coder' オプションをサポートします。

メモ

関数 fiaccel と同様に、関数 buildInstrumentedMex は MEX 関数を生成します。C コードを生成するには、関数 codegen (MATLAB Coder) を使用します。

例

buildInstrumentedMex fcn_1... fcn_n -options -coder は、MATLAB 関数 fcn_1 から fcn_n を MEX 関数に変換し、すべての名前付き変数と中間変数の最小値と最大値のログを記録するインストルメント化を有効にします。複数のエントリポイント関数のための MEX 関数を生成するには '-coder' オプションが必要です。

メモ

関数 buildInstrumentedMex を使用して複数のエントリポイント関数のための MEX 関数を生成するには、MATLAB Coder™ ライセンスが必要です。

例

すべて折りたたむ

ライブ スクリプトを開く

この例では、インストルメント化された MEX 関数を作成し、テスト ベンチを実行してから、ログに記録された結果を表示する方法を示します。

プロトタイプの入力引数を定義します。

n = 128;
x = complex(zeros(n,1));
w = fi_radix2twiddles(n);

インストルメント化した MEX 関数を生成します。-o オプションを使用して、MEX 関数名を指定します。-histogram オプションを使用してヒストグラムを計算します。

MATLAB® Coder™ ライセンスがある場合は、-coder オプションも追加できます。この場合は次のようになります。 

buildInstrumentedMex testfft -o testfft_instrumented -args {x,coder.Constant(w)} -histogram

MATLAB® Coder™ ライセンスがある場合は、-coder オプションも追加できます。次に例を示します。

buildInstrumentedMex testfft -coder -o testfft_instrumented -args {x,w}

関数 fiaccel と同様に、関数 buildInstrumentedMex は MEX 関数を生成します。C コードを生成するには、MATLAB® Coder™ の関数 codegen を使用します。

テスト ファイルを実行し、インストルメント化の結果を記録します。関数 showInstrumentedMex を使用してレポートを開きます。シミュレーションの最小値と最大値や 0 または正の整数のステータスを表示するには、レポート内の変数をポイントします。倍精度数に推奨されるデータ型もテーブルで参照できます。

for i=1:20
   y = testfft_instrumented(randn(size(x)),w);
end

showInstrumentationResults testfft_instrumented

instrumentation-report-tb1.png

ヒストグラムの表示を閉じてから、関数 clearInstrumentationResults を使用して結果のログをクリアします。

clearInstrumentationResults testfft_instrumented

別のテスト ベンチを実行し、次に新しい計測結果を表示します。

for i=1:20
   y = testfft_instrumented(cast(rand(size(x))-0.5,'like',x),w);
end

showInstrumentationResults testfft_instrumented

instrumentation-report-tb2.png

変数のヒストグラムを表示するには、[変数] タブでヒストグラム アイコンをクリックします。

numeric-type-scope-x-tb2.png

ヒストグラムの表示を閉じてから、関数 clearInstrumentationResults を使用して結果のログをクリアします。

clearInstrumentationResults testfft_instrumented

MEX 関数をクリアします。

clear testfft_instrumented

この例では次を使用します。

ライブ スクリプトを開く

この例では、複数のエントリポイント関数のインストルメント化された MEX 関数を作成する方法を示します。関数 buildInstrumentedMex を使用して複数のエントリポイント関数の MEX 関数を生成するには、'-coder' オプションを使用する必要があり、MATLAB® Coder™ ライセンスが必要です。

セクション 1 のタイトル

この例では、2 つのエントリポイント関数 ep1 と ep2 を使用します。

function y1 = ep1(u) %#codegen
y1 = u;
end

function y2 = ep2(u,v) %#codegen
y2 = u + v;
end

2 つのエントリポイント関数のためにインストルメント化された MEX 関数を生成します。-o オプションを使用して、MEX 関数の名前を指定します。-histogram オプションを使用してヒストグラムを計算します。関数 buildInstrumentedMex で -coder オプションを使用して、複数のエントリポイントを生成します。

u = 1:100;
v = 5:104;
buildInstrumentedMex -o sharedmex ...
ep1 -args {u} ... % Entry point 1
ep2 -args {u,v} ... % Entry point 2
-histogram -coder
Code generation successful.

生成された MEX 関数を使用して最初のエントリポイント関数を呼び出します。

y1 = sharedmex('ep1',u);

生成された MEX 関数を使用して 2 番目のエントリポイント関数を呼び出します。

y2 = sharedmex('ep2',u,v);

計測結果を表示します。

showInstrumentationResults sharedmex

report-multiple-entry-point-functions.png

入力引数

すべて折りたたむ

インストルメント化する MATLAB エントリポイント関数。現在の作業フォルダーまたはパス上に存在する関数として指定します。エントリポイント関数はコード生成に適合していなければなりません。詳細は、MATLAB コードをコード生成に適したものにする (MATLAB Coder)を参照してください。

コンパイラ オプションの選択肢。buildInstrumentedMex では、構成オブジェクトを使用して指定されたオプションよりも、個々のコマンド ライン オプションが優先されます。コマンド ライン オプションが競合する場合は、最も右にあるオプションが優先されます。

-args example_inputs

すべての MATLAB 関数入力のサイズ、クラスおよび実数/複素数を定義します。example_inputs 内の値を使用してこれらのプロパティを定義します。example_inputs は MATLAB 関数と同じ数で同じ順序の入力を指定する cell 配列でなければなりません。

-coder

既定の Fixed-Point Designer™ 関数 fiaccel ではなく、MATLAB Coder ソフトウェアを使用して MEX ファイルをコンパイルします。このオプションによって fiaccel 制限が除外されるため、コード生成が十分サポートされるようになります。このオプションを使用するには、MATLAB Coder のライセンスを所有していなければなりません。

-config config_object

config_object に基づき、coder.mexconfig を使用して MATLAB 変数として定義される、MEX 生成パラメーターを指定します。以下に例を示します。

cfg = coder.mexconfig;

-d out_folder

生成されたファイルを out_folder で指定された絶対パスまたは相対パスに保存します。out_folder で指定されたフォルダーが存在しない場合、関数 buildInstrumentedMex はフォルダーを作成します。

フォルダーの場所を指定しない場合、buildInstrumentedMex は既定のフォルダー内にファイルを生成します。 

fiaccel/mex/fcn.

fcn はコマンド ラインで指定された MATLAB 関数の名前です。

フォルダー名にはアスタリスク (*)、疑問符 (?)、ドル記号 ($) およびシャープ記号 (#) は使用できません。

-g

最適化を無効にして、デバッグ モードで MEX 関数をコンパイルします。指定しない場合、buildinstrumentedMex は最適なモードで MEX 関数を生成します。

-global global_values

MATLAB ファイルのグローバル変数の初期値を指定します。コンパイルする関数でグローバル変数を初期化するために cell 配列 global_values 内の値を使用します。cell 配列には各グローバル変数の名前と初期値を指定しなければなりません。関数 buildInstrumentedMex を使用してコンパイルする前にグローバル変数を初期化しなければなりません。-global オプションを使用してグローバル変数に初期値を提供しない場合、buildInstrumentedMex は MATLAB グローバル ワークスペース内の変数をチェックします。初期値を指定しないと buildInstrumentedMex はエラーを生成します。

生成された MEX コードと MATLAB は、それぞれ独自のグローバル データのコピーをもっています。一貫性を維持するために、これらの 2 つが情報をやり取りするときには必ずそれらのグローバル データを同期しなければなりません。データを同期しないと、グローバル変数は異なるものになる可能性があります。

-histogram名前付きの値、中間値および式の値すべての log2 ヒストグラムを計算します。ヒストグラムの列がコード生成レポートの表に表示されます。
-I include_path

include_path をコード生成パスの先頭に追加します。

MATLAB コードを MEX コードに変換する際には、buildInstrumentedMex は "最初に" コード生成パスを検索します。

-launchreport

コード生成レポートを生成して開きます。このオプションを指定しないと、buildInstrumentedMex ではエラー メッセージまたは警告メッセージが発生した場合、あるいは -report オプションを指定した場合にのみレポートが生成されます。

-o output_file_name

output_file_name を基本名とし、プラットフォーム固有の拡張子を付けて、MEX 関数を生成します。

output_file_name にはファイル名を指定するかまたは既存のパスを含めることができます。

出力ファイル名を指定しないと、基本名は fcn_mex になります。これによって、元の MATLAB 関数と MEX 関数を実行して、結果を比較できます。

-O optimization_option

optimization_option の値に基づいて、生成される MEX コードを最適化します。

  • enable:inline — 関数インライン化を有効にします。

  • disable:inline — 関数インライン化を無効にします。

指定しない場合、buildInstrumentedMex ではインライン化を使用して最適化が行われます。

-report

コード生成レポートを生成します。このオプションを指定しないと、buildInstrumentedMex ではエラー メッセージまたは警告メッセージが発生した場合、あるいは -launchreport オプションを指定した場合にのみレポートが生成されます。

ヒント

  • ソフトウェアに付属の MATLAB 関数はインストルメント化できません。最上位の関数がそのような MATLAB 関数の場合、ログには何も含まれません。また、スクリプトもインストルメント化できません。

  • 計測結果は、インストルメント化した MEX 関数が呼び出されるたびに累積されます。clearInstrumentationResults を使用して、ログの前回の結果をクリアします。

  • コーディング パターンによっては膨大なデータが渡されますが、使用されるデータはその一部です。そのような場合、buildInstrumentedMex の使用時にパフォーマンスの低下が確認される可能性もあります。次のパターンでは、subfun は入力配列の 1 要素 A しか使用しません。通常の実行では、subfun を 1 回実行する時間は A のサイズにかかわらず一定です。つまり、関数 topfun が subfun を N 回呼び出すと、topfun の合計実行時間は N に比例します。ただし、インストルメント化されると、subfun を 1 回実行する時間は N^2 に比例するようになります。これは、最小データと最大データが配列全体に対して計算されるためです。A が大きいと、この計算でパフォーマンスの大幅な低下が発生する場合があります。そのため、可能な限り、関数が実際に必要とするデータのみを渡すようにしてください。

    function A = topfun(A)
    N = numel(A);
    for i=1:N
        A(i) = subfun(A,i);
    end
end
function b = subfun(A,i)
    b = 0.5 * A(i);
end
  
function A = topfun(A)
    N = numel(A);
    for i=1:N
        A(i) = subfun(A(i));   
    end  
end
function b = subfun(a)
    b = 0.5 * a;
end

バージョン履歴

R2011b で導入

すべて展開する

参考

| | | | (MATLAB Coder) |