Support Model Referencing

If you want to use a custom system target file for building a model that has referenced models, you must configure the custom system target file to support model referencing.

Requirements for Model Referencing with a Custom System Target File

To build a model that references other models:

Use a custom system target file that is derived from a GRT or ERT system target file.
The custom system target file must declare model reference compliance –– see Declaring Model Referencing Compliance.
The template makefile must define some entities that support model referencing –– see Providing Model Referencing Support in the TMF.

Declaring Model Referencing Compliance

To declare model reference compliance for your target, you must implement a callback function that sets the ModelReferenceCompliant flag, and then install the callback function in the SelectCallback field of the rtwgensettings structure in your system target file. The callback function is triggered whenever the user selects the target in the System Target File Browser. For example, the following system target file code installs a SelectCallback function named custom_select_callback_handler:

rtwgensettings.SelectCallback = 'custom_select_callback_handler(hDlg,hSrc)';

The arguments to the SelectCallback function (hDlg, hSrc) are handles to private data used by the callback API functions. These handles are restricted to use in system target file callback functions. They should be passed in without alteration.

Your callback function should set the ModelReferenceCompliant flag as follows:

slConfigUISetVal(hDlg,hSrc,'ModelReferenceCompliant','on');
slConfigUISetEnabled(hDlg,hSrc,'ModelReferenceCompliant',false);
hSrc.getConfigSet.refreshDialog;

If you might use the target to build models containing large model reference hierarchies, consider configuring the target to support parallel builds, as discussed in Reduce Build Time for Referenced Models by Using Parallel Builds.

To configure a target for parallel builds, your callback function must also set the ParMdlRefBuildCompliant flag as follows:

slConfigUISetVal(hDlg,hSrc,'ParMdlRefBuildCompliant','on');
slConfigUISetEnabled(hDlg,hSrc,'ParMdlRefBuildCompliant',false);
hSrc.getConfigSet.refreshDialog;

For more information about the system target file callback API, see the slConfigUIGetVal, slConfigUISetEnabled, and slConfigUISetVal function reference pages.

Providing Model Referencing Support in the TMF

To configure the template makefile (TMF) for model referencing:

Add the following make variables and tokens to be expanded when the makefile is generated:

MODELREFS                 = |>MODELREFS<|
MODELLIB                  = |>MODELLIB<|
MODELREF_LINK_LIBS        = |>MODELREF_LINK_LIBS<|
MODELREF_LINK_RSPFILE     = |>MODELREF_LINK_RSPFILE_NAME<|
RELATIVE_PATH_TO_ANCHOR   = |>RELATIVE_PATH_TO_ANCHOR<|
MODELREF_TARGET_TYPE      = |>MODELREF_TARGET_TYPE<|

The following code excerpt shows how makefile tokens are expanded for a referenced model.

MODELREFS                 =
MODELLIB                  = engine3200cc_rtwlib.a
MODELREF_LINK_LIBS        =
MODELREF_LINK_RSPFILE     =
RELATIVE_PATH_TO_ANCHOR   = ../../..
MODELREF_TARGET_TYPE      = RTW

The following code excerpt shows how makefile tokens are expanded for the top model that references the referenced model.

MODELREFS                 = engine3200cc transmission
MODELLIB                  = 
MODELREF_LINK_LIBS        = engine3200cc_rtwlib.a transmission_rtwlib.a
MODELREF_LINK_RSPFILE     =
RELATIVE_PATH_TO_ANCHOR   = ..
MODELREF_TARGET_TYPE      = NONE

Token	Expands to
`MODELREFS` for the top model	List of referenced model names.
`MODELLIB`	Name of the library generated for the model.
`MODELREF_LINK_LIBS` token for the top model	List of referenced model libraries that the top model links against.
`MODELREF_LINK_RSPFILE` token for the top model	Name of a response file that the top model links against. This token is valid only for build environments that support linker response files. For an example of its use, see `matlabroot/toolbox/coder/compile/tmf/grt_vcx64.tmf`.
`RELATIVE_PATH_TO_ANCHOR`	Relative path, from the location of the generated makefile, to the MATLAB^® working folder.
`MODELREF_TARGET_TYPE`	Signifies the type of target being built. Possible values are `NONE`: Standalone model or top model referencing other models `RTW`: Model reference target build `SIM`: Model reference simulation target build

Add the RELATIVE_PATH_TO_ANCHOR include path to the overall INCLUDES variable.

INCLUDES = -I. -I$(RELATIVE_PATH_TO_ANCHOR) $(ADD_INCLUDES) \
	   $(USER_INCLUDES) $(SHARED_INCLUDES)

Change the SRCS variable in your TMF so that it initially lists only common modules. Additional modules are then appended conditionally, as described in the next step. For example, change
```
SRCS  = $(MODEL).c $(MODULES) ert_main.c $(ADD_SRCS) $(EXT_SRC)
```
to
```
SRCS = $(MODULES)
```

Create variables to define the final target of the makefile. You can remove variables that may have existed for defining the final target. For example, remove

PROGRAM   = ../$(MODEL)

and replace it with

ifeq ($(MODELREF_TARGET_TYPE), NONE)
  # Top model for RTW
  PRODUCT            = $(RELATIVE_PATH_TO_ANCHOR)/$(MODEL)
  BIN_SETTING        = $(LD) $(LDFLAGS) -o $(PRODUCT) $(SYSLIBS)
  BUILD_PRODUCT_TYPE = "executable"
  # ERT based targets
  SRCS               += $(MODEL).c ert_main.c $(EXT_SRC)
  # GRT based targets
  # SRCS             += $(MODEL).c grt_main.c rt_sim.c $(EXT_SRC) $(SOLVER)

else
  # sub-model for RTW
  PRODUCT            = $(MODELLIB)
  BUILD_PRODUCT_TYPE = "library"
endif

Note

If the template makefile is associated with a toolchain, remove $(MODEL).c or $(MODEL).$(TARGET_LANG_EXT) from the SRCS list.

Create rules for the final target of the makefile (replace existing final target rules). For example:

ifeq ($(MODELREF_TARGET_TYPE),NONE)
  # Top model for RTW
  $(PRODUCT) : $(OBJS) $(LIBS) $(MODELREF_LINK_LIBS)
               $(BIN_SETTING) $(LINK_OBJS) $(MODELREF_LINK_LIBS)
               $(LIBS)
               @echo "### Created $(BUILD_PRODUCT_TYPE): $@"
else
  # sub-model for RTW
  $(PRODUCT) : $(OBJS) $(LIBS)
               @rm -f $(MODELLIB)
               $(ar) ruvs $(MODELLIB) $(LINK_OBJS)
               @echo "### Created $(MODELLIB)"
               @echo "### Created $(BUILD_PRODUCT_TYPE): $@"
endif

Create a rule to allow referenced models to compile files that reside in the MATLAB working folder (pwd).
```
%.o : $(RELATIVE_PATH_TO_ANCHOR)/%.c
	$(CC) -c $(CFLAGS) $<
```

Note

If you are using a TMF without the variable MODELREFS, the file might have been used with a previous release of Simulink^® software. If you want your TMF to support model referencing, add either variable MODELREFS to the make file.

Controlling Configuration Option Value Agreement

By default, the value of a configuration option defined in the system target file for a TLC-based custom target must be the same in a referenced model and its parent model. To relax this requirement, include the modelReferenceParameterCheck field in the rtwoptions structure element that defines the configuration option, and set the value of the field to 'off'. For example:

rtwoptions(2).prompt         = 'My Custom Parameter';
rtwoptions(2).type           = 'Checkbox';
rtwoptions(2).default        = 'on';
rtwoptions(2).modelReferenceParameterCheck  = 'on';
rtwoptions(2).tlcvariable    = 'mytlcvariable';
...

The configuration option My Custom Parameter can differ in a referenced model and its parent model. See Customize System Target Files for information about TLC-based system target files, and rtwoptions Structure Fields Summary for a list of rtwoptions fields.

Preventing Resource Conflicts (Optional)

Hook files are optional TLC and MATLAB program files that are invoked at well-defined stages of the build process. Hook files let you customize the build process and communicate information between various phases of the process.

If you are adapting your custom target for code generation compatibility with model reference features, consider adding checks to your hook files for handling referenced models differently than top models to prevent resource conflicts.

For example, consider adding the following check to your STF_make_rtw_hook.m file:

% Check if this is a referenced model
mdlRefTargetType = get_param(codeGenModelName,'ModelReferenceTargetType');
isNotModelRefTarget = strcmp(mdlRefTargetType, 'NONE'); % NONE, SIM, or RTW
if isNotModelRefTarget
  % code that is specific to the top model
else
  % code that is specific to the referenced model
end

You may need to do a similar check in your TLC code.

%if !IsModelReferenceTarget()
  %% code that is specific to the top model
%else
  %% code that is specific to the referenced model
%endif