MATLAB Function

在 Simulink 模型中包含 MATLAB 代码

库:
Simulink / User-Defined Functions
HDL Coder / User-Defined Functions

描述

使用 MATLAB Function 模块可以编写用于 Simulink^® 模型的 MATLAB^® 函数。MATLAB 函数针对仿真执行，并生成以 Simulink Coder™ 为目标的代码。如果您刚开始使用 Simulink 和 MATLAB 产品，请参阅用 MATLAB Function 模块在 Simulink 中实现 MATLAB 函数了解概述信息。

双击 MATLAB Function 模块将打开 MATLAB Function 模块编辑器，您可以在其中编写 MATLAB 函数。用 MATLAB Function 模块在 Simulink 中实现 MATLAB 函数中讨论的示例模型 call_stats_block2 在 MATLAB Function 模块编辑器中使用以下函数：

function [mean,stdev] = stats(vals)

% Calculates a statistical mean and a standard
% deviation for the values in vals.

len = length(vals);
mean = avg(vals,len);
stdev = sqrt(sum(((vals-avg(vals,len)).^2))/len);
plot(vals,"-+");

function mean = avg(array,size)
mean = sum(array)/size;

该函数将函数声明语句中的输入和输出数据指定为参量和返回值。前面的示例函数的参量和返回值对应于以下 call_stats_block2 模型中的模块的输入和输出。

This shows connected signals between the blocks in the call_stats_block2 model discussed in .

您还可以使用模型资源管理器或符号窗格来定义变量、添加输入触发器以及创建函数调用输出。有关详细信息，请参阅Create and Define MATLAB Function Block Variables、Manage the Input Trigger of a MATLAB Function Block和Manage Function Call Outputs of a MATLAB Function Block。

MATLAB Function 模块基于分析来生成有效的可嵌入式代码，该分析可确定每个变量的大小、类和复/实性。该分析施加了以下限制：

首次对变量赋值时会定义其大小、类和复/实性。
请参阅为 C/C++ 代码生成定义变量的最佳做法。
在初始赋值后不能为变量属性重新赋值，但在代码中可以针对不同用途使用可变大小的数据或重复使用变量。
请参阅变量属性的重新赋值。

除了语言限制，MATLAB Function 模块还支持 MATLAB 中提供的函数子集。这些函数包括常见类别的函数，例如：

plus、minus 和 power 等算术运算符。有关详细信息，请参阅数组与矩阵运算。
size 和 length 等矩阵运算
lu、inv、svd 和 chol 等高级矩阵运算
sin、cos、sinh 和 cosh 等三角函数

有关详细信息，请参阅 C/C++ 代码生成支持的函数和对象。

注意

虽然此模块的代码会尝试生成与 MATLAB 完全相同的结果，但由于存在舍入误差，因此仍可能产生差异。这些数值差异最初可能是几个 eps，在重复运算之后可能会放大。建议您不要依赖 nan 的行为。对于相同的计算，不同的 C 编译器可能产生不同的结果。

注意

新的 MATLAB Function 模块不包括 %#codegen 指令，但在检查错误时就如果包含该指令一样。将 %#codegen 指令添加到 MATLAB Function 模块不会影响错误检查。有关详细信息，请参阅编译指令 %#codegen。

为支持数据可视化，MATLAB Function 模块仅支持调用 MATLAB 函数进行仿真。请参阅使用 MATLAB 引擎在 MATLAB Function 模块中执行函数调用了解该功能的一些限制，以及该功能如何与此模块的代码分析集成在一起。如果这些函数调用不直接影响任何 Simulink 输入或输出，则这些调用不会出现在 Simulink Coder 生成的代码中。

在 MATLAB Function 模块中，还可以调用在 Simulink Function 模块中定义的函数。如果在图表的“属性”对话框中选中导出图级别函数(全局) 和允许 Simulink 调用导出的函数，则可以调用 Stateflow^® 函数。

在符号窗格中，您可以将模块输入声明为 Simulink 参数，而不是端口。MATLAB Function 模块还支持继承输入、输出和参数的类型及大小。您也可以显式指定这些属性。有关在 MATLAB Function 模块中使用的变量的描述，请参阅定义和修改变量数据类型、指定 MATLAB Function 模块变量的大小和配置 MATLAB Function 模块参数变量。

MATLAB Function 模块中不允许递归调用。

默认情况下，MATLAB Function 模块已启用直接馈通。要禁用它，请清除允许直接馈通属性。非直接馈通语义确保输出仅依赖于当前状态。使用非直接馈通使您能够在反馈环中使用 MATLAB Function 模块并防止代数环。有关详细信息，请参阅 Use Nondirect Feedthrough in a MATLAB Function Block。

示例

全部展开

将输入信号乘以二

将 MATLAB Function 添加到您的模型中以修改输入信号。

在仿真选项卡中，点击库浏览器。选择 Simulink > 用户定义的函数。将 MATLAB Function 模块拖到 Simulink 画布上。
双击模块以打开 MATLAB Function 模块编辑器。用以下代码替换函数体代码：
```
y = 2*u;
```
通过点击“向上到父级”按钮返回到模型。添加 Sine Wave 模块作为输入信号，并添加 Scope 模块来采集 MATLAB Function 模块的输入和输出。
运行仿真并打开 Scope 模块以查看代码的效果。

扩展示例

使用包含 MATLAB Function 模块的封装库子系统运行仿真并生成代码

使用带有库中自定义 MATLAB Function 模块的模型运行仿真并生成代码。

打开模型

Call MATLAB Function Files in MATLAB Function Blocks

Use MATLAB Function blocks to call and execute code written in MATLAB function files.

打开模型

使用 MATLAB Function 模块的雷达跟踪

此示例说明如何使用 MATLAB Function 模块创建一个卡尔曼滤波器来估计飞机的位置。在估计位置后，模型调用外部 MATLAB® 函数来绘制跟踪数据。

打开模型

Spiral Galaxy Formation Simulation Using MATLAB Function Blocks

Use MATLAB Function blocks to simulate and plot galaxy interactions.

打开模型

端口

输入

全部展开

u — 输入端口
标量 | 向量 | 矩阵

输入端口，指定为标量、向量或矩阵。您创建的每个输入变量都有一个对应的输入端口。

MATLAB 支持但 Simulink 不支持的数据类型可能无法在 Simulink 模型和 MATLAB Function 模块内的函数之间传递。这些类型可在 MATLAB Function 模块内使用。

有关此模块的定点支持的详细信息，请参阅Fixed-Point Data Types with MATLAB Function Block (Fixed-Point Designer)和Data Type Override with MATLAB Function Block (Fixed-Point Designer)。

依存关系

要创建输入端口，请打开模块并在符号窗格中创建输入变量。请参阅Create and Define MATLAB Function Block Variables。

输出

全部展开

y — 输出端口
标量 | 向量 | 矩阵

输出端口，指定为标量、向量或矩阵。您创建的每个输出变量都有一个对应的输出端口。

依存关系

要创建输出端口，请打开模块并在符号窗格中创建输出变量。请参阅Create and Define MATLAB Function Block Variables。

参数

全部展开

常设

显示端口标签 — 端口标签的显示选项
FromPortIcon (默认) | 无 | FromPortBlockName | SignalName

选择如何在 MATLAB Function 模块图标上显示端口标签。

无 - 不显示端口标签。
FromPortIcon - 显示输入和输出变量的名称。
FromPortBlockName - 显示输入和输出变量的名称。
SignalName - 如果连接到端口的信号已命名，则显示信号名称。否则，显示变量的名称。

编程用法

要以编程方式设置模块参数值，请使用 set_param 函数。

要以编程方式获取模块参数值，请使用 get_param 函数。

参数:	`ShowPortLabels`
值:	`"FromPortIcon"` (默认) \| `"none"` \| `"FromPortBlockName"` \| `"SignalName"`

读取/写入权限 — 模块内容的访问级别
ReadWrite (默认) | ReadOnly | NoReadOrWrite

控制用户对 MATLAB Function 模块内容的访问。

ReadWrite - 允许打开和修改 MATLAB Function 模块内容。
ReadOnly - 允许打开 MATLAB Function 模块。
NoReadOrWrite - 禁止打开或修改 MATLAB Function 模块。

注意

如果您尝试查看其读取/写入权限参数设置为 NoReadOrWrite 的 MATLAB Function 模块的内容，该模块不会响应。例如，当您双击 MATLAB Function 模块时，Simulink 不会打开模块，也不会显示消息。

编程用法

要以编程方式设置模块参数值，请使用 set_param 函数。

要以编程方式获取模块参数值，请使用 get_param 函数。

参数:	`Permissions`
值:	`"ReadWrite"` (默认) \| `"ReadOnly"` \| `"NoReadOrWrite"`

尽量减少出现代数环 — 消除人为代数环的选项
off (默认) | on

模块是否尝试消除包含该模块的人为代数环。

off - 不尝试消除任何包含此模块的人为代数环。
on - 尝试消除任何包含此模块的人为代数环。

编程用法

要以编程方式设置模块参数值，请使用 set_param 函数。

要以编程方式获取模块参数值，请使用 get_param 函数。

参数:	`MinAlgLoopOccurrences`
值:	`"off"` (默认) \| `"on"`

采样时间(-1 表示继承) — 指定时间间隔
`-1` (默认) | `[Ts 0]`

指定此模块中的变量必须以相同的速率运行，还是能以不同的速率运行。

如果 MATLAB Function 模块中的变量能以不同速率运行，请将采样时间指定为继承 (-1)。
如果变量必须以相同的速率运行，请指定与此速率对应的采样时间 Ts。

编程用法

要以编程方式设置模块参数值，请使用 set_param 函数。

要以编程方式获取模块参数值，请使用 get_param 函数。

参数:	`SystemSampleTime`
值:	`"-1"` (默认) \| `"[Ts 0]"`
数据类型:	`char` \| `string`

代码生成

函数打包 — 选择代码格式
自动 (默认) | 内联 | 不可重用函数 | 可重用函数

选择模块生成的代码格式。

自动 — Simulink Coder 将基于模型中存在的 MATLAB Function 模块的类型和实例数为您的系统选择最佳格式。
内联 - Simulink Coder 无条件地内嵌 MATLAB Function 模块。
不可重用函数 - Simulink Coder 在单独的文件中显式生成单独的函数。具有此设置的 MATLAB Function 模块生成的函数可能具有取决于函数接口参数设置的参量。您可以分别使用函数名称和 文件名（无扩展名） 参数来命名生成的函数和文件。这些函数不可重入。
Reusable function — Simulink Coder 可以生成带参量的函数，当模型中包含模块的多个 MATLAB Function 实例时，将允许重用 MATLAB Function 模块的代码。
此选项生成具有参量的函数，该函数允许在模型引用层次结构的生成代码中重用 MATLAB Function 模块代码，该层次结构包括跨引用模型的 MATLAB Function 模块的多个实例。在这种情况下，MATLAB Function 模块必须在库中。

提示

当您要将一个 MATLAB Function 模块的多个实例表示为一个可重用函数时，您可以将每个实例指定为自动或可重用函数。使用其中一个，因为使用两个将生成两个可重用函数，每个指定一个函数。仅当可以重用时，这些选项的结果才会有区别。选择自动则不允许控制 MATLAB Function 模块代码的函数或文件名。
可重用函数和自动选项都会确定是否存在 MATLAB Function 模块的多个实例，以及是否可以重用代码。当无法重用代码时，这些选项的行为会有所不同。
- 自动生成内联代码，或者在禁止内联的情况下为每个子系统 MATLAB Function 模块实例生成一个单独的函数。
- 可重用函数为每个子系统 MATLAB Function 模块实例生成一个单独的参量函数。
如果您在生成的代码处于源代码管理状态下时选择了可重用函数，请将文件名选项设置为使用子系统名称、使用函数名称或用户指定。否则，点您修改模型时，代码文件的名称就会改变，从而无法对文件进行源代码管理。

依存关系

此参数需要 Simulink Coder。
将此参数设置为不可重用函数或可重用函数将启用下列参数：
- 函数名称选项
- 文件名选项
- 用于初始化/终止函数的内存段（需要 Embedded Coder^® 和基于 ERT 的系统目标文件）
- 用于执行函数的内存段（需要 Embedded Coder 和基于 ERT 的系统目标文件）

编程用法

要以编程方式设置模块参数值，请使用 set_param 函数。

要以编程方式获取模块参数值，请使用 get_param 函数。

参数:	`RTWSystemCode`
值:	`"Auto"` (默认) \| `"Inline"` \| `"Nonreusable function"` \| `"Reusable function"`

模块特性

数据类型	`Boolean^a` \| `bus^a` \| `double^a` \| `enumerated^a` \| `fixed point^a` \| `half^a` \| `integer^a` \| `single^a` \| `string^a`
直接馈通	`是^a`
多维信号	`是^a`
可变大小信号	`是^a`
过零检测	`否`
^a 实际支持的数据类型或功能取决于模块实施。

扩展功能

C/C++ 代码生成
使用 Simulink® Coder™ 生成 C 代码和 C++ 代码。

实际数据类型或功能支持取决于模块实现。

HDL 代码生成
使用 HDL Coder™ 为 FPGA 和 ASIC 设计生成 VHDL、Verilog 和 SystemVerilog 代码。

HDL Coder™ 提供影响 HDL 实现和综合逻辑的额外配置选项。实际数据类型或功能支持取决于模块实现。有关使用 MATLAB Function 模块的最佳做法，请参阅：

HDL 架构

MATLAB 函数（默认值）

这是具有定点数据类型的 MATLAB Function 模块的默认架构。当您使用此架构时，您可以对 MATLAB Function 模块周围的模块使用速度和面积优化。MATLAB Function 模块中的代码不会优化。

MATLAB Datapath

这是具有浮点数据类型的 MATLAB Function 模块的默认架构。当您使用此架构时，代码生成器将 MATLAB Function 模块视为常规的 Subsystem 模块。通过为定点类型启用此架构，您可以对 MATLAB Function 模块内的模块以及与 MATLAB Function 模块一起工作的其他 Simulink 模块使用速度和面积优化。

通过此功能，您可以为 MATLAB Function 模块指定要为 Subsystem 模块指定的其他属性，例如 ClockRatePipelining 和 FlattenHierarchy。

HDL 模块属性

AdaptivePipelining	基于综合工具、目标频率和乘法器字长的自动流水线插入。默认值为 inherit。要指定此属性，请将架构设置为 `MATLAB Datapath`。另请参阅AdaptivePipelining (HDL Coder)。
BalanceDelays	检测沿一条路径引入的新延迟，并在其他路径上插入匹配的延迟。默认值为 inherit。要指定此属性，请将架构设置为 `MATLAB Datapath`。另请参阅BalanceDelays (HDL Coder)。
ClockRatePipelining	以较快的时钟频率而不是较慢的数据速率插入流水线寄存器。默认值为 inherit。要指定此属性，请将架构设置为 `MATLAB Datapath`。另请参阅ClockRatePipelining (HDL Coder)。
ConstMultiplierOptimization	正则有符号数 (CSD) 或因子化 CSD 优化。默认值为无。另请参阅ConstMultiplierOptimization (HDL Coder)。
ConstrainedOutputPipeline	通过移动设计中现有延迟的方式来放置在输出端的寄存器的数量。分布式流水线不会重新分发这些寄存器。默认值为 `0`。有关详细信息，请参阅ConstrainedOutputPipeline (HDL Coder)。
DistributedPipelining	流水线寄存器分配或寄存器重定时。默认值为 inherit。另请参阅DistributedPipelining (HDL Coder)。
DSPStyle	乘法器映射的综合属性。默认值为无。要指定此属性，请将架构设置为 `MATLAB Datapath`。另请参阅DSPStyle (HDL Coder)。
FlattenHierarchy	从生成的 HDL 代码中删除 MATLAB Function 模块层次结构。默认值为 inherit。要指定此属性，请将架构设置为 `MATLAB Datapath`。另请参阅FlattenHierarchy (HDL Coder)。
InputPipeline	要在生成的代码中插入的输入流水线阶段数。分布式流水线和受限输出流水线可以移动这些寄存器。默认值为 `0`。有关详细信息，请参阅InputPipeline (HDL Coder)。
InstantiateFunctions	为每个函数生成 VHDL^® `entity` 或 Verilog^® `module`。默认值为 off。另请参阅InstantiateFunctions (HDL Coder)。
LoopOptimization	展开、流化或不优化循环。默认值为无。如果您将架构设置为 `MATLAB Datapath`，您只能展开循环。如果您要在 `MATLAB Datapath` 架构中使用循环流，可以通过指定 StreamingFactor 来使用流式优化。另请参阅LoopOptimization (HDL Coder)。
MapPersistentVarsToRAM	将持久数组映射到 RAM。默认值为 off。另请参阅MapPersistentVarsToRAM (HDL Coder)。
OutputPipeline	要在生成的代码中插入的输出流水线阶段数。分布式流水线和受限输出流水线可以移动这些寄存器。默认值为 `0`。有关详细信息，请参阅OutputPipeline (HDL Coder)。
ResetType	隐藏重置逻辑生成。默认值为默认，它生成重置逻辑。另请参阅ResetType (HDL Coder)。
SharingFactor	要映射到单个共享资源的功能等效的资源的数量。默认值为 0。另请参阅Resource Sharing (HDL Coder)。
StreamingFactor	并行数据路径或向量的数量，这些路径或向量通过时间多路复用的方式变换为串行标量数据路径。默认值为 0，表示实现完全并行的数据路径。要指定此属性，请将架构设置为 `MATLAB Datapath`。另请参阅Streaming (HDL Coder)。
VariablesToPipeline	警告不推荐使用 `VariablesToPipeline`。请改用 `coder.hdl.pipeline` (HDL Coder)。在一个或多个指定变量的输出端插入流水线寄存器。将变量列表指定为字符向量，变量之间用空格分隔。要指定此属性，请将架构设置为 `MATLAB Function`。

数据类型支持

对于 MATLAB Function 模块中的以下函数，HDL 代码生成支持半精度数据类型：

`all`	`and, &`	`any`	`cast`	`conj`	`ctranspose`
`end`	`=`	`eq`	`==`	`ge, >=`	`gt, >`
`half`	`inf`	`int8`	`int16`	`int32`	`int64`
`isa`	`iscolumn`	`isempty`	`isequal`	`isfinite`	`isfloat`
`isinf`	`isinteger`	`islogical`	`isnan`	`isnumeric`	`isreal`
`isrow`	`isscalar`	`isvector`	`le, <=`	`length`	`logical`
`lt, <`	`max`	`min`	`minus, -`	`NaN`	`ndims`
`ne, ~=`	`not`	`numel`	`or, \|`	`plus, +`	`prod`
`reshape`	`single`	`size`	`sqrt`	`sum`	`times, .*`
`transpose`	`uint8`	`uint16`	`uint32`	`uint64`	`uminus`
`uplus`	`vertconcat`	-	-	-	-

复数数据支持

此模块支持复信号的代码生成。

另请参阅Complex Data Type Support (HDL Coder)。

可调参数支持

HDL Coder 支持以下数据类型的可调和不可调参数：

标量
向量
复数
结构体
枚举

有关详细信息，请参阅Generate DUT Ports for Tunable Parameters (HDL Coder)和Design Guidelines for the MATLAB Function Block (HDL Coder)。

生成具有代数环的模块的 HDL 代码

要为包含 Matlab Function 模块的模型生成 HDL 代码，请执行以下操作：

在“配置参数”对话框中，点击诊断，并将代数环参数设置为无或警告。
打开 Matlab Function 模块的模块封装，并选择视为原子单元和尽量减少出现代数环参数。

限制

如果模块包含 System object™，则模块输入不能包含非离散（常量或 Inf）采样时间。
HDL Coder 不支持包含与函数的输入和输出相同的变量的 MATLAB Function。例如，不支持使用此 MATLAB 代码。
```
function y = myFun(y)
%#codegen

y = 3 * y;
```
模块仅在本机浮点模式下支持浮点数据类型。

有关基于 MATLAB Function 模块的 HDL 代码生成支持的 MATLAB 语言子集，请参阅 Supported MATLAB Data Types, Operators, and Control Flow Statements (HDL Coder)。

PLC 代码生成
使用 Simulink® PLC Coder™ 生成结构化文本代码。

PLC 模块属性

UseExternalDefinition

在生成的代码中取消模块定义。默认值为 Off。另请参阅 UseExternalDefinition (Simulink PLC Coder)。

定点转换
使用 Fixed-Point Designer™ 设计和仿真定点系统。

实际数据类型或功能支持取决于模块实现。

版本历史记录

在 R2011a 中推出

全部展开

R2021a: 报告 MATLAB Function 模块在快速加速模式下的运行时错误

通过将启用内存完整性检查配置参数设置为始终打开，报告在快速加速模式下进行仿真时 MATLAB Function 模块的运行时错误。

R2020a: 对 MATLAB Function 模块的 64 位整数类型支持

MATLAB Function 模块现在支持 64 位整数数据。该模块将 int64 和 uint64 数据类型实现为定点数，字长为 64 位，小数长度为 0。

MATLAB Function

描述

示例

将输入信号乘以二

扩展示例

使用包含 MATLAB Function 模块的封装库子系统运行仿真并生成代码

Call MATLAB Function Files in MATLAB Function Blocks

使用 MATLAB Function 模块的雷达跟踪

Spiral Galaxy Formation Simulation Using MATLAB Function Blocks

端口

输入

u — 输入端口 标量 | 向量 | 矩阵

依存关系

输出

y — 输出端口 标量 | 向量 | 矩阵

依存关系

参数

常设

显示端口标签 — 端口标签的显示选项 FromPortIcon (默认) | 无 | FromPortBlockName | SignalName

编程用法

读取/写入权限 — 模块内容的访问级别 ReadWrite (默认) | ReadOnly | NoReadOrWrite

编程用法

尽量减少出现代数环 — 消除人为代数环的选项 off (默认) | on

编程用法

采样时间(-1 表示继承) — 指定时间间隔 -1 (默认) | [Ts 0]

编程用法

代码生成

函数打包 — 选择代码格式 自动 (默认) | 内联 | 不可重用函数 | 可重用函数

提示

依存关系

编程用法

模块特性

扩展功能

C/C++ 代码生成 使用 Simulink® Coder™ 生成 C 代码和 C++ 代码。

HDL 代码生成 使用 HDL Coder™ 为 FPGA 和 ASIC 设计生成 VHDL、Verilog 和 SystemVerilog 代码。

PLC 代码生成 使用 Simulink® PLC Coder™ 生成结构化文本代码。

定点转换 使用 Fixed-Point Designer™ 设计和仿真定点系统。

版本历史记录

R2021a: 报告 MATLAB Function 模块在快速加速模式下的运行时错误

R2020a: 对 MATLAB Function 模块的 64 位整数类型支持

R2019b: 对 MATLAB Function 模块的字符串支持

另请参阅

主题

WeChat

u — 输入端口
标量 | 向量 | 矩阵

y — 输出端口
标量 | 向量 | 矩阵

显示端口标签 — 端口标签的显示选项
FromPortIcon (默认) | 无 | FromPortBlockName | SignalName

读取/写入权限 — 模块内容的访问级别
ReadWrite (默认) | ReadOnly | NoReadOrWrite

尽量减少出现代数环 — 消除人为代数环的选项
off (默认) | on

采样时间(-1 表示继承) — 指定时间间隔
`-1` (默认) | `[Ts 0]`

函数打包 — 选择代码格式
自动 (默认) | 内联 | 不可重用函数 | 可重用函数

C/C++ 代码生成
使用 Simulink® Coder™ 生成 C 代码和 C++ 代码。

HDL 代码生成
使用 HDL Coder™ 为 FPGA 和 ASIC 设计生成 VHDL、Verilog 和 SystemVerilog 代码。

PLC 代码生成
使用 Simulink® PLC Coder™ 生成结构化文本代码。

定点转换
使用 Fixed-Point Designer™ 设计和仿真定点系统。