legacy_code

通过使用代码继承工具集成现有 C/C++ 代码

全页折叠

语法

legacy_code('help')

specs = legacy_code('initialize')

legacy_code('sfcn_cmex_generate', specs)

legacy_code('compile', specs, compilerOptions)

legacy_code('generate_for_sim', specs, modelname)

legacy_code('slblock_generate', specs, modelname)

legacy_code('sfcn_tlc_generate', specs)

legacy_code('sfcn_makecfg_generate', specs)

legacy_code('rtwmakecfg_generate', specs)

legacy_code('backward_compatibility')

说明

legacy_code('help') 显示代码继承工具的使用说明。

示例

specs = legacy_code('initialize') 初始化代码继承工具数据结构体 specs，它用于注册现有 C 或 C++ 代码的特征以及代码继承工具生成的 S-Function 的属性。

legacy_code('sfcn_cmex_generate', specs) 生成由代码继承工具数据结构体 specs 指定的 S-Function 源文件。

legacy_code('compile', specs, compilerOptions) 编译并链接由代码继承工具根据数据结构体 specs 以及您可能指定的编译器选项生成的 S-Function。这些编译器选项必须受 mex 函数支持。

示例

legacy_code('generate_for_sim', specs, modelname) 通过一个步骤生成、编译并链接 S-Function。如果代码继承工具数据结构体的 Options.useTlcWithAccel 字段设置为逻辑值 1 (true)，该函数还会生成 TLC 文件用于加速仿真。

示例

legacy_code('slblock_generate', specs, modelname) 为代码继承工具根据数据结构体 specs 生成的 S-Function 生成封装的 S-Function 模块。该模块将出现在由 modelname 指定的 Simulink^® 模型中。如果您忽略 modelname，该模块将出现在空模型编辑器窗口中。

legacy_code('sfcn_tlc_generate', specs) 为代码继承工具根据数据结构体 specs 生成的 S-Function 生成 TLC 文件。此选项在您想执行以下操作时才有意义：

强制 Simulink 软件中的加速模式使用生成的 S-Function 的 TLC 内联代码。有关详细信息，请参阅 ssSetOptions SimStruct 函数和 SS_OPTION_USE_TLC_WITH_ACCELERATOR S-Function 选项的描述。
使用 Simulink Coder™ 软件从您的 Simulink 模型中生成代码。有关详细信息，请参阅使用代码继承工具在生成的代码中导入对外部代码的调用 (Simulink Coder)。

legacy_code('sfcn_makecfg_generate', specs) 为代码继承工具根据数据结构体 specs 生成的 S-Function 生成 sFunction_makecfg.m 文件。如果使用 Simulink Coder 从 Simulink 模型生成代码，则可以使用此选项为 S-Function 编译过程指定其他项，如源文件夹、预处理器宏和链接对象。例如，您可以指定 S-Function 依赖的源文件，这些源文件位于包含生成的 S-Function 可执行文件的文件夹之外的文件夹中。有关详细信息，请参阅Use makecfg to Customize Generated Makefiles for S-Functions (Simulink Coder)和使用代码继承工具在生成的代码中导入对外部代码的调用 (Simulink Coder)。

示例

legacy_code('rtwmakecfg_generate', specs) 为代码继承工具根据数据结构体 specs 生成的 S-Function 生成 rtwmakecfg.m 文件。如果使用 Simulink Coder 从 Simulink 模型生成代码，则可以使用此选项为 S-Function 编译过程指定其他项，如源文件夹、预处理器宏和链接对象。例如，您可以指定 S-Function 依赖的源文件，这些源文件位于包含生成的 S-Function 可执行文件的文件夹之外的文件夹中。有关详细信息，请参阅Use rtwmakecfg.m API to Customize Generated Makefiles (Simulink Coder)和使用代码继承工具在生成的代码中导入对外部代码的调用 (Simulink Coder)。

legacy_code('backward_compatibility') 自动将使用代码继承工具的语法更新为此参考页以及Integrate C Functions Using Legacy Code Tool中介绍的支持的语法。

示例

全部折叠

已有函数的按值或按地址传递的输入

打开模型

此示例说明如何使用代码继承工具集成按值与按地址传递其输入参数的已有 C 函数。

代码继承工具允许您：

提供已有函数设定；
生成 C-MEX S-Function，在仿真期间使用它来调用现有代码；以及
编译和构造生成的 S-Function 以进行仿真。

提供已有函数设定

代码继承工具附带的函数接受特定的数据结构体或结构体数组作为参数。可以通过调用函数 legacy_code() 并使用 'initialize' 作为第一个输入来初始化数据结构体。初始化结构体之后，您必须将其属性指定给与要集成的现有代码对应的值。此示例中调用的已有函数的原型为：

FLT filterV1(const FLT signal, const FLT prevSignal, const FLT gain)
FLT filterV2(const FLT* signal, const FLT prevSignal, const FLT gain)

其中 FLT 是浮点类型的 typedef。已有源代码位于文件 your_types.h、myfilter.h、filterV1.c 和 filterV2.c 中。

请注意两个结构体中定义的 OutputFcnSpec 的区别：第一种情况指定第一个输入参数按值传递，第二种情况指定按指针传递。

defs = [];

% sldemo_sfun_filterV1
def = legacy_code('initialize');
def.SFunctionName = 'sldemo_sfun_filterV1';
def.OutputFcnSpec = 'single y1 = filterV1(single u1, single u2, single p1)';
def.HeaderFiles   = {'myfilter.h'};
def.SourceFiles   = {'filterV1.c'};
def.IncPaths      = {'sldemo_lct_src'};
def.SrcPaths      = {'sldemo_lct_src'};
defs = [defs; def];

% sldemo_sfun_filterV2
def = legacy_code('initialize');
def.SFunctionName = 'sldemo_sfun_filterV2';
def.OutputFcnSpec = 'single y1 = filterV2(single u1[1], single u2, single p1)';
def.HeaderFiles   = {'myfilter.h'};
def.SourceFiles   = {'filterV2.c'};
def.IncPaths      = {'sldemo_lct_src'};
def.SrcPaths      = {'sldemo_lct_src'};
defs = [defs; def];

生成和编译 S-Function 以供仿真期间使用

再次调用函数 legacy_code() 并将第一个输入设置为 'generate_for_sim'，以便根据输入参数 'defs' 提供的描述自动生成和编译 C-MEX S-Function。此 S-Function 用于在仿真中调用已有函数。S-Function 的源代码位于文件 sldemo_sfun_filterV1.c 和 sldemo_sfun_filterV2.c 中。

legacy_code('generate_for_sim', defs);

### Start Compiling sldemo_sfun_filterV1
    mex('-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368', '-c', '-outdir', '/tmp/Bdoc23b_2347338_254548/tpebceeac5_de9c_4912_9353_b1b853714148', '/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368/sldemo_lct_src/filterV1.c')
Building with 'gcc'.
MEX completed successfully.
    mex('sldemo_sfun_filterV1.c', '-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368', '/tmp/Bdoc23b_2347338_254548/tpebceeac5_de9c_4912_9353_b1b853714148/filterV1.o')
Building with 'gcc'.
MEX completed successfully.
### Finish Compiling sldemo_sfun_filterV1
### Exit

### Start Compiling sldemo_sfun_filterV2
    mex('-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368', '-c', '-outdir', '/tmp/Bdoc23b_2347338_254548/tp8d5370e2_7295_4432_8471_64bb48773a66', '/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368/sldemo_lct_src/filterV2.c')
Building with 'gcc'.
MEX completed successfully.
    mex('sldemo_sfun_filterV2.c', '-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368/sldemo_lct_src', '-I/tmp/Bdoc23b_2347338_254548/tp9a1ab271/simulink_features-ex08075368', '/tmp/Bdoc23b_2347338_254548/tp8d5370e2_7295_4432_8471_64bb48773a66/filterV2.o')
Building with 'gcc'.
MEX completed successfully.
### Finish Compiling sldemo_sfun_filterV2
### Exit

生成 rtwmakecfg.m 文件以进行代码生成

在创建 TLC 模块文件后，可再次调用函数 legacy_code() 并将第一个输入设置为 'rtwmakecfg_generate'，以生成 rtwmakecfg.m 文件来通过 Simulink® Coder™ 支持代码生成。如果 S-Function 需要的源文件和头文件与 S-Function 不在同一个文件夹中，而您要将这些依存项添加到代码生成过程中生成的联编文件中，请生成 rtwmakecfg.m 文件。

注意：仅当要在加速模式下仿真模型时，才完成此步骤。

legacy_code('rtwmakecfg_generate', def);

生成封装的 S-Function 模块以调用生成的 S-Function

在编译 C-MEX S-Function 源代码后，可以再次调用函数 legacy_code() 并将第一个输入设置为 'slblock_generate'，以生成封装的 S-Function 模块，这些模块配置为调用上述 S-Function。这些模块放置在新模型中，并且可以复制到现有模型中。

% legacy_code('slblock_generate', defs);

集成现有代码

模型 sldemo_lct_filter 显示与现有代码的集成。子系统 TestFilter 的作用相当于通过生成的 S-Function 调用已有 C 函数的工具，而单位延迟的作用是存储之前的输出值。

open_system('sldemo_lct_filter')
open_system('sldemo_lct_filter/TestFilter')
sim('sldemo_lct_filter');

输入参数

全部折叠

`specs` — 现有 C 或 C++ 代码和 S-Function 的设定
结构体

现有 C 或 C++ 代码和正在生成的 S-Function 的设定，指定为具有以下字段的 struct：

S-Function 命名

SFunctionName（必需）- 由代码继承工具生成的 S-Function 的名称，指定为字符向量或字符串。

定义代码继承工具函数设定

InitializeConditionsFcnSpec - S-Function 为初始化和重置状态而调用的函数，指定为非空字符向量或字符串。必须使用 Simulink 软件能够解释的标记声明此函数，如Declaring Legacy Code Tool Function Specifications中所述。
OutputFcnSpec - S-Function 在每个时间步调用的函数，指定为非空字符向量或字符串。必须使用 Simulink 软件能够解释的标记声明此函数，如Declaring Legacy Code Tool Function Specifications中所述。
StartFcnSpec - S-Function 在开始执行时调用的函数，指定为字符向量或字符串。此函数可以访问 S-Function 参数以及工作数据。必须使用 Simulink 软件能够解释的标记声明此函数，如Declaring Legacy Code Tool Function Specifications中所述。
TerminateFcnSpec - S-Function 在终止执行时调用的函数，指定为字符向量或字符串。此函数可以访问 S-Function 参数以及工作数据。必须使用 Simulink 软件能够解释的标记声明此函数，如Declaring Legacy Code Tool Function Specifications中所述。

定义编译资源

HeaderFiles - 编译所需的头文件的文件名，指定为字符向量元胞数组或字符串数组。
SourceFiles - 编译所需的源文件，指定为字符向量元胞数组或字符串数组。您可以使用绝对或相对路径名称来指定源文件。
HostLibFiles - 主机编译所需的库文件，指定为字符向量元胞数组或字符串数组。您可以使用绝对或相对路径名称来指定库文件。
TargetLibFiles - 目标（即独立）编译所需的库文件，指定为字符向量元胞数组或字符串数组。您可以使用绝对或相对路径名称来指定库文件。
IncPaths - 包含头文件的目录，指定为字符向量元胞数组或字符串数组。您可以使用绝对或相对路径名称来指定目录。
SrcPaths - 包含源文件的目录，指定为字符向量元胞数组或字符串数组。您可以使用绝对或相对路径名称来指定目录。
LibPaths - 包含主机和目标库文件的目录，指定为字符向量元胞数组或字符串数组。您可以使用绝对或相对路径名称来指定目录。

指定采样时间

SampleTime - 以下项之一：

'inherited'（默认值）- 从源模块继承采样时间。
'parameterized' - 采样时间表示为可调参数。生成的代码可以通过调用 MEX API 函数（如 mxGetPr 或 mxGetData）来访问该参数。
固定 - 您显式指定的采样时间。有关如何指定采样时间的信息，请参阅指定采样时间。

如果您指定此字段，必须最后指定它。

定义 S-Function 选项

Options - S-Function 选项，指定为结构体。结构体的字段包括：

canBeCalledConditionally - S-Function SS_OPTION_CAN_BE_CALLED_CONDITIONALLY 选项的设置，指定为逻辑值。默认情况下，值为 true (1)。
convertNDArrayToRowMajor - 在列优先格式和行优先格式之间自动转换矩阵，指定为逻辑值。列优先格式由 MATLAB^®、Simulink 和生成的代码使用。行优先格式由 C 使用。默认情况下，值为 false (0)。如果您当前指定该选项的旧版本 convert2DMatrixToRowMajor，函数将自动指定选项的新版本 convertNDArrayToRowMajor。

注意
此选项不支持复数数据的二维矩阵。
isMacro - 现有代码是否为 C 宏，指定为逻辑值。默认情况下，值为 false (0)。
isVolatile - S-Function SS_OPTION_NONVOLATILE 选项的设置，指定为逻辑值。默认情况下，值为 true (1)。
language - 代码继承工具将生成的 S-Function 的目标语言，指定为 'C' 或 'C++'。默认情况下，值为 'C'。

注意
代码继承工具可与 C++ 函数对接，但不能与 C++ 对象对接。有关解决方法，请参阅 Simulink 文档中的Legacy Code Tool Limitations。
outputsConditionallyWritten - 现有代码是否有条件地写入输出端口，指定为逻辑值。如果为 true，生成的 S-Function 指定与每个输出端口关联的内存无法覆盖并且是全局性的 (SS_NOT_REUSABLE_AND_GLOBAL)。如果为 false，则与每个输出端口关联的内存可重用并且是局部性的 (SS_REUSABLE_AND_LOCAL)。默认情况下，值为 false (0)。有关详细信息，请参阅 ssSetOutputPortOptimOpts。
singleCPPMexFile - 生成的代码是否：
- 要求您将内联 S-Function 仅生成为一个文件 (.cpp) 并进行管理，而不是两个文件（.c 和 .tlc）。
- 按照模型配置参数指定的方式维护模型代码风格（一般表达式中和 if 语句中的条件表达式中括号级别的用法和操作数顺序的保持）。
指定为逻辑值。默认情况下，值为 false。
限制
在下列情况下，不能将 singleCPPMexFile 字段设置为 true：
- Options.language='C++'
- 您使用以下 Simulink 对象之一并将 IsAlias 属性设置为 true：
  Simulink.Bus
  Simulink.AliasType
  Simulink.NumericType
- 代码继承工具函数设定中包含 void* 或 void**，以表示状态参数的标量工作数据
- 代码继承工具结构体的 HeaderFiles 字段指定多个头文件
supportsMultipleExecInstances - 包含对 ssSupportsMultipleExecInstances 函数的调用的选项，指定为逻辑值。默认情况下，值为 false (0)。
supportCodeReuseAcrossModels - 生成的 S-Function 是否可以在模型引用层次结构中重用，指定为逻辑值。如果为 true，则生成的 S-Function 包括 ssSetSupportedForCodeReuseAcrossModels 函数调用。代码生成器为 slprj\ert\_sharedutils 文件夹中的 S-Function 生成代码。
supportCoverage - 生成的 S-Function 是否必须与模型覆盖率兼容，指定为逻辑值。默认情况下，值为 false (0)。
supportCoverageAndDesignVerifier - 生成的 S-Function 是否必须与模型覆盖率和 Simulink Design Verifier™ 兼容，指定为逻辑值。默认情况下，值为 false (0)。
useTlcWithAccel - S-Function SS_OPTION_USE_TLC_WITH_ACCELERATOR 选项的设置，指定为逻辑值。默认情况下，值为 true (1)。