S-Function Builder用法及使用实例
函数生成器对话框S-Function Builder Dialog Box
关于S-Function
S-Function Builder dialog box允许您指定要由S-Function Builder块构建的S-Function的属性。要显示对话框，双击S-Function Builder块图标或选择块，然后从模型编辑器的编辑菜单或块的上下文菜单中选择Open Block。
对话框包含一些控件，允许您输入S-Function构建器块所需的信息，以便根据您的规范构建S-Function。控件被分组到窗格中。有关窗格及其包含的控件的信息，请参阅以下部分。
请注意，以下部分使用术语
target S-function来指代由S-function Builder dialog box指定的S-function。
Parameters/Language/S-Function Name Pane参数/语言/ S函数名称窗格
此窗格显示目标S函数名称和参数，并包含以下控件。
S函数名称： 指定目标S函数的名称。
语言
指定S函数的目标语言。您可以选择在C / C ++中生成S函数，也可以继承模型设置。
S函数参数
该表显示目标S函数的参数。表的每一行对应一个参数，每一列显示该参数的属性，如下所示：
名称—参数的名称。在“参数”窗格中定义和修改此属性。
数据类型-列出参数的数据类型。在“参数”窗格中定义和修改此属性。
值—指定参数的值。在此字段中输入有效的
MATLAB®表达式。
建立/保存
使用此按钮可根据您在S-Function Builder中输入的信息生成C源代码和可执行MEX文件。如果按钮标记为Build，则S-Function Builder会生成源代码和可执行的MEX文件。如果按钮标记为“保存”，则仅生成C源代码。使用“构建信息”窗格上的“仅保存代码”复选框来切换此按钮的功能。
隐藏/显示S函数编辑选项卡
使用“参数/ S函数名称”窗格右下角的小按钮折叠和展开“ S函数构建器”对话框的底部。
Port/Parameter Pane 端口/参数窗格
左侧的“端口/参数”窗格显示对话框为目标S函数指定的端口和参数。
该窗格包含一个树控件，其顶部节点分别对应于目标S函数输入端口，输出端口和参数。展开“输入端口”，“输出端口”或“参数”节点，分别显示为目标S函数指定的输入端口，输出端口或参数。选择任何端口或参数节点都会在相应的端口或参数指定窗格上选择相应的条目。
初始化窗格
通过“初始化”窗格，您可以指定S函数的基本功能，例如其输入和输出端口的宽度及其采样时间。
S-Function Builder使用在此窗格上输入的信息来生成mdlInitializeSizes回调方法。 Simulink®引擎在仿真的模型初始化阶段调用此方法，以获得有关S函数的基本信息。 （有关模型初始化阶段的更多信息，请参见Simulink Engine与CS函数的交互。）
初始化窗格包含以下字段。
离散状态数
S函数中离散状态的数量。
**离散状态IC
**S函数中离散状态的（IC ：Initial conditions）初始条件。您可以将值输入为以逗号分隔的列表或向量（例如[0 1 2]）。初始条件的数量必须等于离散状态的数量。
连续状态数
S函数中连续状态的数量。
连续状态IC
S函数中连续状态的初始条件。您可以将值输入为以逗号分隔的列表或向量（例如[0 1 2]）。初始条件的数量必须等于连续状态的数量。
采样模式
S函数的采样模式。采样模式确定S函数更新其输出的时间间隔。您可以选择以下选项之一：
继承 S函数从连接到其输入端口的块继承其采样时间。
连续 该块在每个仿真步骤更新其输出。
离散 S函数以S函数构建器对话框的采样时间值字段中指定的速率更新其输出。
采样时间值
标量值，指示S函数输出更新之间的间隔。仅当选择“离散”作为“采样”模式时，才启用此字段。
注意
S-Function Builder当前不支持多块采样时间或非零偏移时间。
PWorks数量
S函数使用的数据指针的数量。 PWorks指向块整个生命周期中的内存。例如，您可以在**“开始”**处声明并初始化指向文件或内存的指针，并在“**输出”，“更新”和“派生”窗格中访问它，然后在“终止”**窗格中将其取消分配。在这些窗格中编写的代码由mdlStart，mdlOutputs，mdlUpdate，mdlDerivatives和mdlTerminate调用。请参见示例。
注意
使用PWorks会影响SimState的合规性。如果声明PWorks，则不允许使用SimState保存和还原。否则，将使用默认的SimState合规性设置USE_DEFAULT_SIM_STATE。
Data Properties Pane 数据属性窗格
“数据属性”窗格允许您将端口和参数添加到S函数。窗格左侧的按钮列允许您添加，删除或重新排序端口或参数。
要添加端口或参数，请单击
add按钮。要删除当前选定的端口或参数，请单击“删除”按钮。
要将当前选定的端口或参数向上移动到相应的
S-Function端口或参数列表中的一个位置，请单击up按钮。要将当前选定的端口或参数在相应的
S-function端口或参数列表中向下移动一个位置，请单击向下按钮。
Array layout 阵列布局
C / C ++代码的数组布局。您可以选择表中列出的选项之一。
| Option | Array Layout of C/C++ Function | Action |
|---|---|---|
Column-major |
Column-major | S-Function Builder块在mdlInitializeSizes中添加了SimStruct函数ssSetArrayLayoutForCodeGen，以将S函数标记为用于生成列的主要代码。 |
Row-major |
Row-major | S函数构建器块在mdlInitializeSizes中添加SimStruct函数ssSetArrayLayoutForCodeGen，以将S函数标记为行主要代码生成。在仿真过程中，如果您的C / C ++代码涉及矩阵或多维输入，输出或参数，则将转置添加到以下S函数回调方法中：mdlOutputs mdlUpdate mdlDerivatives在Accelerator和Rapid Accelerator模式下运行仿真时，Simulink还将应用上述转置。使用TLC不能内联S函数。而是直接编译带有转置的MEX S函数。 |
Any |
C/C++ function is not affected by array layout | S-Function Builder块在mdlInitializeSizes中添加了SimStruct函数ssSetArrayLayoutForCodeGen，以将S-函数标记为接受行主代码和列主代码生成。 |
此窗格还包含选项卡式窗格，可让您指定创建的端口和参数的属性。看到：
输入端口窗格
输出端口窗格
参数窗格
数据类型属性窗格
Input Ports Pane 输入端口窗格
输入端口窗格使您可以检查和修改S功能输入端口的属性。该窗格包含一个可编辑表，该表按端口在S-Function Builder块上出现的顺序列出了输入端口的属性。该表的每一行都对应一个端口。该行中的每个条目都显示端口的属性，如下所示。
端口名称
端口名称。编辑此字段以更改端口名称。
外型尺寸
列出端口接受的输入信号的维数。要显示支持的尺寸列表，请单击相邻的按钮。要更改端口尺寸，请从列表中选择一个新值。指定1-D以动态调整信号大小，而不管信号的实际尺寸如何。
行
指定输入信号的第一（或唯一）维度的大小。指定-1以动态调整信号大小。
列
指定输入信号的第二维尺寸（仅当输入端口接受二维信号时）。
注意
对于具有二维的输入信号，如果行尺寸是动态调整大小，则列维也必须动态调整大小或设置为1。如果将列维设置为其他值，则将编译S函数，但是任何包含由于尺寸规格无效，此S功能将无法运行。
复杂度
指定输入端口接受实数还是复数值信号。
总线
如果S-Function Builder块的输入信号是总线，则使用“总线”列中的下拉菜单选择“打开”。
总线名称
如果输入信号是总线，则构建S函数的第2步会自动指示您创建总线对象。在“总线名称”列中提供的字段中，输入在创建入口总线对象时定义的总线名称。
Output Ports Pane 输出端口窗格
通过“输出端口”窗格，您可以检查和修改S功能输出端口的属性。该窗格由一个表组成，该表按端口在S功能块上出现的顺序列出了输出端口的属性。该表的每一行都对应一个端口。该行中的每个条目都显示端口的属性，如下所示。
端口名称
端口名称。编辑此字段以更改端口名称。
外型尺寸
列出端口输出的信号的维数。要显示支持的尺寸列表，请单击相邻的按钮。要更改端口尺寸，请从列表中选择一个新值。指定1-D以动态调整信号大小，而不管信号的实际尺寸如何。
行
指定输出信号的第一（或唯一）维度的大小。指定-1以动态调整信号大小。
列
指定输出信号的二维尺寸（仅当端口输出二维信号时）。
注意
对于具有二维的输出信号，如果其中一个维是动态调整大小，则另一个维也必须动态调整大小或设置为1。如果将第二维设置为其他某个值，则将编译S函数，但是任何包含由于尺寸规格无效，此S功能将无法运行。在某些情况下，确定动态大小的输出端口尺寸的计算可能不足，并且二维输出信号的两个尺寸可能都需要进行硬编码。
复杂度
指定端口输出实信号还是复值信号。
总线
如果到S-Function Builder模块的输出信号是总线，则使用“总线”列中的下拉菜单选择“打开”。
总线名称
Build S-Functions的步骤2自动指示您创建总线对象。在“总线名称”列中提供的字段中，输入在创建输出总线对象时定义的名称。
Parameters Pane 参数窗格
通过“参数”窗格，您可以检查和修改S功能参数的属性。该窗格由一个表格组成，该表格列出了S功能参数的属性。表的每一行都对应一个参数。参数出现的顺序与用户必须在S功能参数字段中指定它们的顺序相对应。该行中的每个条目都显示参数的属性，如下所示。
参数名称
参数名称。编辑此字段以更改名称。
数据类型
列出参数的数据类型。单击相邻按钮以显示支持的数据类型的列表。要更改参数数据类型，请从列表中选择一种新类型。
复杂度
指定参数是实数值还是复数值。
Data Type Attributes Pane 数据类型属性窗格
该窗格允许您指定目标S函数的输入和输出端口的数据类型属性。该窗格包含一个表，该表列出了每个S函数端口的数据类型属性。您只能编辑表中的某些字段。其他字段显示为灰色。每行对应于目标S功能的端口。每列指定相应端口的属性。
端口
端口名称。该字段显示在“输入端口”和“输出端口”窗格中输入的名称。您无法编辑此字段。
数据类型
端口的数据类型。单击相邻按钮以显示支持的数据类型的列表。要更改数据类型，请从列表中选择其他数据类型。
仅在“数据类型”字段指定定点数据类型时，才启用此窗格上的其余字段。有关更多信息，请参见指定定点数据类型。
Libraries Pane 库窗格 “库”窗格允许您指定在S-Function Builder对话框的其他窗格中输入的自定义代码引用的外部代码文件的位置。它包括以下字段。
库/对象/源文件
在S-Function Builder对话框的其他位置输入的自定义代码引用的外部库，目标代码和源文件。在单独的行上列出每个文件。如果文件位于当前文件夹中，则只需指定文件名。如果文件位于另一个文件夹中，则必须指定文件的完整路径。
或者，您也可以使用此字段指定库，目标文件，头文件和源文件的搜索路径。为此，请分别输入标签LIB_PATH，INC_PATH或SRC_PATH，然后输入路径名。您可以根据需要输入任意数量的此类条目，但每个条目必须位于单独的行上。
例如，考虑一个驻留在d：\ matlab6p5\ work并需要链接以下文件的S-Function Builder项目：
c：\ customfolder \ customfunctions.lib
d：\ matlab7 \ customobjs \ userfunctions.obj
d：\ externalsource \ freesource.c
下列条目使S-Function Builder可以找到这些文件：
SRC_PATH d:\externalsource
LIB_PATH $MATLABROOT\customobjs
LIB_PATH c:\customfolder
customfunctions.lib
userfunctions.obj
freesource.c
如本示例所示，您可以使用LIB_PATH来指定对象和库文件路径。您可以在LIB_PATH声明中包含库名，但是必须将目标文件名放在单独的行上。标签 $MATLABROOT表示相对于MATLAB安装的路径。您可以在单独的行中包含多个LIB_PATH条目。按照指定的顺序搜索路径。
您还可以在此字段中输入预处理器（-D）指令，例如，
-DDEBUG
每个指令必须位于单独的行上。
注意
即使路径名中包含空格，也不要在库路径两边加上引号。如果添加引号，则编译器将找不到该库。
Includes
头文件，其中包含在S-Function Builder对话框的其他位置输入的自定义代码引用的函数，变量和宏的声明。在单独的行上将每个文件指定为#include语句。使用方括号括起标准C标头文件的名称（例如，#include ）。使用引号将自定义头文件的名称括起来（例如，＃include“ myutils.h”）。如果您的S函数使用不在当前文件夹中的自定义包含文件，则必须使用“库/对象/源文件”字段中的INC_PATH标记将S函数构建器的包含路径设置为包含包含文件的目录文件（请参阅库/对象/源文件）。
外部函数声明
未在“包括”字段中列出的头文件中声明的外部函数的声明。将每个声明放在单独的行上。 S-Function构建器在其生成的S-Function源文件中包含指定的声明。这允许计算S-function状态或输出的S-function代码调用外部函数。
Start Pane 启动窗格
在模拟开始时，使用“开始”窗格编写代码以分配内存。 Pworks引用了分配的内容，以在整个S功能中使用。
Outputs Pane 输出窗格
使用“输出”窗格输入在每个模拟时间步长计算S函数输出的代码。此窗格包含以下字段。
代码说明
mdlOutputs函数的代码，该函数在每个时间步长（或采样时间点，在离散S函数的情况下为采样时间）计算S函数的输出。生成S函数的源代码时，S函数构建器会将代码插入此字段的表单包装函数中
void sfun_Outputs_wrapper(const real_T *u,
real_T *y,
const real_T *xD, /* optional */
const real_T *xC, /* optional */
const real_T *param0, /* optional */
int_T p_width0 /* optional */
real_T *param1 /* optional */
int_t p_width1 /* optional */
int_T y_width, /* optional */
int_T u_width) /* optional */
{
/* Your code inserted here */
}
其中sfun是S函数的名称。 S函数创建器在为您的S函数生成的mdlOutputs回调方法中插入对此包装函数的调用。 Simulink引擎在每个模拟时间步长（如果是离散S函数，则为采样时间步长）调用mdlOutputs方法，以计算S函数输出。 mdlOutputs方法又调用包含输出代码的包装器函数。然后，您的输出代码实际计算并返回S函数输出。
mdlOutputs方法将以下一些或所有以下参数传递给输出包装函数。
| Argument | Description |
|---|---|
u0, u1, ... uN |
指向包含S函数输入的数组的指针，其中N是在“数据属性”窗格上的“输入端口”窗格上指定的输入端口数。在输出包装器函数中出现的参数名称与在“输入端口”窗格中找到的名称相同。每个阵列的宽度与在“输入端口”窗格上为每个输入指定的输入宽度相同。如果将-1指定为输入宽度，则数组的宽度由包装函数的u_width参数指定（请参见下文）。 |
y0, y1, ... yN |
指向包含S函数输出的数组的指针，其中N是在“数据属性”窗格上的“输出端口”窗格上指定的输出端口数。在输出包装函数中出现的参数名称与在“输出端口”窗格中找到的名称相同。每个阵列的宽度与在“输出端口”窗格上为每个输出指定的输出宽度相同。如果您指定-1作为输出宽度，则数组的宽度由包装函数的y_width参数指定（请参见下文）。使用此数组可以将代码计算的输出传递回Simulink引擎 |
xD |
指向包含S函数离散状态的数组的指针。仅当您在“初始化”窗格中指定了离散状态时，此参数才会出现。在第一个模拟时间步骤中，离散状态具有您在“初始化”窗格上指定的初始值。在随后的采样时间步骤中，从S函数在前一个时间步骤中计算出的值获得状态（有关更多信息，请参见离散更新窗格）。 |
xC |
指向包含S函数连续状态的数组的指针。仅当您在“初始化”窗格上指定了连续状态时，才会出现此参数。在第一个模拟时间步骤中，连续状态具有您在“初始化”窗格上指定的初始值。在随后的时间步长中，通过对前一时间步长的状态导数进行数值积分来获得状态（有关更多信息，请参见“连续导数窗格”）。 |
param0, p_width0, param1, p_width1, … paramN, p_widthN |
param0，param1，... paramN是指向包含S函数参数的数组的指针，其中N是在“数据属性”上的“参数”窗格上指定的参数数窗格。 p_width0，p_width1，... p_widthN是参数数组的宽度。如果参数是矩阵，则宽度等于数组尺寸的乘积。例如，3 x 2矩阵参数的宽度为6。只有在“数据属性”窗格上指定参数时，这些参数才会出现。 |
y_width |
包含S函数输出的数组的宽度。仅当您指定-1作为S函数输出的宽度时，此参数才会出现在生成的代码中。如果输出是矩阵，则y_width是该尺寸的乘积 |
u_width |
包含s函数输入的数组的宽度。只有在指定-1作为S-function输入的宽度时，这个参数才会出现在生成的代码中。如果输入是一个矩阵，那么u的宽度就是矩阵的维数的乘积。 |
这些参数允许您根据块的输入以及块的状态和参数来计算块的输出。您在此字段中输入的代码可以调用在头文件中声明的外部函数或“库”窗格上的外部声明。这使您可以使用现有代码来计算S函数的输出。
输出函数中需要输入
如果使用S函数输入的当前值来计算其输出，则选中此复选框。 Simulink引擎使用此信息来检测通过直接或间接将S函数输出连接到S函数输入而创建的代数循环。
Continuous Derivatives Pane 连续导数窗格
如果S函数具有连续状态，请使用“连续导数”窗格输入计算状态导数所需的代码。在此窗格的“代码描述”字段中，输入mdlDerivatives函数的代码以计算连续状态的导数。生成代码时，S-Function Builder会在此窗格中获取代码，并将其插入以下形式的包装函数中：
void sfun_Derivatives_wrapper(const real_T *u,
const real_T *y,
real_T *dx,
real_T *xC,
const real_T *param0, /* optional */
int_T p_width0, /* optional */
real_T *param1,/* optional */
int_T p_width1, /* optional */
int_T y_width, /* optional */
int_T u_width) /* optional */
{
/* Your code inserted here. */
}
其中sfun是S函数的名称。 S函数创建器在为S函数生成的mdlDerivatives回调方法中插入对此包装函数的调用。 Simulink引擎在每个时间步长的末尾调用mdlDerivatives方法，以获取连续状态的导数（请参见Simulink Engine与CS函数的交互）。 Simulink求解器通过数值方式对导数进行积分，以确定下一个时间步的连续状态。在下一个时间步，引擎会将更新后的状态传递回mdlOutputs方法（请参见输出窗格）。
为S函数生成的mdlDerivatives回调方法将以下参数传递给派生包装函数：
uydxxCparam0,p_width0,param1,p_width1, …paramN,p_widthNy_widthu_width
dx参数是一个数组的指针，该数组的宽度与在“初始化”窗格上指定的连续派生数相同。您的代码应使用此数组返回其计算的导数的值。有关其他参数的含义和用法，请参见输出窗格。这些参数允许您的代码根据S函数输入，输出以及（可选）参数来计算导数。您的代码可以调用在“库”窗格中声明的外部函数。
Discrete Update Pane 离散更新窗格
如果S函数具有离散状态，请使用“离散更新”窗格输入在当前时间步计算离散状态值的代码，该代码将在下一时间步计算。
在此窗格的“代码描述”字段中，为mdlUpdate函数输入代码以计算离散状态的值。生成代码时，S-Function Builder会在此窗格中获取代码，并将其插入到表单的包装函数中：
void sfun_Update_wrapper(const real_T *u,
const real_T *y,
real_T *xD,
const real_T *param0, /* optional */
int_T p_width0, /* optional */
real_T *param1,/* optional */
int_T p_width1, /* optional */
int_T y_width, /* optional */
int_T u_width) /* optional */
{
/* Your code inserted here. */
}
其中sfun是S函数的名称。 S函数创建器在为S函数生成的mdlUpdate回调方法中插入对此包装函数的调用。 Simulink引擎在每个时间步长的结尾处调用mdlUpdate方法，以在下一个时间步长获取离散状态的值（请参见Simulink Engine与CS功能的交互）。在下一个时间步，引擎会将更新后的状态传递回mdlOutputs方法（请参见输出窗格）。
为S函数生成的mdlUpdates回调方法将以下参数传递给update包装函数：
uyxDparam0,p_width0,param1,p_width1, …paramN,p_widthNy_widthu_width
有关这些参数的含义和用法，请参见输出窗格。您的代码应使用xD（离散状态）变量返回其计算的离散状态的值。这些参数允许您的代码将离散状态计算为S函数输入，输出以及（可选）参数的函数。您的代码可以调用在“库”窗格中声明的外部函数。
Terminate Pane 终止窗格
使用“终止”窗格来编写代码以释放在“开始”窗格中分配的内存。 PWorks引用的内存也可以在Terminate中看到，并应在此处取消分配。
Build Info Pane 构建信息窗格
使用“构建信息”窗格来指定用于构建S函数MEX文件的选项。此窗格包含以下字段。
编译诊断
在S-Function Builder生成C源文件和可执行文件时显示信息。
显示编译步骤
在“编译诊断”字段中记录每个构建步骤。
创建可调试的MEX文件
在生成的MEX文件中包括调试信息。
启用覆盖范围支持
使S功能与模型覆盖范围兼容。有关更多信息，请参见Simulink Coverage™文档中Simulink模型中自定义C / C ++代码的覆盖范围（Simulink Coverage）。
生成包装器TLC
选择此选项可让您生成TLC文件。如果要在Rapid Accelerator模式下运行模型或从模型生成Simulink Coder™代码，则需要生成TLC文件。同样，虽然加速器模式仿真不是必需的，但TLC文件将生成S函数的代码，从而使模型在加速器模式下运行得更快。
仅保存代码
不要从生成的源代码构建MEX文件。
启用对SimStruct的访问
使SimStruct（S）可被S-Function Builder生成的包装函数访问。这使您可以在输出，连续导数和离散更新窗格中将SimStruct宏和函数与代码一起使用。例如，启用此选项后，可以在计算S函数输出的代码中使用诸如ssGetT之类的宏：
double t = ssGetT(S);
if(t < 2 ) {
y0[0] = u0[0];
} else {
y0[0]= 0.0;
}
其他方法
单击此按钮可在S功能的TLC文件中包括其他TLC方法。选中要添加的方法，然后单击“关闭”按钮以将方法包括在TLC文件中。有关更多信息，请参见阻止目标文件方法（Simulink Coder）。
示例：对两输入/两输出的系统建模 Example: Modeling a Two-Input/Two-Output System
sfbuilder_example示例显示了如何使用S函数构建器对具有两个状态的两输入两输出离散状态空间系统进行建模。在该示例中，状态空间矩阵是S函数的参数，而S函数的输入和输出是向量。您可以在dsfunc.c中找到手动编写的S函数版本。
注意:
您需要在运行示例模型之前构建
S函数。要构建S函数，请双击模型中的S Function Builder块，然后在打开的S Function Builder对话框中单击Build。
初始化S函数设置
初始化窗格指定离散状态的数量及其初始条件，并设置S函数的采样时间。
本示例包含两个离散状态，每个状态都初始化为1，以及离散采样模式，采样时间为1。
初始化输入，输出和参数
“数据属性”窗格指定S函数输入和输出的尺寸，以及初始化状态空间矩阵。
“输入端口”窗格将一个S函数输入端口定义为具有两行的一维矢量。
类似地，“输出端口”窗格将一个S函数输出端口定义为具有两行的一维矢量。
“参数”窗格定义了四个参数，每个参数用于四个状态空间矩阵。
S函数构建器顶部的S函数参数窗格包含作为MATLAB表达式输入的状态空间矩阵的实际值。在此示例中，每个状态空间参数都是一个2乘2矩阵。或者，您可以将状态空间矩阵存储在MATLAB工作区的变量中，然后将变量名称输入每个参数的“Value”字段中。
定义输出方法
“输出”窗格根据输入和状态向量以及状态空间矩阵来计算S函数输出。在输出代码中，使用“数据属性-参数”窗格中定义的参数名称来引用S函数参数。请记住，S函数使用基于零的索引，从而使用标量索引对二维矩阵进行索引。例如，要访问S函数参数C中的元素C（2,1），请在S函数代码中使用C [1]。
由于此状态空间模型具有非零的D矩阵，因此“输出”窗格还选择了输出功能（direct feedthrough）选项中需要的输入。
定义离散更新方法
“离散更新”窗格更新离散状态。与输出代码一样，使用S函数参数名称并使用标量索引将其索引到二维矩阵中，请记住S函数使用从零开始的索引。例如，要访问S函数参数A中的元素A（2,1），请在S函数代码中使用A [1]。变量xD存储离散状态的最终值。
建立状态空间示例
单击S-Function Builder上的Build按钮以为此S-function创建可执行文件。现在，您可以运行模型并将输出与sfcndemo_dsfunc中包含的原始离散状态空间S函数进行比较。搭建模型以及运行结果：
相关链接
例子simulink
S-Function Builder Dialog Box官方文档