编写二级MATLAB S-Functions - MATLAB & Simulink - MathWorks한국

写二级MATLAB S-Functions

关于二级MATLAB s函数

2级的MATLAB^®S-function API允许您使用MATLAB语言创建具有多个输入和输出端口的自定义块，并能够处理由Simulink产生的任何类型的信号^®模型，包括任意数据类型的矩阵和帧信号。二级MATLAB s函数API与创建C MEX s函数的API密切对应。很多关于创建C MEX s -函数的文档也适用于第2级MATLAB s -函数。为了避免重复，本节重点提供特定于编写Level-2 MATLAB s函数的信息。

二级MATLAB s函数是定义一个实例的属性和行为的MATLAB函数2级MATLAB函数在Simulink模型中引用MATLAB函数的块。MATLAB函数本身包含一组回调方法(参见Level-2 MATLAB S-Function回调方法)，在更新或模拟模型时由Simulink引擎调用。回调方法执行初始化和计算s函数定义的块的输出的实际工作。

为了方便这些任务，引擎将一个运行时对象作为参数传递给回调方法。运行时对象有效地充当了S-Function块的MATLAB代理，允许回调方法在模拟或模型更新期间设置和访问块属性。

关于运行时对象

当Simulink引擎调用二级MATLAB s函数回调方法时，它传递一个实例仿真软件。MSFcnRunTimeBlock类的方法作为一个参数。这个实例被称为S-Function块的运行时对象，对二级MATLAB s -函数回调方法的作用与SimStruct结构服务于C MEX s函数回调方法。该对象使方法能够提供和获取关于块端口、参数、状态和工作向量的各种元素的信息。该方法通过获取或设置块运行时对象的属性或调用方法来实现这一点。的文档请参阅仿真软件。MSFcnRunTimeBlock类获取有关获取和设置运行时对象属性以及调用运行时object方法的信息。

运行时对象不支持MATLAB稀疏矩阵。例如，如果变量块是一个运行时对象，在二级MATLAB s函数中，下面这行代码会产生一个错误:

block.Outport(1)。Data = speye (10);

在哪里speye命令形成一个稀疏单位矩阵。

请注意

除MATLAB s函数外，其他MATLAB程序也可以使用运行时对象来获取被模拟模型中MATLAB s函数的信息。看到在模拟过程中访问块数据在使用仿真软件为更多的信息。

Level-2 MATLAB s -函数模板

使用基本的Level-2 MATLAB s函数模板msfuntmpl_basic.m来开始创建一个新的二级MATLAB s函数。该模板包含二级MATLAB s函数API定义的所需回调方法的框架实现。要编写更复杂的s函数，可以使用带注释的模板msfuntmpl.m。

要创建MATLAB s函数，请制作模板的副本，并根据需要编辑副本，以反映您正在创建的s函数的期望行为。下面两节描述了MATLAB代码模板的内容。一节编写二级MATLAB s函数示例描述了如何编写一个Level-2的MATLAB s函数来模拟一个单位延迟。

Level-2 MATLAB S-Function回调方法

二级MATLAB s函数API定义了组成二级MATLAB s函数的回调方法的签名和一般用途。s函数本身提供了这些回调方法的实现。实现依次决定块属性(例如，端口、参数和状态)和行为(例如，块输出作为时间和块输入、状态和参数的函数)。通过创建一个带有适当回调方法集的s函数，你可以定义一个满足你的应用程序的特定需求的块类型。

二级MATLAB s函数必须包含以下回调方法:

一个设置函数来初始化s函数的基本特征
一个输出函数计算s函数的输出

你的s函数可以包含其他方法，这取决于s函数定义的块的需求。由二级MATLAB s函数API定义的方法通常对应于由C MEX s函数API定义的类似命名的方法。有关这些方法在仿真过程中何时被调用的信息，请参见流程视图在Simulink引擎与C S-Functions的交互。

下表列出了所有的二级MATLAB s函数回调方法及其对应的C MEX方法。

2级MATLAB方法	等价的C MEX方法
`设置`(见使用setup方法)	`mdlInitializeSizes`
`CheckParameters`	`mdlCheckParameters`
`衍生品`	`mdlDerivatives`
`禁用`	`mdlDisable`
`启用`	`mdlEnable`
`InitializeConditions`	`mdlInitializeConditions`
`输出`	`mdlOutputs`
`PostPropagationSetup`	`mdlSetWorkWidths`
`ProcessParameters`	`mdlProcessParameters`
`投影`	`mdlProjection`
`SetInputPortComplexSignal`	`mdlSetInputPortComplexSignal`
`SetInputPortDataType`	`mdlSetInputPortDataType`
`SetInputPortDimensions`	`mdlSetInputPortDimensionInfo`
`SetInputPortDimensionsModeFcn`	`mdlSetInputPortDimensionsModeFcn`
`SetInputPortSampleTime`	`mdlSetInputPortSampleTime`
`SetOutputPortComplexSignal`	`mdlSetOutputPortComplexSignal`
`SetOutputPortDataType`	`mdlSetOutputPortDataType`
`SetOutputPortDimensions`	`mdlSetOutputPortDimensionInfo`
`SetOutputPortSampleTime`	`mdlSetOutputPortSampleTime`
`SimStatusChange`	`mdlSimStatusChange`
`开始`	`mdlStart`
`终止`	`mdlTerminate`
`更新`	`mdlUpdate`
`WriteRTW`	`mdlRTW`

使用`设置`方法

的主体设置method在一个Level-2的MATLAB S-function中初始化相应Level-2的MATLAB S-function块的实例。在这方面，设置方法类似于mdlInitializeSizes和mdlInitializeSampleTimes由C MEX S-functions实现的回调方法。的设置Method执行以下任务:

初始化块的输入和输出端口的数量。
为这些端口设置诸如维度、数据类型、复杂度和采样时间等属性。
指定块采样时间。看到指定样品时间在使用仿真软件更多关于如何指定有效样本时间的信息。
设置s函数对话框参数的数量。
通过将MATLAB s函数中的局部函数句柄传递给RegBlockMethod方法的S-Function块的运行时对象。参见文档仿真软件。MSFcnRunTimeBlock获取有关使用的信息RegBlockMethod方法。

编写二级MATLAB s函数示例

下面的步骤演示了如何编写一个简单的二级MATLAB s函数。在适用的情况下，这些步骤包括s函数示例中的例子msfcn_unit_delay.m在模型中使用msfcndemo_sfundsc2。所有代码行都使用变量名块的s函数运行时对象。

复制第2级MATLAB s函数模板msfuntmpl_basic.m到您的工作文件夹。如果在复制文件时更改了文件名，请更改函数行相同的名称。
修改设置方法来初始化s函数的属性。对于这个示例:
- 设置运行时对象的NumInputPorts和NumOutputPorts属性1为了初始化一个输入端口和一个输出端口。
- 调用运行时object的SetPreCompInpPortInfoToDynamic和SetPreCompOutPortInfoToDynamic方法来指示输入和输出端口从模型继承它们的compiled属性(维度、数据类型、复杂性和采样模式)。
- 设置DirectFeedthrough属性的InputPort来假以表示输入端口没有直接馈通。保留模板文件副本中设置的所有其他输入和输出端口属性的默认值。属性设置的值维,DatatypeID,复杂性属性覆盖使用SetPreCompInpPortInfoToDynamic和SetPreCompOutPortInfoToDynamic方法。
- 设置运行时对象的NumDialogPrms财产1以初始化一个s函数对话框参数。
- 通过设置运行时对象的值，指定s函数具有继承的采样时间SampleTimes财产[1 0]。
- 调用运行时对象的RegBlockMethod方法来注册这个s函数中使用的以下四个回调方法。
  - PostPropagationSetup
  - InitializeConditions
  - 输出
  - 更新
  从模板文件的副本中删除任何其他注册的回调方法。的调用中RegBlockMethod，第一个输入参数是S-function API方法的名称，第二个输入参数是MATLAB S-function中相关局部函数的函数句柄。
以下设置方法从msfcn_unit_delay.m执行前面的步骤列表:
```
function setup(block) %%注册单个对话框参数块。NumDialogPrms = 1;%%输入输出端口块的寄存器数量。NumInputPorts = 1;块。NumOutputPorts = 1;%%设置功能端口属性以动态%%继承。block.SetPreCompInpPortInfoToDynamic;block.SetPreCompOutPortInfoToDynamic;%%硬编码某些端口属性block.InputPort(1)。尺寸= 1;block.InputPort(1)。DirectFeedthrough= false; block.OutputPort(1).Dimensions = 1; %% Set block sample time to [0.1 0] block.SampleTimes = [0.1 0]; %% Register methods block.RegBlockMethod('PostPropagationSetup',@DoPostPropSetup); block.RegBlockMethod('InitializeConditions',@InitConditions); block.RegBlockMethod('Outputs', @Output); block.RegBlockMethod('Update', @Update);
```
如果你的s函数需要连续状态，初始化连续状态的数量设置方法，使用运行时对象的NumContStates财产。的初始化离散状态设置方法。
的离散状态初始化PostPropagationSetup方法。二级MATLAB s函数将离散状态信息存储在DWork向量中。默认的PostPropagationSetup对于这个例子，模板文件中的方法就足够了。
以下PostPropagationSetup方法从msfcn_unit_delay.m,名叫DoPostPropSetup，用名称初始化一个DWork向量x0。
```
函数DoPostPropSetup(block) %% Setup Dwork块。NumDworks = 1;block.Dwork(1)。Name = ' x0 ';block.Dwork(1)。维= 1; block.Dwork(1).DatatypeID = 0; block.Dwork(1).Complexity = 'Real'; block.Dwork(1).UsedAsDiscState = true;
```
如果你的s函数使用额外的DWork向量，在PostPropagationSetup方法，也一样(见在二级MATLAB s函数中使用DWork向量)。
中的离散态和连续态或其他DWork向量的值初始化InitializeConditions或开始回调方法。使用开始回调方法，用于在模拟开始时初始化一次的值。使用InitializeConditions方法，用于在包含s函数的已启用子系统被重新启用时需要重新初始化的值。
对于本例，使用InitializeConditions方法将离散状态的初始条件设置为s函数的对话参数的值。例如,InitializeConditions方法msfcn_unit_delay.m是:
```
function InitConditions(block) %%初始化Dwork block.Dwork(1)。Data = block.DialogPrm (1) . Data;
```
对于具有连续状态的s函数，使用ContStates运行时对象方法来初始化连续状态数据。例如:
```
block.ContStates.Data (1) = 1.0;
```
计算s函数的输出输出回调方法。对于本例，将输出设置为DWork向量中存储的离散状态的当前值。
的输出方法msfcn_unit_delay.m是:
```
函数输出(块)block.OutputPort(1)。Data = block.Dwork (1) . Data;
```
对于具有连续状态的s函数，计算状态导数衍生品回调方法。运行时对象将派生数据存储在衍生品财产。例如，下面这行设置第一状态导数等于第一个输入信号的值。
```
block.Derivatives.Data (1) = block.InputPort (1) . data;
```
这个例子没有使用连续状态，因此没有实现衍生品回调方法。
中的任何离散状态更新回调方法。对于本例，将离散状态的值设置为第一个输入信号的当前值。
的更新方法msfcn_unit_delay.m是:
```
函数更新(块)block.Dwork(1)。Data = block.InputPort (1) . Data;
```
执行任何清理，例如清除变量或内存，在终止方法。与C MEX s函数不同，Level-2的MATLAB s函数不需要有终止方法。

有关其他回调方法的信息，请参见Level-2 MATLAB S-Function回调方法。有关运行时对象属性的列表，请参阅参考页仿真软件。MSFcnRunTimeBlock和父类仿真软件。RunTimeBlock。

实例化一个二级MATLAB S-Function

要在模型中使用二级MATLAB s函数，请复制2级MATLAB函数Block进入模型。打开该块的块参数对话框，并输入实现s函数的MATLAB文件的名称功能名称字段。如果你的s函数使用任何额外的参数，在块参数对话框中以逗号分隔的列表形式输入参数值参数字段。

变大小信号的运算

以下是对二级MATLAB s函数模板的修改(msfuntmpl_basic.m)和其他操作，允许您使用可变大小的信号。

函数设置(block) %注册输出端口block. outputport(1)的属性。DimensionsMode =“变量”;块。RegBlockMethod (SetInputPortDimensionsMode, @SetInputDimsMode);function DoPostPropSetup(block) %注册依赖规则，根据%输入端口b和c块更新输出端口a的当前输出大小。AddOutputDimsDependencyRules(a， [b c]， @setOutputVarDims);%配置输出端口b与输入端口a块具有相同的尺寸。inputportsamedimsasoutputport (a,b);%配置DWork a，当输入大小发生变化时重置其大小。block.DWorkRequireResetForSignalSize(真正的);function SetInputDimsMode(block, port, dm) %设置尺寸模式block. inputport (port)。DimensionsMode = dm;block.OutputPort(港口)。DimensionsMode = dm;function setOutputVarDims(block, opIdx, inputIdx) %设置输出的当前(运行时)尺寸outDimsAfterReset = block. inputport (inputIdx(1)).CurrentDimensions; block.OutputPort(opIdx).CurrentDimensions = outDimsAfterReset;

从二级MATLAB s函数生成代码

为包含二级MATLAB s函数的模型生成代码需要您提供相应的目标语言编译器(TLC)文件。你不需要TLC文件来加速一个包含二级MATLAB s函数的模型。的仿真软件加速器™软件在解释模式下运行二级MATLAB s函数。然而，如果M-file s -函数在模型参考中，则M-file s -函数不能与加速模式一起工作。关于为MATLAB s函数编写TLC文件的更多信息，请参见内联S-Functions(仿真软件编码器)和内联MATLAB文件s函数(仿真软件编码器)。