このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

モデルまたはサブシステムの S-Function ターゲットの使用

S-Function は、コード ジェネレーターがコードを生成できるシステム ターゲット ファイルのクラスです。S-Function ターゲットにサブシステムをカプセル化することにより、実行効率性を高め、コードの再利用を容易にし、知的所有権を保護できます。

メモ

S-Function ターゲットを使用して、内部ロジックを検査や修正から保護しながら再利用のためにアプリケーション コンポーネントを展開できますが、配布されるコンポーネントの知的財産を保護するための推奨ソリューションには次のものがあります。

• 保護モデルは、ブロックとコード行の情報を隠した参照モデルです。詳細については、コンテンツを隠すためのモデルの保護を参照してください。

• Simulink^® 外部のシステム シミュレーションに使用するモデルまたはサブシステム用の共有ライブラリを生成するのに使用される、共有ライブラリ システム ターゲット ファイル。詳細については、生成コードを共有ライブラリとしてパッケージ化 (Embedded Coder)を参照してください。

これらのソリューションにより、実行効率性も向上し、コードの再利用も容易になります。

生成された S-Function ターゲットは Generated S-Function ブロックで使用できます。

S-Function ターゲットによって使用される TLC 変数 CodeFormat の値を 'S-Function' に設定すると、Simulink C MEX S-Function アプリケーション プログラミング インターフェイス (API) に対応するコードが生成されます。

S-Function の展開に必要なファイル

シミュレーションとコード生成用に生成された S-Function ブロックを展開するには、さまざまなファイルが必要です。

生成された S-Function ブロックを展開して "シミュレーション用" の他のモデルにインクルードするには、その S-Function ブロックが生成された時点で作業フォルダーに生成されたバイナリ MEX ファイル オブジェクトだけを提供する必要があります。必要なファイルは以下のとおりです。

• subsys_sf.mexext

ここで、subsys はサブシステム名で、mexext はプラットフォームに依存する MEX ファイルの拡張子です (mexextを参照)。例: SourceSubsys_sf.mexw64。

生成された S-Function ブロックを展開して "コード生成用" に他のモデルにインクルードするには、その S-Function ブロックが生成された時点で作業フォルダーに生成されたすべてのファイルを提供します。必要なファイルは以下のとおりです。

• subsys_sf.c または .cpp、ここで subsys はサブシステム名 (たとえば、SourceSubsys_sf.c)

• subsys_sf.h

• subsys_sf.mexext、ここで mexext はプラットフォームに依存する MEX ファイルの拡張子 (mexextを参照)

• サブフォルダー subsys_sfcn_rtw とその内容

S-Function ターゲットで使用するために、rtwsfcn.tlc システム ターゲット ファイルが提供されています。

生成された S-Function コードは、関数がビルドされたホスト システムに一致する [コンフィギュレーション パラメーター] 、 [ハードウェア実行] パラメーター値を使用します。コード生成用のモデルで S-Function を使用する場合、モデルのこれらのパラメーター値が S-Function のパラメーター値と一致することを確認してください。

生成された S-Function でのサンプル時間の伝播

一定の基準が満たされている場合、生成された S-Function ブロックはそのモデルからそのサンプル時間を継承できます。Model ブロックと生成された S-Function ブロックの間でのサンプル時間の伝播を制御する条件は、参照モデルのサンプル時間とサンプル時間継承ルールを指定する S-Functionに説明されています。

サンプル時間の継承の基準を満たす S-Function ブロックを生成するには、S-Function ブロックを生成するモデルのソルバーを制限しなければなりません。モデル コンフィギュレーション パラメーター [タイプ] を [固定ステップ] に、[周期的なサンプル時間の制約] を [サンプル時間に依存しない] に設定します。モデルがサンプル時間を継承できない場合、この設定はモデルのビルド時に Simulink ソフトウェアがエラー メッセージを出す原因になります。このオプションの詳細については、Periodic sample time constraintを参照してください。

生成された S-Function をもつ最上位モデルのソルバー タイプ

以下の表に、最上位モデル ソルバー タイプで取りうる組み合わせを示します。これらのタイプは、生成された S-Function 用の離散サンプル時間または連続サンプル時間とソルバー タイプがモデルにあるかどうかに関連します。

最上位モデル ソルバー オプションとサンプル時間

	モデル コンフィギュレーション パラメーター: 最上位モデル コンフィギュレーション
サンプル時間	ソルバー オプション、タイプ: 可変ステップ	ソルバー オプション、タイプ: 固定ステップ
離散	生成された S-Function には可変ステップ ソルバーが必要	生成された S-Function は可変ステップ ソルバーまたは固定ステップ ソルバーをもつことが可能
連続	生成された S-Function には可変ステップ ソルバーが必要	生成された S-Function には固定ステップ ソルバーが必要

サブシステムから生成される S-Function には、ブロックにハードコードされるパラメーターがあります。Simulink では、シミュレーションの実行時ではなく、ブロックの生成時に、サンプル時間などのパラメーターが計算されます。生成された S-Function ブロックがデスティネーション モデルで予期したように機能するかどうかを確認することが重要です。

生成された S-Function での調整可能なパラメーター

生成された S-Function で調整可能なパラメーターを使用するには、モデル コンフィギュレーション パラメーターを使用して目的のブロック パラメーターを調整可能として宣言します。[モデル パラメーター設定] ダイアログ ボックスを使用した、ワークスペース変数の調整可能なパラメーターとしての宣言を参照してください。

ソース モデルで [Auto] ストレージ クラスを使用して調整可能と宣言したブロック パラメーターは、生成された S-Function で調整可能なパラメーターになります。これらのパラメーターは他のシステム ターゲット ファイルから生成されたコードの場合とは違い、生成された model_P (正式には rtP) パラメーター データ構造体の一部にはなりません。代わりに、mxGetPr や mxGetData のような MEX API 呼び出しを使用して、生成されたコードはこれらのパラメーターにアクセスします。ユーザーのコードも同じ方法でこれらのパラメーターにアクセスしなければなりません。

MEX API の呼び出しの詳細については、About C MEX S-Functionsおよび外部プログラミング言語およびシステムと MATLAB の統合を参照してください。

S-Function ターゲットを使用して作成された S-Function ブロックは自動的にマスクされます。マスクは編集フィールドで調整可能なパラメーターごとに表示されます。既定の設定では、次の例のように、編集フィールドはパラメーターを変数名で表示します。

モデル コンフィギュレーション パラメーター [調整可能なパラメーターの値を使用] を選択することで、変数名ではなくパラメーターの値を表示するよう選択できます。

このパラメーターを選択すると、編集フィールドに (コード生成時の) 変数の値が表示されます。

マクロ パラメーター

生成コードでパラメーターがマクロとして現れるように、Define のようなストレージ クラスを Simulink.Parameter オブジェクトに適用すると仮定します。ERT S-Function の生成元のサブシステム内のパラメーター オブジェクトを使用する場合、このパラメーター オブジェクトは調整可能なパラメーターとして選択できません。代わりに、S-Function コード ジェネレーターは、パラメーター オブジェクトにカスタム ストレージ クラスを適用します。S-Function コード内のこのマクロ生成によって、Variant Subsystem ブロックのようなバリアント要素を含むサブシステムから S-Function を生成でき、生成コード内でプリプロセッサ条件を生成するように構成できます。ただし、S-Function のシミュレーション中はパラメーターの値を変更できません。

パラメーター オブジェクトを調整可能なパラメーターとして選択するには、別のストレージ クラスを適用するか、独自のストレージ クラスを作成します。パラメーターをマクロとして扱うカスタム ストレージ クラスには、Define、ImportedDefine、CompilerFlag およびカスタム ストレージ クラス デザイナーで [データの初期化] を [マクロ] に設定して作成したストレージ クラスがあります。マクロではないストレージ クラスを使用する場合、パラメーター オブジェクトをバリアント制御変数として使用してプリプロセッサ条件を生成することはできません。

パラメーター オブジェクトをインポートされたマクロとして扱うストレージ クラスを適用する場合、関数 ERT S-Function を生成する前にマクロ定義を指定します。たとえば、ストレージ クラス ImportedDefine を Simulink.Parameter オブジェクトに適用して、サブシステム内でパラメーター オブジェクトをバリアント制御変数として使用すると仮定します。カスタム属性 HeaderFile を 'myHdr.h' に設定する場合、S-Function を生成するときにカスタム ヘッダー ファイル myHdr.h を現在のフォルダーに置きます。生成された S-Function では、パラメーター オブジェクトの Value プロパティの値ではなく、ヘッダー ファイルのマクロの値が使用されます。

コンパイラ オプションによって定義されるマクロ (たとえば、ストレージ クラス CompilerFlag を適用する) を使用するには、モデル コンフィギュレーション パラメーター [コード生成] 、 [カスタム コード] 、 [コード情報] 、 [定義] を使用してコンパイラ オプションを指定します。詳細については、[コード生成] ペイン: カスタム コード: 追加のビルド情報: 定義を参照してください。

チェックサムと S-Function ターゲット

コード ジェネレーターはモデル用のチェックサムを作成し、そのビルド プロセスで、コードの再利用機能、モデル参照機能およびエクスターナル モード機能用にチェックサムを使用します。

コード ジェネレーターは次の方法でモデルのチェックサムを計算します。

1. モデルでサブシステムごとにチェックサムを計算します。サブシステムのチェックサムは、サブシステムのブロックのプロパティ (データ型、実数/複素数、サンプル時間、端子の次元など) の組み合わせになります。

2. サブシステムのチェックサムと他のモデル レベルの情報を組み合わせます。

S-Function は関数 ssSetChecksumVal を呼び出してチェックサムに付加情報を追加できます。この付加情報はブロック プロパティ解析中に取得されません。S-Function ターゲットの場合、チェックサムに追加される値は S-Function を生成する元のモデルまたはサブシステムのチェックサムです。

コード ジェネレーターはサブシステムとモデルのチェックサムを以下の用途に使用します。

• コードの再利用 — モデル内の 2 つのサブシステムのチェックサムが同じ場合、コード ジェネレーターは 1 つの関数用だけのコードを生成します。

• モデル参照 — 現在のモデルのチェックサムがモデル作成時のチェックサムと同じ場合、ビルド プロセスは参照モデルをリビルドしません。

• エクスターナル モード — 現在のモデルのチェックサムがターゲット ハードウェアで実行中のコードのチェックサムと一致しない場合、ビルド プロセスでエラーが発生します。

生成された S-Function の互換性

モデルから MEX S-Function をビルドすると、コード ジェネレーターはレベル 2 のインラインでない S-Function をビルドします。生成コードとバイナリ MEX ファイル (*.mexw64 など) のリリースをまたがる使用には、次のような制限があります。

• 以前の MATLAB^® リリース ソフトウェアからの S-Function ターゲット生成コードは、新しいリリースと互換性がありません。以前のリリースの生成コードを新しい MATLAB リリース ソフトウェアで再コンパイルしないでください。同じ MATLAB リリース ソフトウェアを使用して S-Function ターゲットのコードを生成し、そのコードを MEX ファイルにコンパイルしてください。

• 以前の MATLAB リリース ソフトウェアから生成されたバイナリ S-Function MEX ファイルは、手書きの S-Function と同じ互換性注意事項の下で同じリリースまたはより新しいリリースと共に使用できます。詳細については、S-Function Compatibilityを参照してください。

• コード ジェネレーターは、生成された S-Function を含むモデルからコードを生成したり実行可能ファイルをビルドしたりできます。このサポートについては、モデルをビルドしたのと同じ MATLAB リリース ソフトウェアで S-Function をビルドする必要があります。以前の MATLAB リリース ソフトウェアで生成された S-Function MEX ファイルをモデルに組み込み、より新しいリリースでモデルをビルドすることはできません。

S-Function ターゲットの制限

• 連続サンプル時間をもつ Inport ブロックおよび Outport ブロック

• 式内の調整可能な変数

• パラメーターの調整

• ランタイム パラメーターと S-Function の互換性診断

• Goto ブロックと From ブロック

• S-Function の作成と更新

• サポートされていないブロック

• コード生成でサポートされないモデルの操作点

• S-Function の入れ子構造

• ユーザー定義のデータ型

• S-Function ターゲットの右クリックによる生成

• バスの入力と出力

• 関数呼び出しの入力信号と出力信号をもつサブシステム

• Function-Call Subsystem のモデル化パターン

• データ ストアへのアクセス

• サブシステム マスクによる Inport ブロックまたは Outport ブロックのパラメーター

• MEX S-Function ラッパー

連続サンプル時間をもつ Inport ブロックおよび Outport ブロック

S-Function の生成を右クリックでのビルドで行う方法では、Inport ブロックおよび Outport ブロックで連続サンプル時間が保持されません。サンプル時間が保持されないため、生成された S-Function ブロックのシミュレーションが影響を受ける可能性があります。

式内の調整可能な変数

式で調整可能な変数を使用する場合、一定の制限があります。コード ジェネレーターでコードの生成中にサポートされない式が検出されると、警告が表示されて、等価の数値がコードに生成されます。制限の一覧については、調整可能な式の制限を参照してください。

パラメーターの調整

S-Function ブロックは、以下と共に使用する調整可能なパラメーターの調整をサポートしていません。

• 複素数値

• 定数に変換される値またはデータ型 (モデル コンフィギュレーション パラメーター [最適化] 、 [既定のパラメーター動作] を [インライン] に設定)。

• 組み込まれていないデータ型

• 同等の組み込み型がない浮動小数点データ型。

ランタイム パラメーターと S-Function の互換性診断

モデル コンフィギュレーション パラメーター [アップグレードの必要な S-function] を [警告] または [エラー] に設定すると、サブシステムから生成された S-Function をアップグレードするようにコード ジェネレーターから指示されます。S-Function システム ターゲット ファイルではランタイム パラメーターが登録されません。ランタイム パラメーターはインライン化された S-Function だけでサポートされており、生成された S-Function はインライン化される (たとえば、他のインラインでない S-Function を呼び出したり含んだりすることができる) ことを回避する機能をサポートします。

この制限を回避するには、パラメーター [アップグレードの必要な S-function] を [なし] に設定します。

Goto ブロックと From ブロック

S-Function システム ターゲット ファイルを使用する場合、コード ジェネレーターは入力および出力の対象をルート モデルの Inport ブロックと Outport ブロック (または S-Function ターゲットを生成する元になった Subsystem ブロックの Inport ブロックと Outport ブロック) に制限します。コード ジェネレーターは、Goto ブロックまたは From ブロックのコードを生成しません。

この制限を回避するには、Goto ブロックと From ブロックを使用してルート モデルとサブシステムの間でデータを渡すのではなく、必要な Inport ブロックと Outport ブロックをもつモデルとサブシステムを作成します。そして、生成された S-Function を組み込んだモデルに、Goto ブロックと From ブロックを追加します。

制限を回避しない例

• From ブロックとサブシステム Subsystem1 を含むルート モデル

  

• グローバル可視性をもち、入力をルート モデルの From ブロックに渡す Goto ブロックを含む Subsystem1

  

• S-Function システム ターゲット ファイルで生成された S-Function で置き換えられる Subsystem1 — 生成された S-Function は Goto ブロックを実装していないため、モデルを実行すると警告が出る

  

制限を回避した例

Subsystem1 の GoTo ブロックを Outport ブロックで置き換えます。生成された S-Function をルート モデルに接続すると、その出力は To Workspace ブロックに直接接続されます。

S-Function の作成と更新

S-Function システム ターゲット ファイルを使用する S-Function の作成と更新については、次の制限があります。

• S-Function システム ターゲット ファイルを使用する Model ブロックを含むモデルを作成することはできません。これは、サブシステムに Model ブロックが含まれている場合、コンテキスト メニューの右クリックを使用してサブシステムを作成できないという意味でもあります。これは S-Function ターゲットを使用して生成された S-Function だけの制限で、ERT S-Function では制限はありません。

• 以下を使用してモデルをビルドできます。

  • ツールチェーン (ツールチェーンが MEX ファイルの生成をサポートする場合のみ)。

  • テンプレート makefile (テンプレート makefile が、MEX ファイルの生成をサポートするツールチェーンに関連付けられている場合のみ)。

• S-Function ブロックを生成したモデルを変更する場合、ビルド プロセスは生成された S-Function ブロックを含むモデルを自動的にリビルドしません。これは Model ブロックで参照されたモデルが (モデル参照の [リビルド] コンフィギュレーション設定により) 変更される場合に自動的にリビルドされることとは対照的です。

• 対応する TLC ファイルのない手書きの S-Function は例外のないコードを含まなければなりません。例外のないコードの詳細については、Exception Free Codeを参照してください。

サポートされていないブロック

S-Function 形式は以下の組み込みブロックをサポートしません。

• Interpreted MATLAB Function ブロック

• 次のいずれかを含む S-Function ブロック

  • MATLAB 言語 S-Function (C コード生成用の TLC ファイルがない場合)

  • Fortran S-Function (C コード生成用の TLC ファイルがない場合)

  • MATLAB 環境を呼び出す C/C++ MEX S-Function

• Simulink Function ブロック

• Function Caller ブロック

• Scope ブロック

• To Workspace ブロック

S-Function 形式は、embeddedtargetslib ブロック ライブラリからのブロックをサポートしません。

コード生成でサポートされないモデルの操作点

モデルの操作点を利用する C-MEX とレベル 2 の MATLAB S-Function を記述できます。これを使用して、シミュレーション状態を保存し復旧できます。モデルの操作点は S-Function システム ターゲット ファイルを含むコード生成はサポートしません。

既定の操作点準拠または操作点サポートなしを指定する S-Function のコードを生成すると、生成されたコードには、モデルの操作点機能が含まれません。カスタムの操作点機能を実装する S-Function のコードは生成できません。

S-Function の入れ子構造

生成された S-Function ブロックをモデルやサブシステム内で入れ子構造にして、それから他の S-Function を生成する場合には次の制限があります。

• ソフトウェアは入れ子構造の S-Function について非バーチャル バスの入力と出力をサポートしません。

• S-Function と同じ名前をもつモデルやサブシステム内で (数レベル離れている場合もあります) S-Function を入れ子にするのは避けてください。このような状況では、S-Function は再帰的に呼び出される可能性があります。ソフトウェアは現状ではこのような S-Function のループを検出しないため、MATLAB セッションの中止やハングアップにつながる結果になります。このような事態を防ぐには、MATLAB のパス上の既存の MEX ファイル名を複製しないようにするために、S-Function ターゲットとして生成される予定のサブシステムやモデルに一意な名前を付けます。

ユーザー定義のデータ型

S-Function システム ターゲット ファイルは、Simulink.AliasType、Simulink.Bus および Simulink.NumericType オブジェクトに基づくものも含む、ユーザー定義のデータ型で指定される HeaderFile プロパティをサポートしません。モデルでユーザー定義されたデータ型が HeaderFile プロパティを使用して関連するヘッダー ファイルを指定する場合、S-Function システム ターゲット ファイルを使用するコード生成はその値を無視し、対応するインクルード文を生成しません。

S-Function ターゲットの右クリックによる生成

Function-Call Subsystem ブロックを右クリックして S-Function ターゲットを生成すると、元のサブシステムと生成された S-Function の間の整合性を確保できないことがあります。不整合が発生するのは、Function-Call Subsystem ブロック内の Trigger Port ブロックの [イネーブル時の状態] パラメーターが [継承] に設定されている場合です。[イネーブル時の状態] パラメーターは、[リセット] または [保持] に設定しなければなりません。それ以外の設定では Simulink でエラーが発生します。

バスの入力と出力

S-Function ターゲットを使用して生成された S-Function にバスの入力または出力がある場合、生成されたバス データ構造体にはバス要素に関するフィールドと、シミュレーション中に使用される Simulink の表現を整合させるためのパディングが含まれている可能性があります。ただし、モデルに S-Function を挿入して、grt.tlc のようなモデル ターゲットを使用するコードを生成する場合、モデル ビルドのために生成されたバス構造体の配置が S-Function に対して生成されたパディングと一致せずに、コード実行の数値結果に影響を与える場合があります。モデル シミュレーションとモデル コードの実行の間で構造体の配置を整合させるには、それぞれの Simulink.Bus オブジェクトに対して、HeaderFile プロパティを変更して、パディングされていないバス構造体ヘッダー ファイルを削除します。その結果、S-Function のために生成されたバスの typedef がモデルのコードで再利用されます。

関数呼び出しの入力信号と出力信号をもつサブシステム

S-Function ターゲットでは、関数呼び出しのトリガー入力または関数呼び出し出力をもつサブシステムからの S-Function ブロックの作成をサポートしません。

Function-Call Subsystem のモデル化パターン

生成された S-Function ブロックをモデルに追加してシミュレートしたときに、生成された S-Function で次のような Function-Call Subsystem のモデル化パターンが使用されていると MATLAB がクラッシュする可能性があります。

この Function-Call Subsystem は Outport ブロックに直接接続されています。サブシステムを Outport ブロックに接続する信号線が関数 Update をもつブロック、つまり各メジャー タイム ステップで更新される Unit Delay や Memory などのブロックに分岐しています。分岐はサブシステムの内側にある場合も外側にある場合もあります。

このような Function-Call Subsystem を含むモデルでは、次のいずれかの位置に Signal Conversion ブロックを配置することで、生成された S-Function での問題を回避できます。

1. サブシステム ブロックと分岐の間

2. 分岐とルートの Outport ブロックの間

3. 分岐と関数 Update をもつブロックの間

この回避策における Signal Conversion ブロックのパラメーター設定は次のとおりです。

• [出力] を [信号のコピー] に設定

• ['ブロック削減' の最適化からこのブロックを排除する] を選択

データ ストアへのアクセス

モデル内の S-Function ブロックがシミュレーション中にデータ ストアにアクセスする場合、Simulink はデータ ストアの診断を無効にします。

• モデルから S-Function ブロックを作成した場合、診断はグローバル データ ストアに対しても無効となります。

• サブシステムから S-Function ブロックを作成した場合、診断は次のデータ ストアに対して無効となります。

  • グローバル データ ストア

  • サブシステムの外部に配置され、Data Store Read ブロックまたは Data Store Write ブロックによってアクセスされるデータ ストア

サブシステム マスクによる Inport ブロックまたは Outport ブロックのパラメーター

Inport ブロックまたは Outport ブロックのパラメーターがサブシステム マスク変数で指定されたサブシステムから生成された S-Function では、その S-Function ブロックを使用するシミュレーションを実行しようとするとエラーが発生します。

Invalid setting in 'testSystem/Subsystem/__OutputSSForSFun__/Out2' 
for parameter 'PortDimensions'
...

MEX S-Function ラッパー

MEX S-Function ラッパーは、ラッパーが作成された MATLAB バージョンでのみ使用します。

関連するトピック

• コンテンツを隠すためのモデルの保護
• RSim システム ターゲット ファイルを使用したホスト コンピューターでのハイブリッド動的システムの高速化、調整およびテスト
• C/C++ S-Function の基礎
• S-Function とコード生成
• レガシ コード ツールによって外部コードへの呼び出しを生成コードにインポート
• Use a Bus with S-Function Builder to Create an S-Function