モデルまたはサブシステムの 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 ブロックは自動的にマスクされます。マスクは編集フィールドで調整可能なパラメーターごとに表示されます。既定の設定では、次の例のように、編集フィールドはパラメーターを変数名で表示します。

Block parameter dialog box for generated S-Function that shows parameter by variable name

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

S-function target model configuration parameters with parameters Create new model and Use value for tunable parameters selected

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

Block parameter dialog box for generated S-Function that shows parameter by variable value

マクロパラメーター

生成コードでパラメーターがマクロとして現れるように、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 ターゲット

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

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

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

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 ブロックに直接接続されます。

In subsystem, GoTo block replaced by Outport block

Generated S-function plugged into root model and has output connected to To Workspace block

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 modeling pattern

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

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

サブシステムブロックと分岐の間
分岐とルートの Outport ブロックの間
分岐と関数 Update をもつブロックの間

Locations where you can insert a Signal Conversion block in function-call subsystem modeling pattern

この回避策における 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 バージョンでのみ使用します。