自定义系统目标文件

概述

本节介绍系统目标文件的结构和内容。下面的列表显示了系统目标文件的一般结构。请注意，这不是系统目标文件的完整代码列表，只是从构成系统目标文件的每个部分中摘录的片段。

%%----------------------------
%% Header Comments Section
%%----------------------------
%% SYSTLC: Example Real-Time Target
%%    TMF: my_target.tmf MAKE: make_rtw
%% Initial comments contain directives for STF Browser.
%% Documentation, date, copyright, and other info may follow.
          ...
%selectfile NULL_FILE
         ...
%%----------------------------
%% TLC Configuration Variables Section
%%----------------------------
%% Assign code format, language, target type.
%%
%assign CodeFormat = "Embedded-C"
%assign TargetType = "RT"
%assign Language   = "C"
%%
%%----------------------------
%% TLC Program Entry Point
%%----------------------------
%% Call entry point function.
%include "codegenentry.tlc"
%%
%%----------------------------
%% (OPTIONAL) Generate Files for Build Process
%%----------------------------
%include "mytarget_genfiles.tlc"
%%----------------------------
%% RTW_OPTIONS Section
%%----------------------------
/%
  BEGIN_RTW_OPTIONS
  %% Define rtwoptions structure array. This array defines target-specific
  %% code generation variables, and controls how they are displayed.
  rtwoptions(1).prompt = 'example code generation options';
        ...
  rtwoptions(6).prompt = 'Show eliminated blocks';
  rtwoptions(6).type = 'Checkbox';
         ...
  %----------------------------------------%
  % Configure RTW code generation settings %
  %----------------------------------------%
         ...
  %%----------------------------
  %% rtwgensettings Structure
  %%----------------------------
  %% Define suffix text for naming build folder here.
  rtwgensettings.BuildDirSuffix = '_mytarget_rtw'
  %% Callback compatibility declaration
  rtwgensettings.Version = '1';

  %% (OPTIONAL) target inheritance declaration
  rtwgensettings.DerivedFrom = 'ert.tlc';
  %% (OPTIONAL) other rtwGenSettings fields...
         ...
  END_RTW_OPTIONS
%/
%%----------------------------
%% targetComponentClass - MATHWORKS INTERNAL USE ONLY
%% REMOVE NEXT SECTION FROM USER_DEFINED CUSTOM TARGETS
%%----------------------------
/%
  BEGIN_CONFIGSET_TARGET_COMPONENT
  targetComponentClass = 'Simulink.ERTTargetCC';
  END_CONFIGSET_TARGET_COMPONENT
%/

如果您基于现有系统目标文件创建自定义目标，则必须删除 targetComponentClass 部分（指令 BEGIN_CONFIGSET_TARGET_COMPONENT 和 END_CONFIGSET_TARGET_COMPONENT 之间的部分）。此部分预留给 MathWorks 内部开发的目标使用。

标头注释

文件开头的这几行采用 TLC 注释的格式。它们为系统目标文件浏览器和编译过程提供必要的信息。请注意，必须将浏览器注释放在文件头部，位于其他注释或 TLC 语句之前。

注释的存在使代码生成器能够检测到系统目标文件。打开系统目标文件浏览器时，代码生成器将扫描 MATLAB 路径中是否存在具有格式化标头注释的 TLC 文件。注释中包含以下指令：

以下标头注释来自 matlabroot/rtw/c/ert/ert.tlc。

%% SYSTLC: Embedded Coder TMF: ert_default_tmf MAKE: make_rtw
%% SYSTLC: Create Visual C/C++ Solution File for Embedded Coder
.
.
.

每个注释最多只能包含两行。

如果不指定系统目标文件中的 TMF 字段，该文件仍然有效。要更改 TemplateMakefile 参数的值，您可以改用由 rtwgensettings.SelectCallback 指定的回调函数。

您也可以使用 rtwgensettings.SelectCallback 指定的回调函数来更改外部模式参数 ExtMode、ExtModeTransport、ExtModeMexFile 或 ExtModeIntrfLevel 的值。

您可以在标头注释中指定多组指令。每一组指令在系统目标文件浏览器中显示为一种不同的目标配置。在上面的示例中，前两行代码指定 ERT 目标的默认配置。接下来两行指定创建和编译 Microsoft^® Visual C++^® 解决方案 (.sln) 文件的配置。下图显示了这些配置在系统目标文件浏览器中的显示方式。

有关自定义标头注释的示例，请参阅创建自定义目标配置。

TLC 配置变量

系统目标文件中的这一节介绍与整个代码生成过程有关的为全局 TLC 变量赋值的内容。

对于嵌入式目标，大多数情况下只需使用 ERT 目标 (ert.tlc) 使用的全局 TLC 变量设置。特别重要的是，您的系统目标文件必须为 CodeFormat TLC 变量使用 'Embedded-C' 值，并在 TLC 文件的 RTW_OPTIONS 部分使用对应的 rtwgensettings.DerivedFrom = 'ert.tlc'。验证并确认已为以下变量赋值：

TLC 程序入口点和相关的 %include 指令

代码生成过程通常以 codegenentry.tlc 开始。系统目标文件调用 codegenentry.tlc，如下所示。

%include "codegenentry.tlc"

如果您需要实现目标特定的代码生成功能，应在您的系统目标文件中包含 TLC 文件 mytarget_genfiles.tlc。此文件提供了在调用 codegenentry.tlc 前后执行自定义 TLC 代码的机制。有关此机制的信息，请参阅：

自定义代码生成过程的另一种方法是直接调用底层函数（通常由 codegenentry.tlc 调用），并在代码生成过程的每个阶段包含您自己的 TLC 函数。采用这种方法应慎重。有关详细信息，请参阅TLC 文件。

codegenentry.tlc 调用的底层函数包括：

RTW_OPTIONS 部分

RTW_OPTIONS 部分须置于以下指令之间：

/%
  BEGIN_RTW_OPTIONS
.
.
.
  END_RTW_OPTIONS
%/

RTW_OPTIONS 的第一部分定义 rtwoptions 结构体数组。使用 rtwoptions 显示自定义目标选项中介绍了这种结构体。

RTW_OPTIONS 的第二部分定义 rtwgensettings 结构体，它定义代码生成过程的编译文件夹名称和其他设置。有关 rtwgensettings 的信息，请参阅 rtwgensettings 结构体。

rtwgensettings 结构体

系统目标文件的最后一部分定义 rtwgensettings 结构体。此结构体存储写入 model.rtw 文件并由编译过程使用的信息。目标开发人员最常用到的 rtwgensettings 字段包括

其他代码生成选项

Configure Generated Code with TLC介绍了其他 TLC 代码生成变量。目标的最终用户可以通过输入以下形式的 MATLAB 命令为这些变量赋值

set_param(modelName,'TLCOptions','-aVariable=val');

但是，最好还是使用以下形式的语句在系统目标文件中为这些变量赋值：

%assign Variable = val

为了增强可读性，建议您在系统目标文件中配置 RTW 代码生成设置注释的下方添加这些赋值。

模型引用注意事项

有关系统目标文件以及为了支持代码生成器模型引用功能而需要进行的其他修改的重要信息，请参阅Support Model Referencing。

使用 rtwoptions 显示自定义目标选项

通过自定义系统目标文件中的 rtwoptions 结构体，可以控制“配置参数”对话框的代码生成窗格中显示的选项。

rtwoptions 结构体的字段定义要在“配置参数”对话框中显示的变量和关联的用户界面元素。使用 rtwoptions 结构体数组，您可以定义该对话框中显示的目标特定的选项，并将选项按类别进行组织。还可以编写回调函数，以指定如何处理这些选项。

当代码生成窗格打开时，系统将扫描 rtwoptions 结构体数组，并显示列出的选项。每个选项由一个指定的用户界面元素（复选框、编辑字段、菜单或按钮）表示，此界面元素显示该选项的当前值。

用户界面元素可以处于启用或禁用（灰显）状态。如果选项处于启用状态，则用户可以更改选项值。如果某个选项被禁用，该选项将使用默认值，并且用户无法更改该选项值。

您也可以使用 rtwoptions 结构体数组来定义触发回调函数执行但不显示在代码生成窗格中的特殊的 NonUI 元素。请参阅 NonUI 元素。

rtwoptions 结构体数组的元素被分成几个组。每个组都以 Category 类型的头元素开始。Category 头元素的 default 字段必须包含该类别中其余元素的计数。

Category 头元素的下方是要显示在代码生成窗格上的选项。每个类别中的头后面是一个或多个选项定义元素。

每个类别的目标选项都对应于“配置参数”对话框中代码生成下面列出的选项。

rtwoptions 结构体字段摘要表总结了 rtwoptions 结构体的字段。

示例 rtwoptions 结构体.  以下代码定义一个 rtwoptions 结构体数组。第一个（头）元素的默认字段设置为 4，指示头后面的元素数。

  rtwoptions(1).prompt        = 'userPreferred target options (I)';
  rtwoptions(1).type          = 'Category';
  rtwoptions(1).enable        = 'on';
  rtwoptions(1).default       = 4;   % number of items under this category
                                     % excluding this one.
  rtwoptions(1).popupstrings  = '';  % At the first item, user has to 
  rtwoptions(1).tlcvariable   = '';  % initialize all supported fields
  rtwoptions(1).tooltip       = '';
  rtwoptions(1).callback      = '';
  rtwoptions(1).makevariable  = '';

  rtwoptions(2).prompt        = 'Execution Mode';
  rtwoptions(2).type          = 'Popup';
  rtwoptions(2).default       = 'Real-Time';
  rtwoptions(2).popupstrings  = 'Real-Time|UserDefined';
  rtwoptions(2).tlcvariable   = 'tlcvariable1';
  rtwoptions(2).tooltip       = ['See this text as tooltip'];

  rtwoptions(3).prompt        = 'Log Execution Time';
  rtwoptions(3).type          = 'Checkbox';
  rtwoptions(3).default       = 'on';
  rtwoptions(3).tlcvariable   = 'RL32LogTETModifier';
  rtwoptions(3).tooltip       = ['']; % no tooltip

  rtwoptions(4).prompt        = 'Real-Time Interrupt Source';
  rtwoptions(4).type          = 'Popup';
  rtwoptions(4).default       = 'Timer';
  rtwoptions(4).popupstrings  = 'Timer|5|6|7|8|9|10|11|12|13|14|15';
  rtwoptions(4).tlcvariable   = 'tlcvariable3';
  rtwoptions(4).callback      = 'usertargetcallback(hDlg, hSrc, ''tlcvariable3'')';
  rtwoptions(4).tooltip       = [''];
  rtwoptions(4).tooltip       = ['See TLC file for how to use reserved '...
    ' keyword ''hDlg'', and ''hSrc''.'];
...
  rtwoptions(5).prompt        = 'Signal Logging Buffer Size in Doubles';
  rtwoptions(5).type          = 'Edit';
  rtwoptions(5).default       = '100000';
  rtwoptions(5).tlcvariable   = 'tlcvariable2';
  rtwoptions(5).tooltip       = [''];

第一个元素在“配置参数”对话框中的代码生成下添加了一个用户首选目标选项 (I) 窗格。该窗格显示了 rtwoptions(2)、rtwoptions(3)、rtwoptions(4) 和 rtwoptions(5) 中定义的选项。

如果要定义很多选项，可在一个系统目标文件中定义多个 Category 组。

请注意，rtwoptions 结构体和回调是使用 MATLAB 代码编写的，虽然它们嵌入在 TLC 文件中。要验证 rtwoptions 结构体定义和代码的语法，可将命令复制并粘贴到 MATLAB 命令行窗口，在 MATLAB 提示符下执行这些命令。

要了解有关 usertarget.tlc 和附带的示例回调文件的详细信息，请参阅包含自定义 rtwoptions 的示例系统目标文件。要查看更多目标特定的 rtwoptions 定义示例，请参阅 matlabroot/rtw/c 文件夹下的 target.tlc 文件。

rtwoptions 结构体字段摘要中列出了 rtwoptions 结构体的字段。

'rt_|_rt|none'

NonUI 元素.  rtwoptions 数组中类型为 NonUI 的元素仅用于调用回调。NonUI 元素不会显示在“配置参数”对话框中。如果要在打开或关闭对话框时执行与用户界面元素无关联的回调，则可以使用 NonUI 元素。有关示例，请参阅下一节，包含自定义 rtwoptions 的示例系统目标文件。

包含自定义 rtwoptions 的示例系统目标文件

本软件提供了一个工作系统目标文件（包含 MATLAB® 文件回调函数），以此为例说明如何使用 rtwoptions 结构体来显示和处理代码生成窗格上的自定义选项。这些示例与回调 API 兼容。

示例目标文件包括：

阅读本节内容时请参考示例文件。示例系统目标文件 usertarget.tlc：说明如何使用 rtwoptions 显示以下自定义目标选项：

与“配置参数”对话框中的示例目标选项交互时，请研究一下示例代码。要与示例目标文件交互，请执行以下操作：

继承目标选项

ert.tlc 提供一组基本的 Embedded Coder^® 代码生成选项。如果您的目标基于 ert.tlc，则您的系统目标文件通常应继承 ERT 中定义的选项。

可以使用 rtwgensettings 结构体中的 rtwgensettings.DerivedFrom 字段定义要从中继承选项的系统目标文件。您应按以下说明转换您的自定义目标，以使用此机制。

按以下示例所示设置 rtwgensettings.DerivedFrom 字段值：

rtwgensettings.DerivedFrom = 'stf.tlc';

其中 stf 是要从中继承选项的系统目标文件的名称。例如：

rtwgensettings.DerivedFrom = 'ert.tlc';

当“配置参数”对话框执行这行代码时，它会自动包含 stf.tlc 中的选项。如果 stf.tlc 是已转换为新布局的 MathWorks 内部系统目标文件，对话框将使用新布局显示继承的选项。

处理不支持的选项.  如果您的目标不能完全支持从 ert.tlc 继承的选项，您应该检测不支持的选项设置并显示警告或错误消息。在某些情况下，如果用户选择了您的目标不支持的选项，您可能需要中止编译过程。例如，如果您的目标不支持生成示例主程序选项，而此选项被选中，则不应允许编译过程继续下去。

即使您的目标可能无法全部支持继承的 ERT 选项，ERT 选项也要保留在“配置参数”对话框的代码生成窗格中。不要简单地从系统目标文件中的 rtwoptions 结构体中删除不支持的选项。当代码生成器执行优化时，这些选项必须存在于对话框中才能被扫描到。

例如，您可能想要阻止用户关闭单一输出/更新函数选项。那么，从对话框中删除此选项并将 TLC 变量 CombineOutputUpdateFcns 简单地指定为 on 似乎是合理的做法。但是，如果该选项不包含在对话框中，代码生成器会认为输出函数和更新函数不需要合并。这样将生成效率较低的代码。

简介

以下各节介绍自定义系统目标文件的各种技巧，包括：

必需的和推荐的 %include 指令

如果您需要实现目标特定的代码生成功能，我们建议在您的系统目标文件中包含 TLC 文件 mytarget_genfiles.tlc。

当您的系统目标文件设置必需的 TLC 环境后，您必须包含 codegenentry.tlc 才能启动标准代码生成过程。

mytarget_genfiles.tlc 提供了一种在主代码生成入口点之后执行自定义 TLC 代码的机制。请参阅使用 mytarget_genfiles.tlc。

使用 mytarget_genfiles.tlc.  mytarget_genfiles.tlc（可选）是一个很有用的中心文件，您可从中调用目标特定的 TLC 文件来生成其他文件，作为目标编译过程的一部分。例如，您的目标可能会为开发环境创建子联编文件或工程文件，或者为调试器创建命令脚本以便执行自动下载。

编译过程然后可以直接从 make 进程中调用这些生成的文件，或者在创建可执行文件后调用这些文件。这是通过 STF_make_rtw_hook.m 机制完成的，如使用 STF_make_rtw_hook 文件自定义编译过程所述。

以下 TLC 代码显示了示例 mytarget_genfiles.tlc 文件。

%selectfile NULL_FILE

%assign ModelName = CompiledModel.Name

%% Create Debugger script
%assign model_script_file = "%<ModelName>.cfg"
%assign script_file = "debugger_script_template.tlc"

%if RTWVerbose
   %selectfile STDOUT
   ### Creating %<model_script_file>
   %selectfile NULL_FILE
%endif

%include "%<script_file>"
%openfile bld_file = "%<model_script_file>"
%<CreateDebuggerScript()>
%closefile bld_file

处理目标选项值的别名

本节介绍了一些工具函数，在测试用户为目标设备类型 (ProdHWDeviceType) 和代码替换库 (CodeReplacementLibrary) 所指定的值时，您可以使用这些函数来检测和解析别名值或已有值。

RTW.isHWDeviceTypeEq.  要测试两个目标设备类型值是否表示同一台硬件设备，请调用以下函数：

result = RTW.isHWDeviceTypeEq(type1,type2)

其中 type1 和 type2 是包含目标设备类型值或别名的字符向量。

如果 type1 和 type2 是表示同一台硬件设备的字符向量，则 RTW.isHWDeviceTypeEq 函数返回 true。例如，以下调用返回 true：

RTW.isHWDeviceTypeEq('Specified','Generic->Custom')

有关目标设备类型选项 ProdHWDeviceType 的描述，请参阅硬件实现窗格参数 Device vendor 和 Device type 的命令行信息。

RTW.resolveHWDeviceType.  要返回硬件设备的设备类型值（假设该值可能是别名或已有值），请调用以下函数：

result = RTW.resolveHWDeviceType(type)

其中 type 是包含目标设备类型值或别名的字符向量。

RTW.resolveHWDeviceType 函数返回设备的设备类型值。例如，以下调用都返回 'Generic->Custom'：

RTW.resolveHWDeviceType('Specified')
RTW.resolveHWDeviceType('Generic->Custom')

有关目标设备类型选项 ProdHWDeviceType 的描述，请参阅硬件实现窗格参数 Device vendor 和 Device type 的命令行信息。

RTW.isTflEq.  要测试两个代码替换库 (CRL) 名称是否表示同一个 CRL，请调用以下函数：

result = RTW.isTflEq(name1,name2)

其中 name1 和 name2 是包含 CRL 值或别名的字符向量。

如果 name1 和 name2 是表示同一个代码替换库的字符向量，则 RTW.isTflEq 函数返回 true。例如，以下调用返回 true：

RTW.isTflEq('GNU','GNU C99 extensions')

有关 CodeReplacementLibrary 参数的描述，请参阅代码替换库。

RTW.resolveTflName.  要返回代码替换库的 CRL 值（假设该值可能是别名或已有值），请调用以下函数：

result = RTW.resolveTflName(name)

其中 name 是包含 CRL 值或别名的字符向量。

RTW.resolveTflName 函数返回引用的代码替换库的值。例如，以下调用都返回 'GNU C99 extensions'：

RTW.resolveTflName('GNU')
RTW.resolveTflName('GNU C99 extensions')

有关 CodeReplacementLibrary 参数的描述，请参阅代码替换库。

支持多个开发环境

您的目标可能需要支持多个开发环境（例如，两个或多个交叉编译器）或多个代码生成模式（例如，是为编译器生成一个二进制可执行文件还是生成一个工程文件）。

要满足这项要求，一种方法是实现多个系统目标文件。每个系统目标文件为开发环境调用一个模板联编文件。这相当于提供两个单独的目标。

更新您的自定义系统目标文件

更新自定义系统目标文件可能会影响使用更新后的系统目标文件加载的模型的选项值。如果禁用某个选项，更新后的系统目标文件将使用该选项的默认值。如果模型对该选项具有不同值，则当您用更新后的系统目标文件加载模型时，模型中的值将被丢弃，而系统目标文件将使用默认值。

简介

本教程将指导您创建一个基于 ERT 的目标 my_ert_target。此练习说明了以下几个任务，它们是创建自定义目标的典型任务：

在本练习中，您将实现一个可操作的、但较为基础的基于 ERT 的目标。此目标可作为完整实现自定义嵌入式目标的一个起点。

my_ert_target 概述

在以下各节，您将创建一个较为基础的目标 my_ert_target。此目标继承并支持 ERT 目标的标准选项，还在“配置参数”对话框中显示目标特定的附加选项（请参阅 my_ert_target 的目标特定的选项）。

my_ert_target 支持基于工具链的编译，生成在开发计算机上运行的代码和可执行文件。

您可以使用与 ERT 目标兼容的模型（请参阅配置系统目标文件）来测试 my_ert_target。生成的程序与 ERT 生成的程序以相同的方式运行。

要简化您的目标测试，请使用 targetmodel 进行测试，这是一个非常简单的定步长模型（请参阅创建测试模型和 S-Function）。targetmodel 中的 S-Function 模块使用 timestwo 示例中的源代码，并生成完全内联的代码。有关 timestwo 示例 S-Function 的进一步讨论，请参阅 S-Function 示例和Inline S-Functions with TLC。

创建目标文件夹

遵循建议的约定创建存储目标文件的文件夹，并将它们添加到 MATLAB 路径中（请参阅Folder and File Naming Conventions）。还要创建一个文件夹来存储测试模型、S-Function 和生成的代码。

此示例假定您的目标和模型文件夹位于文件夹 c:/work 中。不要将您的目标和模型文件夹放在 MATLAB 文件夹树中（即，在 matlabroot 文件夹中或在此文件夹下）。

要创建文件夹并使它们可访问，请执行以下操作：

创建基于 ERT 的、与工具链兼容的系统目标文件

通过复制和修改 ERT 目标的标准系统目标文件，为您的目标创建一个系统目标文件。然后通过查看系统目标文件浏览器和“配置参数”对话框中的新目标来验证该系统目标文件。

编辑系统目标文件.  要编辑系统目标文件，请按以下步骤操作：

创建与工具链兼容的函数.  要使编译使用工具链方法，需要在自定义系统目标文件接近末尾的位置创建一个与 SelectCallback 对应的函数。此函数用来设置工具链兼容性属性。

function enableToolchainCompliant(hSrc, hDlg)
  % The following parameters enable toolchain compliance.
  slConfigUISetVal(hDlg, hSrc, 'UseToolchainInfoCompliant', 'on');
  slConfigUISetVal(hDlg, hSrc, 'GenerateMakefile','on');
  
  % The following parameters are not required for toolchain compliance.
  % But, it is recommended practice to set these default values and 
  % disable the parameters (as shown).
  slConfigUISetVal(hDlg, hSrc, 'RTWCompilerOptimization','off');
  slConfigUISetVal(hDlg, hSrc, 'MakeCommand','make_rtw');
  slConfigUISetEnabled(hDlg, hSrc, 'RTWCompilerOptimization',false);
  slConfigUISetEnabled(hDlg, hSrc, 'MakeCommand',false);
  hCS = hSrc.getConfigSet(); 
  hCS.refreshDialog; 
end

查看系统目标文件.  此时，您可以按以下步骤验证目标是否继承并显示 ERT 选项：

至此，基础目标的系统目标文件已完成。如果您使用工具链方法，现在即可为您的目标调用编译过程。

如果您更喜欢使用模板联编文件方法，则在系统目标文件标头注释中引用 TMF my_ert_target_vcx64.tmf 将会阻止您为目标调用编译过程，直到该 TMF 文件就绪为止。因此，您必须先创建 my_ert_target_vcx64.tmf 文件。

创建基于 ERT 的模板联编文件

如果您使用工具链联编文件方法以及与工具链兼容的自定义目标，则可以省略适用于模板联编文件方法的步骤。（请跳过本节内容。）

如果您使用模板联编文件方法，请按照适用于模板联编文件的步骤进行操作，并省略从系统目标文件中调用函数以实现工具链兼容性的步骤，如创建基于 ERT 的、与工具链兼容的系统目标文件 中所述。

通过复制和修改提供的 ERT 模板联编文件，为您的目标创建一个模板联编文件。选择最适合您的目标的模板联编文件。此示例使用 ert_vcx64.tmf，但您也可以使用 ert_unix.tmf。

如果您有 Microsoft Visual C++ 编译器许可证，您现在可以生成代码并编译可在开发计算机上运行的可执行文件。在下面几节，您将创建一个测试模型并使用 my_ert_target 来测试编译过程。

创建测试模型和 S-Function

在本节中，您将构建一个简单的测试模型，以便在后面的代码生成中继续使用：

将 targetmodel 模型保持打开状态供下一节使用，下一节将使用测试模型生成代码。

验证目标操作

在本节中，您将为 my_ert_target 自定义目标配置 targetmodel，然后生成代码并编译可执行文件：