Main Content

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

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

一部の Simulink® Coder™ アプリケーションでは、あるモデル用に生成されたコードの信号、状態、ルートレベル入力/出力またはパラメーターと対話しなければなりません。たとえば、キャリブレーション アプリケーションはパラメーターを監視および変更します。信号の監視またはデータ ログを行うアプリケーションは、信号、状態、およびルートレベル入力/出力データと対話します。Simulink Coder 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 が選択された生成ファイル

メモ

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

C API ファイルの生成

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

  1. モデルの C API インターフェイスを選択します。モデルの C API インターフェイスを選択する方法は 2 つあります。これらについては次の各節で説明します。

  2. モデルのコードを生成します。

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

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

  1. モデルを開き、[コンフィギュレーション パラメーター] ダイアログ ボックスを開きます。

  2. [コード生成][インターフェイス] ペインの [データ交換インターフェイス] サブグループで 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 ファイルの説明

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

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 データ型です。この構造体のメンバーはデータ型、次元、および固定小数点の構造体配列に対して変数名、アドレス、およびインデックスを提供します。

  • rtDataAddrMaprtBlockSignalsrtBlockParametersrtBlockStates、および配列 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 構造体について、モデル例 rtwdemo_capi を使用して説明します。モデル例からコードを生成するには、次の手順に従います。

  1. 上記の rtwdemo_capi リンクをクリックするか、MATLAB コマンド ラインに rtwdemo_capi を入力してモデルを開きます。

  2. rtwdemo_capi でルートレベル入力/出力の C API 構造体を生成する場合、モデル コンフィギュレーション パラメーター [C API の生成: ルートレベル I/O] を選択します。

    このパラメーターの設定は、最上位モデルと参照モデルの間で一致しなければなりません。パラメーター設定を変更する場合、最上位モデルと参照モデルを書き込み可能な同じ作業フォルダーに保存します。

  3. モデルのコードを生成します。

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

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

  • top_sig1: 最上位モデルの Gain1 ブロックの出力のテスト ポイントです。

  • sig2_eg: 最上位モデルに表示され、ストレージ クラス ExportedGlobal をもつ Simulink.Signal オブジェクトとしてベース ワークスペースで定義されます。

  • bot_sig1: 参照モデル rtwdemo_capi_bot に表示され、ストレージ クラス Model default をもつ Simulink.Signal オブジェクトとして定義されます。

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

  • top_state: 最上位モデルの Delay1 ブロックで定義されます。

  • bot_state: 参照モデルの Discrete Filter ブロックで定義されます。

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

  • 4 つのルートレベル入力 In1In4

  • 6 つのルートレベル出力 Out1Out6

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

  • Kp (最上位モデル Gain1 ブロックおよび参照モデル Gain2 ブロックが共有)

  • Ki (参照モデル Gain3 ブロック)

  • p1 (ルックアップ テーブル lu1d)

  • p2 (ルックアップ テーブル lu2d)

  • p3 (ルックアップ テーブル lu3d)

C API 信号

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

rtwdemo_capi の最上位モデルの C API 信号の情報を提供する rtwdemo_capi_capi.c のコードを次に示します。

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

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

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

メモ:

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

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

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

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

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

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

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

/* Declare Data Addresses statically */
static void* rtDataAddrMap[] = {
  &rtwdemo_capi_B.top_sig1,            /* 0: Signal */
  &sig2_eg[0],                         /* 1: Signal */
  &rtwdemo_capi_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 は静的に宣言されます。再利用可能なコードを生成する場合、インスタンスごとにアドレスを動的に初期化する初期化関数が生成されます (再利用可能なコードの生成方法の詳細については、モデルのエントリポイント関数用のコード生成の構成およびConfigure Code Reuse Support (Embedded Coder)を参照してください)。

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

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

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

メモ

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

C API 状態

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

rtwdemo_capi の最上位モデルの C API 状態の情報を提供する rtwdemo_capi_capi.c のコードを次に示します。

/* Block states information */
static const rtwCAPI_States rtBlockStates[] = {
  /* addrMapIndex, contStateStartIndex, blockPath,
   * stateName, pathAlias, dWorkIndex, dataTypeIndex, dimIndex,
   * fixPtIdx, sTimeIndex, isContinuous
   */
  { 2, -1, "rtwdemo_capi/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, "rtwdemo_capi/Delay1",
    "top_state", "", 0, 0, 0, 0, 0, 0 },

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

  • 信号のアドレスは addrMapIndex によって指定され、この例では 2 となります。このアドレスは配列 rtDataAddrMap へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出されます。インデックスはゼロ ベースであるため、2rtDataAddrMap の 3 番目の要素 (&rtwdemo_capi_DWork.top_state) に対応します。

  • dataTypeIndex は配列 rtDataTypeMap へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出され、パラメーターのデータ型を示します。値 0 は倍精度で非複素数のパラメーターに対応します。

  • dimIndex (次元インデックス) は配列 rtDimensionMap へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出されます。値 0 は最初のエントリ (つまり { rtwCAPI_SCALAR, 0, 2, 0 }) に対応します。

  • fixPtIndex(固定小数点インデックス) は配列 rtFixPtMap へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出され、パラメーターに関する固定小数点情報を示します。対応する信号属性と同様に、ゼロの固定小数点マップ インデックスは、パラメーターに固定小数点情報が含まれないということを意味します。

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

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

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

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

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

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

  { 6, 0, "rtwdemo_capi/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, "rtwdemo_capi/Out1",
    "", 1, 0, 0, 0, 0 },

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

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

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

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

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

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

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 値に設定されたすべての要素をもつ省略された要素です。

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

rtwdemo_capi_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 へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出されます。インデックスはゼロ ベースであるため、5rtDataAddrMap の 6 番目の要素 (rtP_p2) に対応します。

  • dataTypeIndex は配列 rtDataTypeMap へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出され、パラメーターのデータ型を示します。値 0 は倍精度で非複素数のパラメーターに対応します。

  • dimIndex (次元インデックス) は配列 rtDimensionMap へのインデックスを提供し、rtwdemo_capi_capi.c で後に検出されます。値 3 は 4 番目のエントリ (つまり { rtwCAPI_MATRIX_COL_MAJOR, 6, 2, 0 }) に対応します。

  • fixPtIndex(固定小数点インデックス) は配列 rtFixPtMap へのインデックスを提供し、rtwdemo_capi_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_ModelMappingInfommi (モデル マッピング情報) を定義します。構造体は 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 初期化関数を呼び出すことで初期化を実行します。たとえば、次のコードはモデル例 rtwdemo_capi のモデル初期化関数で生成されます。

/* Initialize DataMapInfo substructure containing ModelMap for C API */
rtwdemo_capi_InitializeDataMapInfo(rtwdemo_capi_M);

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

メモ

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

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

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

モデル例を開く

モデル例 rtwdemo_capi を開きます。

open_system('rtwdemo_capi');

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

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

2.[コンフィギュレーション パラメーター] ダイアログ ボックスの [コード生成]、[インターフェイス] ペインで、次の C API パラメーターを少なくとも 1 つ選択します。[信号][パラメーター][状態] および [ルートレベル 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 システム ターゲット ファイルを使用し、モデル コンフィギュレーション パラメーターの [カスタム ストレージ クラスを無視する] がオフになっている場合にのみ、カスタム ストレージ クラス オブジェクトはコード生成において機能します。

関連するトピック