Generate Shared Utility Code
When to Generate Shared Utility Code
Blocks in a model can require common functionality to implement their algorithms. Consider modularizing this functionality into standalone support or helper functions. This approach can be more efficient than inlining the code for the functionality for each block instance. To decide about using a library or a shared utility, consider:
Packaging functions that can have multiple callers into a library when the functions are defined statically. That is, before you use the code generator to produce code for your model, the function source code exists in a file.
Packaging functions that can have multiple callers as shared utilities (produced during code generation) when the functions cannot be defined statically. For example, several model- and block-specific properties specify which functions are used and their behavior. Also, these properties determine type definitions (for example,
typedef) in shared utility header files. The number of possible combinations of properties that determine unique behavior make it impractical to define statically the possible function files before code generation.
Configure Naming of Generated Functions
Configure a default naming rule for generated shared utility functions by using one of these methods.
|A new model or an existing model for which you have mapped default customization settings by using the Code Mappings editor or code mappings programming interface||In the Embedded Coder Dictionary (Embedded Coder), define a function customization template that specifies a custom function naming rule. Then, in the Code Mappings editor or by using the code mappings programming interface, map the Shared utility function category to that template. For more information, see Configure Default C Code Generation for Categories of Data Elements and Functions (Embedded Coder).|
|A model created in a release earlier than R2018a and that has not been configured with the Code Mappings editor or code mappings programming interface||Set the model configuration parameter Shared utilities identifier format (Embedded Coder)
Once you use the Code Mappings editor or code mappings programming interface to configure a model, setting model configuration parameter Shared utilities identifier format does not impact code generation. This setting is not applicable for models configured with these specifications.
|System Target File||Programming Language|
The naming rule for shared utility functions must include the conditional checksum token
$C. To customize the length of the checksum that the code generator
produces, use parameter Shared checksum length
SharedChecksumLength) . Increasing the length of the checksum reduces
the probability of clashes.
This example shows the customization of shared utility function names for C code generation.
Open the example model
rtwdemo_configdefaultsand the Embedded Coder app.
Set model configuration parameter Shared code placement to
Open the Embedded Coder Dictionary. On the C Code tab, select Code Interface > Embedded Coder Dictionary.
On the Function Customization Templates tab, click Add to add a new function customization template.
For the function customization template, specify these configurations:
You can customize this format by using a string. You must include token
Open the Code Mappings editor. On the C Code tab, select Code Interface > Default Code Mappings.
On the Function Defaults tab, for the Shared Utility category, configure Function Customization Template as
Generate code and a code generation report.
In the left navigation pane of the report, review the list of generated files for shared utilities under Shared files.
Control Placement of Shared Utility Code
Control placement of shared utility code with the model configuration parameter
Shared code placement. The default option value is
Auto. For this setting, the code generator places required code
for fixed-point and other utilities in the
file, or a separate file in the
build folder (for example,
vdp_grt_rtw) if a model does not contain
existing shared utility code or one of these blocks:
Simulink Function blocks
Function Caller blocks
Calls to Simulink Functions from Stateflow or MATLAB Function blocks
Stateflow graphical functions when you select parameter Export Chart Level Functions
If a model contains one or more of the preceding blocks, the code generator creates and
uses a shared utilities folder within
slprj. The naming convention for
shared utility folders is
sim for simulations with
Model blocks or the name of the system target file for code
slprj/sim/_sharedutils % folder used with simulation slprj/grt/_sharedutils % folder used with grt.tlc STF slprj/ert/_sharedutils % folder used with ert.tlc STF slprj/mytarget/_sharedutils % folder used with mytarget.tlc STF
To force a model build to use the
slprj folder for shared utility
generation, even when the current model does not contain existing shared utility code or one
of the preceding blocks, set parameter Shared code placement to
Shared location. The code generator places utilities under the
slprj folder rather than in the normal build folder. This setting is
useful when you are manually combining code from several models, because it prevents symbol
collisions between the models.
Control Placement of rtwtypes.h for Shared Utility Code
rtwtypes.h header file provides fundamental type
#define statements, and enumerations. For more information,
Control placement of rtwtypes.h file by selecting whether the build process uses the
shared utilities folder. If the model build uses a shared utilities folder, the build process
slprj/. Otherwise, the
Adding a model to a model hierarchy or changing an existing model in the hierarchy can
result in updates to the shared
rtwtypes.h file during code generation. If
updates occur, recompile and, depending on your development process, reverify previously
generated code. To minimize updates to the
rtwtypes.h file, make the
following changes in the Configuration Parameters dialog box:
Select model configuration parameter Support: complex numbers even if the model does not currently use complex data types. Selecting this parameter protects against a future requirement to add support for complex data types when integrating code.
Clear parameter Support non-inlined S-functions. If you use noninlined S-functions in the model, this option generates an error.
Clear parameter Classic call interface. This parameter setting disables use of the GRT system target file.
Avoid Duplicate Header Files for Exported Data
Exported header files appear in the shared utility folder when:
You control the file placement of declarations for signals, parameters, and states by defining and applying storage classes.
The code generator places utility code in a shared location.
For example, you can specify a header file for data by using:
The Code Generation tab in a Signal Properties dialog box.
HeaderFileproperty of a data object. Data objects are objects of the classes
If you want the declaration to appear in the file
, it is a best practice to leave the
header file name unspecified. By default, the code generator places data declarations in
If you specify
as the header file
name, and if the code generator places utility code in a shared location, you cannot generate
code from the model. The code generator cannot create the file
in both the model build folder and
the shared utility folder.
Reduce Shared Utility Code Generation with Incremental Builds
You can specify that the model build generates C source files in a shared utilities folder. See Generate Shared Utility Code. These files include C source files that contain function definitions and header files that contain macro definitions. For this discussion, the term functions means functions and macros.
Blocks within the same model and blocks in different models can use a shared function when you use model reference or when you build multiple standalone models from the same start build folder. The code generator produces the code for a given function only once for the block that first triggers code generation. As the product determines the requirement to generate function code for subsequent blocks, it performs a file existence check. If the file exists, the model build does not regenerate the function. The shared utility code mechanism requires that a given function and file name represent the same functional behavior regardless of which block or model generates the function. To satisfy this requirement:
Model properties that determine function behavior contribute to the shared utility checksum or determine the function and file name.
Block properties that determine the function behavior also determine the function and file name.
During compilation, makefile rules for the shared utilities folder select compilation of
only new C files and incrementally archive the object file into the shared utility library,
rtwshared.a. Incremental compilation
Manage the Shared Utility Code Checksum
When you set the model configuration parameter Shared code placement
Shared location or when the model contains Model
blocks, the code generator places shared code in the shared utilities folder. The build
process generates a shared utilities checksum of the code generation configuration for the
During subsequent code generation, if the checksum file
exists relative to the current folder, the code generator reads that file. The code generator
verifies that the current model that you are building has configuration properties that match
the checksum of properties from the shared utility model. If mismatches occur between the
properties defined in
checksummap.mat and the current model properties, you
see an error. Use the error message to manage the checksum (for example, diagnose and resolve
the configuration issues with the current model).
View the Shared Utility Checksum Hash Table
It is helpful to view the property values that contribute to the checksum. This example
rtwdemo_lct_start_term.slx model. To load the
checksum.mat file into MATLAB®
and view the
targetInfoStruct that defines the checksum-related
rtwdemo_lct_start_term.slxmodel. In the Command Window, type:
Create and move to a new working folder.
mkdir C:\Temp\demo cd C:\Temp\demo
Save a copy of the model in the folder.
Build the model, which is set up to produce shared utilities.
On the Apps tab, under Code Generation, click Simulink Coder.
On the C Code tab, in the Generate Code section, click the Build button.
Move to the
_sharedutilsfolder created by the build process.
checksummap.matfile into MATLAB.
Display the contents of
hashTbl.targetInfoStructand examine the checksum-related property values.
For this example, the Command Window displays
hashTbl.targetInfoStruct for the shared utilities that you generated
from the model:
ans = struct with fields: ShiftRightIntArith: 'on' ProdShiftRightIntArith: 'on' Endianess: 'LittleEndian' ProdEndianess: 'LittleEndian' wordlengths: '8,16,32,32,64,32,64,64,64,64' Prodwordlengths: '8,16,32,32,64,32,64,64,64,64' TargetWordSize: '64' ProdWordSize: '64' TargetHWDeviceType: 'Custom Processor->MATLAB Host Computer' ProdHWDeviceType: 'Intel->x86-64 (Windows64)' TargetIntDivRoundTo: 'Zero' ProdIntDivRoundTo: 'Zero' UseDivisionForNetSlopeComputation: 'off' PurelyIntegerCode: 'off' PortableWordSizes: 'off' SupportNonInlinedSFcns: '' RTWReplacementTypes: '' MaxIdInt8: 'MAX_int8_T' MinIdInt8: 'MIN_int8_T' MaxIdUint8: 'MAX_uint8_T' MaxIdInt16: 'MAX_int16_T' MinIdInt16: 'MIN_int16_T' MaxIdUint16: 'MAX_uint16_T' MaxIdInt32: 'MAX_int32_T' MinIdInt32: 'MIN_int32_T' MaxIdUint32: 'MAX_uint32_T' MaxIdInt64: 'MAX_int64_T' MinIdInt64: 'MIN_int64_T' MaxIdUint64: 'MAX_uint64_T' BooleanTrueId: 'true' BooleanFalseId: 'false' TypeLimitIdReplacementHeaderFile: '' SharedCodeRepository: '' TargetLang: 'C' PreserveExternInFcnDecls: 'on' ImplementImageWithCVMat: 'off' EnableSignedRightShifts: 'on' EnableSignedLeftShifts: 'on' TflName: 'None' TflCheckSum: [2.1946e+09 3.7762e+09 3.7700e+09 3.6906e+09] UtilMemSecPreStatement: '' UtilMemSecPostStatement: '' UtilMemSecComment: '' CodeCoverageChecksum: [3.6498e+09 78774415 2.5508e+09 2.1183e+09] TargetLargestAtomicInteger: 'Char' TargetLargestAtomicFloat: 'None' ProdLargestAtomicInteger: 'Char' ProdLargestAtomicFloat: 'Float' LongLongMode: 'on' ProdLongLongMode: 'off' toolchainOrTMF: 'Microsoft Visual C++ 2017 v15.0 | nmake (64-bit Windows)'
Relate the Shared Utility Checksum to Configuration Parameters
targetInfoStruct hash table from the shared utility
model. Some key-value pairs relate directly to a model property. Other pairs relate to
groups of properties.
The following table describes the key-value pairs.
|Key Names||Model Properties|
|Reserved (internal use only)|
|Reserved (internal use only)|
|Reserved (internal use only)|
|Reserved (internal use only)|