C API を使用した生成コードと外部コードの間のデータ交換

一部の Simulink^® Coder™ アプリケーションでは、あるモデル用に生成されたコードの信号、状態、ルートレベル入力/出力またはパラメーターと対話しなければなりません。たとえば、キャリブレーションアプリケーションはパラメーターを監視および変更します。信号の監視またはデータログを行うアプリケーションは、信号、状態、およびルートレベル入力/出力データと対話します。Simulink Coder C API を使用して、生成されたコードを実行しながら、信号、状態およびルートレベル入力/出力のログを作成し、信号、状態およびルートレベル入力/出力を監視し、パラメーターの調整を行うターゲットアプリケーションをビルドできます。

C API は信号、状態、ルートレベル入力/出力、およびパラメーターに共通する情報を比較的小さい構造体で共有することで、メモリのフットプリントを最小化します。信号、状態、ルートレベル入力/出力、およびパラメーター構造体には、複数の信号、状態、ルートレベル入力/出力、またはパラメーターがデータを共有できるようにする構造体マップのインデックスが含まれます。

コード例の使用を開始するには、C API を使用したモデルの信号と状態へのアクセスまたはC API を使用したモデルパラメーターへのアクセスを参照してください。

生成された C API ファイル
C API ファイルの生成
C API ファイルの説明
ターゲットシステムとデータを交換するための C API データ定義ファイルの生成
C API 制限

生成された C API ファイル

C API を使用するモデルを構成すると、Simulink Coder コードジェネレーターは 2 つのファイル、model_capi.c (または .cpp) と model_capi.h を生成します。ここで、model はモデルの名前です。コードジェネレーターは [コンフィギュレーションパラメーター] ダイアログボックスの設定に基づいて、ビルドフォルダーに 2 つの C API ファイルを配置します。C API ソースコードファイルには、生成されたコードモデルソースコードで定義されたグローバルブロックの出力信号、状態、ルートレベル入力/出力、およびグローバルパラメーターに関する情報が含まれます。C API ヘッダーファイルはモデルソースコードと生成された C API の間のインターフェイスヘッダーファイルです。これらの C API ファイル内の情報を使用してアプリケーションを作成できます。

メモ

コードジェネレーターを構成して C API インターフェイスとデータログのサポートが含まれるコードを生成する場合、コードジェネレーターは C API ファイル model_capi.c (または .cpp) および model_capi.h に記録されたブロックパス内のブロック名のテキストを含めることができます。これらのテキストに、モデルの文字セットエンコードで表現できない文字が含まれている場合、コードジェネレーターはその文字を XML エスケープシーケンスに置き換えます。たとえば、コードジェネレーターは日本語の全角カタカナの文字「ア」を、エスケープシーケンス ア で置き換えます。詳細については、地域と言語の設定とコード生成を参照してください。

C API ファイルの生成

モデルの C API ファイルを生成するには、次の手順に従います。

モデルの C API インターフェイスを選択します。モデルの C API インターフェイスを選択する方法は 2 つあります。これらについては次の各節で説明します。
- [コンフィギュレーションパラメーター] ダイアログでの C API の選択
- コマンドラインからの C API の選択
モデルのコードを生成します。

コードが生成されたら、モデルビルドフォルダーのファイル model_capi.c (または .cpp) および model_capi.h を検証できます。

[コンフィギュレーションパラメーター] ダイアログでの C API の選択

モデルを開き、[コンフィギュレーションパラメーター] ダイアログボックスを開きます。
[コード生成] 、 [インターフェイス] ペインの [データ交換インターフェイス] サブグループで 1 つ以上の [C API] オプションを選択します。選択したオプションに基づき、C API 生成コードに信号、パラメーター、状態およびルートレベル I/O にアクセスするためのサポートが表示されます。
- グローバルブロック出力信号の C API コードを生成するには、[C API の生成: 信号] を選択します。
- グローバルブロックパラメーターの C API コードを生成するには、[C API の生成: パラメーター] を選択します。
- 離散状態と連続状態の C API コードを生成するには、[C API の生成: 状態] を選択します。
- ルートレベル入力/出力の C API コードを生成するには、[C API の生成: ルートレベル I/O] を選択します。

コマンドラインからの C API の選択

MATLAB^® コマンドラインから、関数 set_param を使用して C API モデルコンフィギュレーションパラメーターをオンまたはオフにします。MATLAB コマンドラインで、次の 1 つ以上のコマンドを入力します。ここで、modelname はモデル名です。

[C API の生成:信号] をオンにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPISignals','on')

[C API の生成:信号] をオフにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPISignals','off')

[C API の生成:パラメーター] をオンにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPIParams','on')

[C API の生成:パラメーター] をオフにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPIParams','off')

[C API の生成:状態] をオンにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPIStates','on')

[C API の生成:状態] をオフにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPIStates','off')

[C API の生成:ルートレベル I/O] をオンにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPIRootIO','on')

[C API の生成:ルートレベル I/O] をオフにするには、次のコマンドを入力します。

set_param('modelname','RTWCAPIRootIO','off')

C API ファイルについて

model_capi.c (または .cpp) ファイルはモデルデータに統一したインターフェイスをもつ外部アプリケーションを提供します。コンフィギュレーションコンフィギュレーションに応じて、データとして信号、状態、ルートレベル入力/出力、またはパラメーターを指定できます。このドキュメントでは、用語 "データ項目" は信号、状態、ルートレベル入力/出力、またはパラメーターのいずれかを指します。C API ではインターフェイスをデータ項目プロパティに提供する構造体を使用します。インターフェイスはデータ構造体の各データ項目のプロパティをパッケージ化します。モデルに複数のデータ項目がある場合、インターフェイスはデータ構造体の配列を生成します。データ構造体のメンバーはデータプロパティにマッピングします。

データ項目と対話するには、アプリケーションでは各データ項目で次のプロパティが必要です。

名前
ブロックパス
ポート番号 (信号とルートレベル入力/出力のみ)
アドレス
データ型情報:ネイティブデータ型、データサイズ、実数/複素数およびその他の属性
次元情報: 行数、列数、データの方向 (スカラー、ベクトル、行列、または n 次元)
固定小数点情報: 勾配、バイアス、スケール型、語長、指数、およびその他の属性
サンプル時間情報 (信号、状態、およびルートレベル入力/出力のみ):サンプル時間、タスク識別子、フレーム

次の図で示すように、たとえば、データ項目 A のプロパティはデータ構造 DS_A に位置し、データ項目 B のプロパティはデータ構造 DS_B に位置しています。

一部のプロパティ "値" は各データ項目に一意である場合がありますが、複数のデータ項目が共通に共有するプロパティ値もあります。たとえば、名前は各データ項目で一意の値をもちます。インターフェイスはデータ項目の構造体に一意のプロパティ値を直接配置します。データ項目 A の名前の値は DS_A に、データ項目 B の名前の値は DS_B に配置されます。

しかし、データ型は値の複数のデータ項目が共通にもつプロパティである場合があります。一部のデータ項目ではプロパティを共有できるため、C API は再利用機能をもつことができます。この場合、インターフェイスはインデックス値のみを DS_A と DS_B に配置します。これらのインデックスは実際のデータ型の値を含む別のデータ構造体 DS_C を指します。次の図にこのスキームの詳細を示します。

図には 3 つの信号が示されています。signal1 と signal2 は同じデータ型 double を共有します。各信号データ構造体でこのデータ型の値を指定する代わりに、インターフェイスは構造体にインデックス値 0 のみを提供します。"double" は両方の信号によって参照される配列 rtDataTypeMap でエントリ 0 で表されます。さらに、プロパティ値は信号、状態、ルートレベル入力/出力、およびパラメーター間で共有できるため、状態、ルートレベル入力/出力、およびパラメーターは配列 rtDataTypeMap の double エントリも参照することがあります。この情報の再利用により、生成されたインターフェイスのメモリサイズが削減されます。

C API ファイルで生成される構造配列

データ型と同様に、インターフェイスはその他の共通プロパティ (アドレス、次元、固定小数点スケーリング、サンプル時間など) を個別の構造体にマッピングし、データ項目に構造体のインデックスを提供します。構造体定義の完全な一覧については、ファイル matlabroot/rtw/c/src/rtw_capi.h を参照してください。このファイルは構造体の各メンバーも表します。model_capi.c (または .cpp) ファイルで生成された構造体配列は rtw_capi.h ファイルに定義された構造体タイプです。model_capi.c (または .cpp) で生成される構造体配列の簡単な説明を次に示します。

rtBlockSignals はモデルのグローバルブロック出力信号に関する情報を含む構造体の配列です。配列の各要素は struct rtwCAPI_Signals 型です。この構造体のメンバーはデータ型、次元、固定小数点、およびサンプル時間構造体配列に対して信号名、ブロックパス、ブロック端子番号、アドレス、およびインデックスを提供します。
rtBlockParameters はブロック名およびパラメーター名別にモデルの調整可能なブロックパラメーターに関する情報を含む構造体の配列です。配列の各要素は struct rtwCAPI_BlockParameters 型です。この構造体のメンバーはデータ型、次元、および固定小数点の構造体配列に対してパラメーター名、ブロックパス、アドレス、およびインデックスを提供します。
rtBlockStates はモデルの離散および連続状態に関する情報を含む構造体の配列です。配列の各要素は struct rtwCAPI_States 型です。この構造体のメンバーはアドレス、データ型、次元、固定小数点、およびサンプル時間構造体配列に対して状態名、ブロックパス、タイプ (離散または連続)、およびインデックスを提供します。
rtRootInputs は、モデルのルートレベル入力に関する情報を格納した構造体の配列です。配列の各要素は struct rtwCAPI_Signals 型です。この構造体のメンバーはデータ型、次元、固定小数点、およびサンプル時間構造体配列に対してルートレベル入力名、ブロックパス、ブロック端子番号、アドレス、およびインデックスを提供します。
rtRootOutputs は、モデルのルートレベル出力に関する情報を格納した構造体の配列です。配列の各要素は struct rtwCAPI_Signals 型です。この構造体のメンバーはデータ型、次元、固定小数点、およびサンプル時間構造体配列に対してルートレベル出力名、ブロックパス、ブロック端子番号、アドレス、およびインデックスを提供します。
rtModelParameters はワークプレイス変数に関する情報を含む構造体の配列です。モデル内の 1 つ以上のブロックや Stateflow^® チャートは、これらのワークプレイス変数をブロックパラメーターとして参照します。配列の各要素は rtwCAPI_ModelParameters データ型です。この構造体のメンバーはデータ型、次元、および固定小数点の構造体配列に対して変数名、アドレス、およびインデックスを提供します。
rtDataAddrMap は rtBlockSignals、rtBlockParameters、rtBlockStates、および配列 rtModelParameters に表示される信号、状態、ルートレベル入力/出力、およびパラメーターのベースアドレスの配列です。配列 rtDataAddrMap の各要素は void (void*) に対するポインターです。
rtDataTypeMap はモデルのさまざまなデータ型に関する情報を含む構造体の配列です。この配列の各要素は struct rtwCAPI_DataTypeMap 型です。この構造体のメンバーはデータ型名、データ型のサイズ、データが複素数であるかどうかに関する情報を提供します。
rtDimensionMap はモデルのさまざまなデータ次元に関する情報を含む構造体の配列です。この配列の各要素は struct rtwCAPI_DimensionMap 型です。この構造体のメンバーはデータの次元数、データの方向 (スカラー、ベクトル、または行列)、およびデータの実際の次元に関する情報を提供します。
rtFixPtMap は信号、状態、ルートレベル入力/出力、およびパラメーターに関する固定小数点情報を格納した構造体の配列です。この配列の各要素は struct rtwCAPI_FixPtMap 型です。この構造体のメンバーはデータスケーリング、バイアス、指数、および固定小数点データが符号付きであるかどうかに関する情報を提供します。モデルに固定小数点データ (信号、状態、ルートレベル入力/出力またはパラメーター) がない場合、Simulink Coder ソフトウェアは NULL または 0 値を配列 rtFixPtMap の要素に代入します。
rtSampleTimeMap はモデルのグローバル信号、状態、およびルートレベル入力/出力に関するサンプリング情報を格納した構造体の配列です (この配列にはパラメーターに関する情報は含まれません)。この配列の各要素は struct rtwCAPI_SampleTimeMap 型です。この構造体のメンバーはサンプル時間、オフセット、およびデータがフレームベースまたはサンプルベールであるかどうかに関する情報を提供します。

サンプル C API ファイルの生成

サブトピックC API 信号、C API 状態、C API のルートレベルの入力と出力およびC API パラメーターでは、生成される C API 構造体について、モデル例 CAPIPModel を使用して説明します。モデル例からコードを生成するには、次の手順に従います。

モデル CAPIModel を開きます。
```
openExample("CAPIModel")
```
CAPIModel でルートレベル入力/出力の C API 構造体を生成する場合、モデルコンフィギュレーションパラメーター [ルートレベル I/O 用 C API の生成] を選択します。
このパラメーターの設定は、最上位モデルと参照モデルの間で一致しなければなりません。パラメーター設定を変更する場合、最上位モデルと参照モデルを書き込み可能な同じ作業フォルダーに保存します。
モデルのコードを生成します。

次のサブトピックの C API コードの例は、ターゲット言語として C を使用して生成されます。

このモデルは C API 生成コードに表示される次の 3 つのグローバルブロック出力信号をもちます。

top_sig1: 最上位モデルの Gain1 ブロックの出力のテストポイントです。
sig2_eg: 最上位モデルに表示され、ストレージクラス ExportedGlobal をもつ Simulink.Signal オブジェクトとしてベースワークスペースで定義されます。
bot_sig1: 参照モデル CAPIModelRef に表示され、ストレージクラス Model default をもつ Simulink.Signal オブジェクトとして定義されます。

モデルには C API 生成コードに表示される次の 2 つの離散状態をもちます。

top_state: 最上位モデルの Delay1 ブロックで定義されます。
bot_state: 参照モデルの Discrete Filter ブロックで定義されます。

C API 生成コードに現れるルートレベル入力/出力をモデルがもつようにするには、モデルコンフィギュレーションパラメーター [C API の生成: ルートレベル I/O] をオンにします。

4 つのルートレベル入力 In1 ～ In4
6 つのルートレベル出力 Out1 ～ Out6

さらに、モデルは C API 生成コードに表示される次の 5 つのグローバルブロックパラメーターをもちます。

Kp (最上位モデル Gain1 ブロックおよび参照モデル Gain2 ブロックが共有)
Ki (参照モデル Gain3 ブロック)
p1 (ルックアップテーブル lu1d)
p2 (ルックアップテーブル lu2d)
p3 (ルックアップテーブル lu3d)

C API 信号

rtwCAPI_Signals 構造体は信号名、アドレス、ブロックパス、出力端子番号、データ型情報、次元情報、固定小数点情報、およびサンプル時間情報を含む信号情報を取得します。

CAPIModel の最上位モデルの C API 信号の情報を提供する CAPIModel_capi.c のコードのセクションを次に示します。

/* Block output signal information */
static const rtwCAPI_Signals rtBlockSignals[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, dimIndex, fxpIndex, sTimeIndex
   */
  { 0, 0, "CAPIModel/Gain1",
    "top_sig1", 0, 0, 0, 0, 0 },

  { 1, 0, "CAPIModel/lu2d",
    "sig2_eg", 0, 0, 1, 0, 0 },

  {
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

メモ

コードをよりよく理解するには、ファイルのコメントを読んでください。たとえば、上記のコードでは 3 行目で始まるコメントに注意してください。このコメントは構造体 rtwCAPI_Signals のメンバーの一覧を順番に示します。これにより、信号で表示される各メンバーの割り当てられる値の順序がわかります。この例で、コメントは signalName が構造体の 4 番目のメンバーであることを示しています。次の行は最初の信号を示しています。

  { 0, 0, "CAPIModel/Gain1",
    "top_sig1", 0, 0, 0, 0, 0 },

これらの行からは最初の信号の名前は top_sig1 であると推測されます。

各配列要素 (最後の要素を除く) はブロック信号ごとに 1 つの出力端子を示しています。最後の配列要素は null 値に設定されたすべての要素をもつ省略された要素です。たとえば、次のコードに示すように 2 番目の信号を検証します。

  { 1, 0, "CAPIModel/lu2d",
    "sig2_eg", 0, 0, 1, 0, 0 },

sig2_eg という名前の信号はブロック CAPIModel/lu2d の最初の端子の出力信号です。(この端子は、2 行目に表示されている portNumber のゼロベースのインデックスには値 0 が割り当てられるため、最初の端子となります)。

この信号のアドレスは addrMapIndex によって指定され、この例では 1 として最初の行に表示されています。このアドレスは配列 rtDataAddrMap へのインデックスを提供し、CAPIModel_capi.c で後に検出されます。

/* Declare Data Addresses statically */
static void* rtDataAddrMap[] = {
  &CAPIModel_B.top_sig1,            /* 0: Signal */
  &sig2_eg[0],                         /* 1: Signal */
  &CAPIModel_DWork.top_state,       /* 2: Discrete State */
  &rtP_Ki,                             /* 3: Model Parameter */
  &rtP_Kp,                             /* 4: Model Parameter */
  &rtP_p1[0],                          /* 5: Model Parameter */
  &rtP_p2[0],                          /* 6: Model Parameter */
  &rtP_p3[0],                          /* 7: Model Parameter */
};

1 のインデックスは配列 rtDataAddrMap の 2 番目の要素を指します。配列 rtDataAddrMap から、この信号のアドレスは &sig2_eg[0] であることを推測できます。

この間接的なレベルは同じモデルの複数のコードインスタンスをサポートします。複数のインスタンスが存在する場合、アドレスを除く信号情報は一定のままです。この場合、モデルは単一のインスタンスです。そのため、rtDataAddrMap は静的に宣言されます。再利用可能なコードを生成する場合、インスタンスごとにアドレスを動的に初期化する初期化関数が生成されます (再利用可能なコードの生成方法の詳細については、生成された C 関数インターフェイスをモデルのエントリポイント関数用に構成およびコード再利用のサポートの設定を参照してください)。

dataTypeIndex は配列 rtDataTypeMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、信号のデータ型を示します。

/* Data Type Map - use dataTypeMapIndex to access this structure */
static const rtwCAPI_DataTypeMap rtDataTypeMap[] = {
  /* cName, mwName, numElements, elemMapIndex, dataSize, slDataId, *
   * isComplex, isPointer */
  { "double", "real_T", 0, 0, sizeof(real_T), SS_DOUBLE, 0, 0 }
};

sig2_eg のインデックスは 0 であるため、インデックスは配列の最初の構造体要素を指します。信号のデータ型は double であると推測できます。isComplex の値は 0 であり、信号が複素数ではないことを示します。rtwCAPI_Signals 構造体にデータ型情報を直接提供する代わりに、間接的なレベルが導入されます。間接性は複数の信号が同じデータ型を共有して 1 つのマップ構造体を指すことを可能にするため、各信号でメモリが節約されます。

dimIndex (次元インデックス) は配列 rtDimensionMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、信号の次元を示します。sig2_eg のインデックスは 1 であるため、インデックスは配列 rtDimensionMap の 2 番目の要素を指します。

/* Dimension Map - use dimensionMapIndex to access elements of ths structure*/
static const rtwCAPI_DimensionMap rtDimensionMap[] = {
  /* dataOrientation, dimArrayIndex, numDims, vardimsIndex */
  { rtwCAPI_SCALAR, 0, 2, 0 },

  { rtwCAPI_VECTOR, 2, 2, 0 },
...
};

この構造体から、2 次元の非スカラー信号であることが推測されます。dimArrayIndex 値、2 は rtDimensionArray へのインデックスを提供し、CAPIModel_capi.c で後に検出されます。

/* Dimension Array- use dimArrayIndex to access elements of this array */
static const uint_T rtDimensionArray[] = {
  1,                                   /* 0 */
  1,                                   /* 1 */
  2,                                   /* 2 */
...
};

fxpIndex(固定小数点インデックス) は配列 rtFixPtMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、信号に関する固定小数点情報を示します。式 V=SQ+B を使用して、信号の実際値を計算するには、コードでスケーリング情報を使用できます。ここで、V は "実際" (つまり、ベース 10) 値、S はユーザー指定の勾配、Q は "量子化された固定小数点値" または "保存整数"、および B はユーザー指定のバイアスです詳細については、スケーリング (Fixed-Point Designer)を参照してください。

このインデックスは sig2_eg に対して 0 であるため、信号には固定小数点情報はありません。ゼロの固定小数点マップインデックスは、信号に固定小数点情報が含まれないということを意味します。

sTimeIndex (サンプル時間インデックス) は配列 rtSampleTimeMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、信号に関するタスク情報を示します。マルチレート信号または条件付き実行信号をログ記録する場合に、サンプリング情報は役立ちます。

メモ

model_capi.c (または .cpp) には rtw_capi.h が含まれます。配列 rtBlockSignals を参照するソースファイルにも rtw_capi.h が含まれなければなりません。

C API 状態

rtwCAPI_States 構造体は状態名、アドレス、ブロックパス、タイプ (離散または連続)、データ型情報、次元情報、固定小数点情報、およびサンプル時間情報を含む状態情報を取得します。

CAPIModel の最上位モデルの C API 状態の情報を提供する CAPIModel_capi.c のコードのセクションを次に示します。

/* Block states information */
static const rtwCAPI_States rtBlockStates[] = {
  /* addrMapIndex, contStateStartIndex, blockPath,
   * stateName, pathAlias, dWorkIndex, dataTypeIndex, dimIndex,
   * fixPtIdx, sTimeIndex, isContinuous
   */
  { 2, -1, "CAPIModel/Delay1",
    "top_state", "", 0, 0, 0, 0, 0, 0 },

  {
    0, -1, (NULL), (NULL), (NULL), 0, 0, 0, 0, 0, 0
  }
};

最後の要素を除く各配列要素はモデルの状態を表します。最後の配列要素は null 値に設定されたすべての要素をもつ省略された要素です。この例で、最上位モデルの C API コードは次の 1 つの状態を表示します。

  { 2, -1, "CAPIModel/Delay1",
    "top_state", "", 0, 0, 0, 0, 0, 0 },

top_state という名前のこの状態はブロック CAPIModel/Delay1 で定義されています。isContinuous の値は 0 であり、状態が連続ではなく離散であることを示します。C API 信号に示されている類似の名前の信号に対応したその他のフィールドも次のように同様です。

信号のアドレスは addrMapIndex によって指定され、この例では 2 となります。このアドレスは配列 rtDataAddrMap へのインデックスを提供し、CAPIModel_capi.c で後に検出されます。インデックスはゼロベースであるため、2 は rtDataAddrMap の 3 番目の要素 (&CAPIModel_DWork.top_state) に対応します。
dataTypeIndex は配列 rtDataTypeMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、パラメーターのデータ型を示します。値 0 は倍精度で非複素数のパラメーターに対応します。
dimIndex (次元インデックス) は配列 rtDimensionMap へのインデックスを提供し、CAPIModel_capi.c で後に検出されます。値 0 は最初のエントリ (つまり { rtwCAPI_SCALAR, 0, 2, 0 }) に対応します。
fixPtIndex(固定小数点インデックス) は配列 rtFixPtMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、パラメーターに関する固定小数点情報を示します。対応する信号属性と同様に、ゼロの固定小数点マップインデックスは、パラメーターに固定小数点情報が含まれないということを意味します。

C API のルートレベルの入力と出力

rtwCAPI_Signals 構造体は、入力/出力名、アドレス、ブロックパス、端子番号、データ型情報、次元情報、固定小数点情報、およびサンプル時間情報を含むルートレベル入力/出力情報を取得します(この構造体は、以前にC API 信号で説明したとおり、ブロック出力信号にも使用されます)。

CAPIModel の最上位モデルの C API ルートレベル入力/出力に関する情報を提供する CAPIModel_capi.c のコードのセクションを次に示します。

/* Root Inputs information */
static const rtwCAPI_Signals rtRootInputs[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, dimIndex, fxpIndex, sTimeIndex
   */
  { 3, 0, "CAPIModel/In1",
    "", 1, 0, 0, 0, 0 },

  { 4, 0, "CAPIModel/In2",
    "", 2, 0, 0, 0, 0 },

  { 5, 0, "CAPIModel/In3",
    "", 3, 0, 0, 0, 0 },

  { 6, 0, "CAPIModel/In4",
    "", 4, 0, 0, 0, 0 },

  {
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

/* Root Outputs information */
static const rtwCAPI_Signals rtRootOutputs[] = {
  /* addrMapIndex, sysNum, blockPath,
   * signalName, portNumber, dataTypeIndex, dimIndex, fxpIndex, sTimeIndex
   */
  { 7, 0, "CAPIModel/Out1",
    "", 1, 0, 0, 0, 0 },

  { 8, 0, "CAPIModel/Out2",
    "", 2, 0, 0, 0, 0 },

  { 9, 0, "CAPIModel/Out3",
    "", 3, 0, 0, 0, 0 },

  { 10, 0, "CAPIModel/Out4",
    "", 4, 0, 0, 0, 0 },

  { 11, 0, "CAPIModel/Out5",
    "sig2_eg", 5, 0, 1, 0, 0 },

  { 12, 0, "CAPIModel/Out6",
    "", 6, 0, 1, 0, 0 },

  {
    0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
  }
};

メモ

C++ コードを生成する場合、コードジェネレーターは C API ルートレベル入力/出力に関する情報を提供しません。

rtwCAPI_Signals 構造体の値を解釈する方法は、前の節C API 信号を参照してください。

C API パラメーター

構造体 rtwCAPI_BlockParameters および rtwCAPI_ModelParameters はパラメーター名、ブロックパラメーターのブロックパス、アドレス、データ型情報、次元情報、固定小数点情報を含むパラメーター情報を取得します。

配列 rtModelParameters にはマシンスコープの調整可能な Simulink ブロックパラメーターまたは Stateflow データとして参照されるワークスペース変数のエントリが含まれます。たとえば、調整可能なパラメーターには、Auto 以外のストレージクラスを使用する Simulink.Parameter オブジェクトが含まれます。Simulink Coder ソフトウェアはこのデータが欠落した場合にその要素に NULL または 0 値のみを代入します。

モデルコンフィギュレーションパラメーター [既定のパラメーター動作] で選択した設定により、情報がどのように model_capi.c (または .cpp) 内の配列 rtBlockParameters 内に生成されるのかが決まります。

[既定のパラメーター動作] を [調整可能] に設定すると、配列 rtBlockParameters にはモデルの各ブロックの変更可能なすべてのパラメーターに対するエントリが含まれます。ただし、MATLAB 変数または調整可能なパラメーターを使用してブロックパラメーターを指定する場合、ブロックパラメーターは rtBlockParameters に表示されません。代わりに、変数または調整可能なパラメーターは rtModelParameters に表示されます。
[既定のパラメーター動作] を [インライン] に設定すると、配列 rtBlockParameters は空になります。Simulink Coder ソフトウェアはその要素に NULL または 0 値のみを代入します。

各配列の最後のメンバーは null 値に設定されたすべての要素をもつ省略された要素です。

CAPIModel_capi.c で既定の設定で生成される配列 rtBlockParameters を次に示します。

/* Individual block tuning is not valid when inline parameters is *
 * selected. An empty map is produced to provide a consistent     *
 * interface independent  of inlining parameters.                 *
 */
static const rtwCAPI_BlockParameters rtBlockParameters[] = {
  /* addrMapIndex, blockPath,
   * paramName, dataTypeIndex, dimIndex, fixPtIdx
   */
  {
    0, (NULL), (NULL), 0, 0, 0
  }
};

次の例では、構造体 rtwCAPI_BlockParameters のすべてのメンバーが NULL または 0 値に設定された、最後の省略された配列要素が生成されます。これは、CAPIModel モデル例では、[既定のパラメーター動作] が既定で [インライン] に設定されているためです。[既定のパラメーター動作] を [調整可能] に設定すると、ブロックパラメーターが rtwCAPI_BlockParameters 構造体に生成されます。ただし、MATLAB 変数と調整可能なパラメーターは rtwCAPI_ModelParameters 構造体に表示されます。

CAPIModel_capi.c で既定の設定で生成される配列 rtModelParameters を次に示します。

/* Tunable variable parameters */
static const rtwCAPI_ModelParameters rtModelParameters[] = {
  /* addrMapIndex, varName, dataTypeIndex, dimIndex, fixPtIndex */
  { 2, TARGET_STRING("Ki"), 0, 0, 0 },

  { 3, TARGET_STRING("Kp"), 0, 0, 0 },

  { 4, TARGET_STRING("p1"), 0, 2, 0 },

  { 5, TARGET_STRING("p2"), 0, 3, 0 },

  { 6, TARGET_STRING("p3"), 0, 4, 0 },

  { 0, (NULL), 0, 0, 0 }
};

次の例で、配列 rtModelParameters には調整可能な Simulink ブロックパラメーターとして参照される各変数のエントリが含まれます。

たとえば、4 番目のパラメーターの varName (変数名) は p2 です。C API 信号に示されている類似の名前の信号に対応したその他のフィールドも次のように同様です。

4 番目のパラメーターのアドレスは addrMapIndex によって指定され、この例では 5 となります。このアドレスは配列 rtDataAddrMap へのインデックスを提供し、CAPIModel_capi.c で後に検出されます。インデックスはゼロベースであるため、5 は rtDataAddrMap の 6 番目の要素 (rtP_p2) に対応します。
dataTypeIndex は配列 rtDataTypeMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、パラメーターのデータ型を示します。値 0 は倍精度で非複素数のパラメーターに対応します。
dimIndex (次元インデックス) は配列 rtDimensionMap へのインデックスを提供し、CAPIModel_capi.c で後に検出されます。値 3 は 4 番目のエントリ (つまり { rtwCAPI_MATRIX_COL_MAJOR, 6, 2, 0 }) に対応します。
fixPtIndex(固定小数点インデックス) は配列 rtFixPtMap へのインデックスを提供し、CAPIModel_capi.c で後に検出され、パラメーターに関する固定小数点情報を示します。対応する信号属性と同様に、ゼロの固定小数点マップインデックスは、パラメーターに固定小数点情報が含まれないということを意味します。

生成されたコードにおける調整可能なパラメーターストレージの詳細については、生成されたコードによる内部信号、状態、パラメーターデータの保存方法を参照してください。

C API データ構造体の rtModel へのマッピング

リアルタイムモデルデータ構造体はモデルデータとモデルを完全に説明する関連情報をカプセル化します。C API 機能を選択してコードを生成すると、Simulink Coder コードジェネレーターは model.h で生成されたリアルタイムモデルデータ構造体に別のメンバーを追加します。

/*
 * DataMapInfo:
 * The following substructure contains information regarding
 * structures generated in the model's C API.
 */
struct {
  rtwCAPI_ModelMappingInfo mmi;
} DataMapInfo;

このメンバーはタイプ struct rtwCAPI_ModelMappingInfo の mmi (モデルマッピング情報) を定義します。構造体は matlabroot/rtw/c/src/rtw_modelmap.h に配置されます。mmi サブ構造体はモデルと C API ファイル間のインターフェイスを定義します。また特に、mmi のメンバーは model_capi.c (または .cpp) の構造体にリアルタイムモデルデータ構造体をマッピングします。

構造体の C API 配列間へのモデルのマッピングに示すように、配列の mmi メンバーの値を初期化すると、マッピングが達成されます。各メンバーは生成された C API ファイルの構造体の配列のいずれかを指します。たとえば、構造体配列 rtBlockSignals のアドレスはrtw_modelmap.h ファイルで次のコードを使用して、model.c (または .cpp) でサブ構造体 mmi の最初のメンバーに割り当てられます。

/* signals */
struct {
    rtwCAPI_Signals const *signals;     /* Signals Array */
    uint_T                numSignals;   /* Num Signals   */
    rtwCAPI_Signals const *rootInputs;  /* Root Inputs array */
    uint_T               numRootInputs; /* Num Root Inputs  */
    rtwCAPI_Signals const *rootOutputs; /* Root Outputs array */
    uint_T               numRootOutputs;/* Num Root Outputs  */
} Signals;

model.c (または .cpp) のモデル初期化関数は C API 初期化関数を呼び出すことで初期化を実行します。たとえば、次のコードはモデル例 CAPIModel のモデル初期化関数で生成されます。

/* Initialize DataMapInfo substructure containing ModelMap for C API */
CAPIModel_InitializeDataMapInfo(CAPIModel_M);

構造体の C API 配列間へのモデルのマッピング

メモ

この図では、構造体が rtw_modelmap.h に表示される順序の配列を示しており、これは model_capi.c で生成された順序とは若干異なります。

ターゲットシステムとデータを交換するための C API データ定義ファイルの生成

ライブスクリプトを開く

この例では、ターゲットベースの C API を使用して、信号、状態、パラメーターおよびルートレベルの I/O を表す生成コードとのインターフェイスをとる方法を説明します。

モデル例を開く

モデル例 CAPIModel を開きます。

open_system('CAPIModel');

C API は、プログラム実行を停止したり、生成コードの再コンパイルを行わずに生成コードのアプリケーションデータを操作する場合に役立ちます。C API インターフェイスを使用するには、最上位モデルとその参照モデルについて、以下を行います。

1. 開発用コンピューターとターゲットコンピューターの間で、クライアント/サーバープロトコル (TCP/IP またはデュアルポートメモリ接続) を設定します。

2. 少なくとも 1 つの C API モデルコンフィギュレーションパラメーター ([信号]、[パラメーター]、[状態]、および [ルートレベル I/O]) を選択します。

3. アドレス指定可能なストレージクラスを使用して C API にアクセスするデータ要素を設定します。

最上位モデルと参照モデルの C API コンフィギュレーション設定が一致しなければなりません。

コードジェネレーターは、C API インターフェイスをファイル model_capi.c に配置します。コンフィギュレーション設定に応じて、データは、アドレス指定可能なストレージクラスを使用して設定される信号、状態、パラメーターおよびルートレベル I/O を表すことができます。ファイルにはデータプロパティへのインターフェイスを提供する構造体が含まれます。

C API 制限

C API 機能には次の制限があります。

C API では TLC 変数 CodeFormat に対して次の値はサポートされません。
- S-Function
- Accelerator_S-Function (高速シミュレーション用)
ERT ベースのターゲットの場合、C API では浮動小数点コードのサポートが有効になっていなければなりません。
ローカルブロック出力信号はサポートされていません。
ローカルな Stateflow パラメーターはサポートされていません。
次のカスタムストレージクラスオブジェクトはサポートされていません。
- csc_registration ファイルのないオブジェクト
- グループ化されたカスタムストレージクラス
- マクロを使用して定義されるオブジェクト
- BitField オブジェクト
- FileScope オブジェクト
C API を使用する場合、カスタマイズされたデータ配置は無効になります。インターフェイスについては、model.h および model_private.h の中のグローバルデータ宣言が参照されます。カスタマイズされたデータ配置によりその他のファイルに配置された宣言はコンパイルされないコードとなります。

メモ

ERT システムターゲットファイルを使用し、モデルコンフィギュレーションパラメーターの [カスタムストレージクラスを無視する] がオフになっている場合にのみ、カスタムストレージクラスオブジェクトはコード生成において機能します。