Programmatically Customize Generated Entry-Point C Function Names

Open Live Script

Entry-point functions are functions in the generated model code that interface with your external code. This example shows how to programmatically customize the names of the generated entry-point functions.

Note: To build an executable from a model with custom entry-point function names, use one of these methods:

Select the model configuration parameter Generate an example main program, located in the Code Generation > Templates pane of the Configuration Parameters dialog box.
Include a custom main program that uses the custom entry-point function names to invoke the generated entry-point functions.

Load Model

Load the model EntryPoints. It is a nonreusable, single-rate model configured to use the ERT system target file.

epModel = "EntryPoints";
load_system(epModel)

You can use one of these configuration options to customize the names of the generated entry-point functions.

Specify Function Customization Template for Function Categories — When you specify a function customization template for a function category, the code generator uses its naming rule to create the names of the generated functions of the category for which you do not specify an explicit naming rule or an individual function customization template.
Specify Function Customization Template for Individual Functions — When you specify a function customization template for an individual entry-point function and you do not explicitly specify a naming rule for the function, the code generator uses the naming rule of the template to create the name of the generated function.
Explicitly Specify Function Naming Rule — You can specify an explicit naming rule for any of the entry-point functions to customize its name.

The names of functions you do not use any of these options with are created according to the default naming rule for entry-point function names. When the model is configured for component deployment type the default naming rule is modelName_funcName, and you cannot change it. Here, modelName is the name of the model and funcName is the name of the function as defined in Types of Generated Entry-Point Functions. For example, the name of the generated initialization function according to this naming rule is modelName_initialize. In this example, keep the model configured for component deployment type.

When the model is configured for subcomponent deployment type, you can customize the default naming rule. This is demonstrated in the example Customize Default Naming Rule of Generated Entry-Point C Functions in Subcomponent Models.

Prepare to Customize Generated Function Names

To customize the names of generated entry-point functions programmatically, you use the code mapping object associated with the model and the Embedded Coder Dictionary of the model (or a shared dictionary linked to the model). Get handles to the code mappings object of the model and to the model dictionary. Store the handles in variables.

coderDict = coder.dictionary.open(epModel);
codeMapObj = coder.mapping.api.get(epModel);

Specify Function Customization Template for Function Categories

When you specify a template for a function category, the code generator uses the function naming rule of the template to generate the names of the entry-point functions in the category, except the names of functions for which you specify individual function customization templates or explicit naming rules. The naming rule of the function customization template is a combination of valid C language characters and the macros $R, $N, $U, $C, and $M. For the definition of each macro, see Function Naming Rule.

Get a handle to the function customization template section of the dictionary and store it in the variable dictTempSect.

dictTempSect = getSection(coderDict,"FunctionCustomizationTemplates");

Add a new template to the function customization template dictionary section (or get the handle of the existing template). Store the handle to the template object in the variable initTermEntry.

initTermTemplateName = "initTermFcnTemplate";
if(exist(dictTempSect,initTermTemplateName))
  initTermEntry = getEntry(dictTempSect,initTermTemplateName);
else
  initTermEntry = addEntry(dictTempSect,initTermTemplateName);
end

Add another new template and store its handle in the variable exeTermEntry.

exeTemplateName = "execFcnTemplate";
if(exist(dictTempSect,exeTemplateName))
  exeTermEntry = getEntry(dictTempSect,exeTemplateName);
else
  exeTermEntry = addEntry(dictTempSect,exeTemplateName);
end

Use the function set with the dictionary section object to specify the naming rule of the first template as initTermDictFcn_$N and the naming rule of the second template as execDictFcn_$N. The macro $N is replaced by the model source name of the generated function, as defined in Types of Generated Entry-Point Functions.

set(initTermEntry,FunctionName="initTermDictFcn_$N");
set(exeTermEntry,FunctionName="execDictFcn_$N");

Use the getFunctionDefault function with the code mapping object and the function template object handles to specify the function customization template for the initialize/terminate function category and the execution function category:

setFunctionDefault(codeMapObj,"InitializeTerminate",FunctionCustomizationTemplate=initTermTemplateName)
setFunctionDefault(codeMapObj,"Execution",FunctionCustomizationTemplate=exeTemplateName)

Use the slbuild function in the Command Window to generate code from the model. Use the evalc function to suppress the output of the slbuild function.

evalc("slbuild(epModel)");

Store the path to the generated header file in headerFile, and use the coder.example.extractLines function to examine the declaration of the model entry-point functions.

headerFile = "EntryPoints_ert_rtw/EntryPoints.h";
coder.example.extractLines(headerFile,"/* Model entry point functions */","terminate",true,true);

/* Model entry point functions */
void initTermDictFcn_initialize(void);
void execDictFcn_step(void);
void initTermDictFcn_terminate(void);

The function names adhere to the naming rules you specified in the function customization templates.

Specify Function Customization Template for Individual Functions

When you specify a function customization template for an individual entry-point function, its naming rule overrides the naming rule of the function customization template specified for the function category (if there is one). Add another template, loneFcnTemplate, in the model dictionary. Store its handle in the variable loneTermEntry.

loneTemplateName = "loneFcnTemplate";
if(exist(dictTempSect,loneTemplateName))
  loneTermEntry = getEntry(dictTempSect,loneTemplateName);
else
  loneTermEntry = addEntry(dictTempSect,loneTemplateName);
end

Use the function set with the template handle to specify the naming rule of the template as loneDictFcn_$N.

set(loneTermEntry,FunctionName="loneDictFcn_$N");

Use the function setFunction with the code mappings object to specify the function customization template of the termination and the step functions as the new template you added to the dictionary.

setFunction(codeMapObj,["Terminate","Periodic:D1"], ...
              FunctionCustomizationTemplate=loneTemplateName)

Generate code from the model again, and use the function coder.example.extractLines to examine the generated entry-point function declarations in the header file EntryPoints.h.

evalc("slbuild(epModel)");
coder.example.extractLines(headerFile,"/* Model entry point functions */","/* Real-time Model object */");

/* Model entry point functions */
void initTermDictFcn_initialize(void);
void loneDictFcn_step(void);
void loneDictFcn_terminate(void);

/*-
 * The generated code includes comments that allow you to trace directly
 * back to the appropriate location in the model.  The basic format
 * is <system>/block_name, where system is the system number (uniquely
 * assigned by Simulink) and block_name is the name of the block.
 *
 * Use the MATLAB hilite_system command to trace the generated code back
 * to the model.  For example,
 *
 * hilite_system('<S3>')    - opens system 3
 * hilite_system('<S3>/Kp') - opens and selects block Kp which resides in S3
 *
 * Here is the system hierarchy for this model
 *
 * '<Root>' : 'EntryPoints'
 */
#endif                                 /* EntryPoints_h_ */

/*
 * File trailer for generated code.
 *
 * [EOF]
 */

The initialization function name adheres to the category naming rule while the termination function and the step function names adhere to the naming rule of the individually specified template.

Explicitly Specify Function Naming Rule

Specifying naming rules for individual entry-point functions explicitly overrides the naming rules you specify in function customization templates. In the Command Window, use the function setFunction with the code mappings object of the model to specify the naming rule of the initialization entry-point function as explicitRule_$N.

setFunction(codeMapObj,"Initialize",FunctionName="explicitRule_$N")