Customize C Functions Generated from Simulink Functions Scoped to Top Model

In the generated model code, each Simulink function corresponds to one of the generated functions. The return value and input arguments of the generated function represent the Argument Inports and Argument Outports of the Simulink function, and the function body corresponds to the Simulink function logic.

A scoped Simulink$${}^{\circledR }$$ function is a Simulink Function block with the Function visibility parameter of its Trigger block specified as scoped. When a scoped Simulink function is located in the top model, it is callable from the top model and from any subsystem in its hierarchy. To read more about scoped Simulink functions, see Scoped Simulink Function Blocks in Models.

This example shows how to customize the name, return value, input arguments, and qualifier of a function generated from a scoped Simulink function locate in the top model.

Open Model and Explore Scoped Simulink Function Block

Load the model SimFuncs and open the scoped Simulink Function block.

sfModel = "SimFuncs";
scopedSf = "SimFuncs/scopedSimFunc";
load_system(sfModel)
open_system(scopedSf)

In scopedSimFunc, double-click the Trigger block s_func to open its Block Parameters dialog box.

Treat as Simulink function is selected and Function visibility is set to scoped.

Customize Generated Function Name

A function customization template is a set of specifications for generating functions. These templates are defined in the Embedded$${}^{\circledR }$$ Coder™ Dictionary of the model, or in a shared dictionary linked to the model. To learn more about templates, see Embedded Coder Dictionary > Function Customization Templates.

The name of the function generated from the scoped Simulink function depends on the function customization template of the Execution function category of the model. If the template for this category is specified as Default, then the function is generated with the default name modelName_functionName, where modelName is the model name and functionName is the function name specified in the Simulink Function block. If the specified template for the Execution category is not Default, then the Function Naming Rule of the template is used for generating the function name. The naming rule is a combination of valid C language characters and the macros $R, $N, $U, $C, and $M. For the definition of each macro, see Embedded Coder Dictionary > Function Naming Rule.

Note:

• The names of all functions generated from scoped Simulink Function blocks located in the top model adhere to the same naming rules. Customizing names of individual Simulink functions located in the top model is not supported.

• The individual function customization template you specify for the Simulink function itself has no effect on the generated function name.

• This example uses the Embedded Coder Dictionary of the model, but you can alternatively use a shared dictionary linked to the model.

Open the Embedded Coder Dictionary of the model:

1. Open the Embedded Coder® app.

2. In the Simulink Toolstrip, navigate to the C Code tab.

3. Select Code Interface > Embedded Coder Dictionary (Model)

In the dictionary that opens:

1. On the left pane, select Function Customization Template.

2. In the middle pane, click Create to create a new template.

3. On the right pane, change the value of Name to SimFuncTemplate.

4. Specify Function Naming Rule as custName_$N. The macro $N is replaced by the name of the function defined in the Simulink Function block, s_func.

Specify the function customization template of the execution function category as the new template you created:

In the Code Mappings editor, navigate to the Function Defaults tab. For the Execution category, select SimFuncTemplate from the Function Custom Template list.

Customize Argument Identifiers

The identifiers of both input and output arguments of the generated function are defined by the naming rule specified in the configuration parameter Subsystem method arguments. The naming rule is a combination of valid C language characters and the macros $I, $M, $N, $U.

• The macro $I is replaced with the letter u for each input argument that corresponds to an Argument Inport of the Simulink function, the letter y for each input argument that corresponds to an Argument Outport of the Simulink function, and the letter pair uy for each combined input argument, that corresponds to one Argument Inport and one Argument Outport of the Simulink function. A demonstration of combined arguments is provided in the example, in the section Use Combined Inports and Outports.

• The macro $N is replaced by the name of the Argument Inport or Argument Outport of the Simulink function.

• The macro $M is replaced by an auto generated name-mangling text, required to avoid naming collisions. If there is no name collision, this macro is ignored.

For detailed definitions of the macros, see Subsystem method arguments Settings.

Note: Customizing argument identifiers of individual scoped Simulink functions is not supported.

Define the naming rule for argument identifiers by specifying the configuration parameter Subsystem method arguments:

1. Open the Configuration Parameters dialog box of the model and navigate to Code Generation > Identifiers.

2. On the right, locate the parameter Subsystem method arguments, and specify its value as custArg_$I_$N$M.

3. Click Apply.

Generate code from the model and examine the generated function code:

1. In the Simulink® Toolstrip, select the C Coder tab. Then, in the Generate Code section, click Generate Code .

2. Open the Code pane and navigate to the generated header file SimFuncs.h. Then search for s_func to see the declaration of the function.

The function name and argument identifiers adhere to the naming rules you specified.

Prepare to Customize Generated Function Arguments

To customize the function, use the Configure C/C++ Function Interface dialog box:

In the Code Mappings editor, navigate to the Functions tab. Locate the entry with Simulink Function:s_func in the Source column and click on the Function Preview content of the entry.

The Configure C/C++ Function Interface dialog box opens.

Customize Function Arguments

The generated function uses its input arguments and its return value to represent the Argument Inports and Argument Outports of the Simulink function. You can:

• Optionally designate one of the Argument Outports of the Simulink function to become the return value of the generated function. Each of the remaining Argument Outports corresponds to one input argument passed by pointer in the generated function.

• Specify the type qualifier of each argument that corresponds to an Argument Inport — passing the argument by value, or by reference as a pointer input argument.

• Customize argument order.

Designate Return Value

The C language syntax allows only one explicit return value. You can specify the return value of the generated function as either void or as one of the Argument Outports of the Simulink Function block. Except for the Argument Outport you designate to be the return value of the generated function, all Argument Outports become pointer input arguments in the generated function. You can customize the identifiers of these implicit output arguments. In this example, designate the Argument Outport s_out2 as the return value.

From the C/C++ return argument list select s_out2. Then, click Apply. The function prototype is updated accordingly.

Customize Input Arguments

For each input argument you can specify one of two values for C/C++ Type Qualifier:

• Pointer to const — The argument is passed as a pointer to a constant in the generated function.

• Auto — The code generator attempts to have the argument passed by value in the generated function. If it cannot, the argument is passed as a pointer in the generated function.

In the table at the bottom of the Configure C/C++ Function Interface dialog box, locate the entries for the input arguments. In the C/C++ Type Qualifier column, select Auto for s_in1, and Pointer to const for s_in2. Click Apply. The function prototype changes accordingly.

You can see the type qualifier for s_out1, Pointer, but you cannot change it.

Customize Argument Order

You can customize the order that arguments appear by reordering the table rows at the bottom of the Configure C/C++ Function Interface dialog box. Locate the dotted drag-and-drop area on the left side of the table entries, and adjust the order to be s_in2, s_out1, and s_in1. Click Apply. The order of the arguments in the C/C++ function prototype changes according to the order you specified.

Generate model code again and open the generated source code file SimFuncs.c in the Code pane. Examine the definition of the generated function.

In the generated code:

• The argument order and qualifiers adhere to your specifications.

• The return value is kept, during the running of the function, in the temporary variable custArg_y_s_out2_0, which corresponds to Argument Outport s_out2 of the Simulink function.

Use Combined Inports and Outports

You can customize the generated function to have combined, in-out arguments, corresponding each to one Argument Inport and one Argument Outport of the Simulink function. A combined argument is passed by pointer and is used in the generated function for both input and output. To use combined arguments, specify the same identifier for both the Argument Inport and the Argument Outport in the Simulink Function block. In the example, update the Simulink function prototype with the argument s_in_out as both the first Argument Inport and the first Argument Outport.

In the Simulink Editor, navigate to the top model. The right block in the lower part is the scoped Simulink Function block, scopedSimFunc. Above it, its Function Caller block, scopedSfCaller.

Update the prototype in the Simulink function block:

1. Click once on the prototype of the Simulink Function block to turn on editing mode.

2. Revise the prototype to [s_in_out,s_out2] = s_func(s_in_out,s_in2).

Update the Function Caller block:

1. Double-click on the scoped Simulink Function Caller block, scopedSfCaller.

2. In the Block Parameters dialog box, change the Function prototype to the new Simulink function prototype.

3. Click OK.

Customize Function Arguments

You need to update the function argument specifications to conform to the new Simulink function prototype.

Open the Configure C/C++ Function Interface dialog box from the Functions tab of the Code Mappings editor.

1. Specify the return argument as void.

2. Use the dotted drag-and-drop area on the left side of the table to arrange the arguments in the order s_in_out, s_in2, s_out2.

3. For s_in2, set C/C++ Type Qualifier to Auto. This way the code generator tries to generate the input argument s_in2 as passed by value.

Click Apply. In the Configure C/C++ Function Interface dialog box:

• Simulink function prototype is [s_in_out,s_out2] = s_func(s_in_out,s_in2).

• C/C++ function prototype is void custName_s_func(* custArg_uy_s_in_out, * custArg_y_s_out2, custArg_u_s_in2).

Generate model code and examine the generated function in the Code pane.

In the generated function:

• The $I part of the naming rule is replaced by uy in the combined argument.

• The combined argument is used for both input and output in the function body. Its value is used in the calculation and is being updated.

Customize Function Qualifiers

You can customize the qualifier of the generated function to be static or extern by enabling on the configuration parameter for either qualifier. Enable the parameter for extern:

In the Configuration Parameters dialog box, navigate to Code Generation > Code Style. On the right, select Preserve extern keyword in function declarations. Click Apply.

Note:

• If both parameters are enabled, the code generator ignores the parameter for extern.

• Customizing individual scoped Simulink functions to use the static or extern qualifiers is not supported.

Generate code from the model again and open the header file SimFuncs.h to examine the declaration of the function.

The function declaration has the extern qualifier.