Stack Usage Profiling for Code Generated from Simulink Models
To determine the size of stack memory that is required to run generated code, you can run a software-in-the-loop (SIL) or processor-in-the-loop (PIL) simulation that generates a stack usage profile. The SIL or PIL simulation instruments the generated code and uses the instrumentation to calculate stack usage. When the simulation is complete, you can view a code stack profiling report that shows minimum, average, and maximum memory demand. Using the Simulation Data Inspector, you can observe streamed stack usage information during and after the simulation. The profiles that you generate enable you to observe the effect of compiler optimization and data input on stack usage.
You can generate stack usage profiles by using the top-model or Model block SIL/PIL workflows. Subsystem SIL/PIL workflows do not support stack usage profiling.
Benefits of Dynamic Stack Usage Profiling
Static stack usage analysis has some limitations. For example, it does not consider:
Memory optimization performed by a compiler. For example, variables that are optimized away or stored in registers.
Additional memory that the compiler uses in a function call. Compilers store the address to which the execution returns after the function call.
Memory alignment that the compiler applies.
The dynamic stack usage profiling provided by a SIL or PIL simulation does not have the listed limitations because the simulation calculates the actual memory usage of the compiled code.
Configure Stack Usage Profiling
To run a SIL or PIL simulation that generates stack usage metrics:
In the Simulink® Editor, open your model.
On the Apps tab, click SIL/PIL Manager.
In the Mode section, select SIL/PIL Simulation Only.
In the Prepare section, specify System Under Test and, if required, SIL/PIL Mode. A PIL simulation requires a driver implementation that obtains stack usage data from the target hardware. See Obtain Stack Usage Data From Target Hardware..
To enable stack usage profiling, in the Prepare section:
Open the Settings gallery.
Under Time Profiling, click the Task Profiling button and Functions button off.
Under Coverage, click the Coverage Collection button off.
Under Stack Profiling, click the Stack Profiling button on. This action selects the Measure task stack usage configuration parameter, which provides stack usage measurements for each generated task. The top model setting for the parameter overrides the corresponding setting in referenced models.
Click
, which opens the Configuration Parameters dialog box. On the Data Import/Export pane, clear the Single simulation output check box.
To view streamed stack usage during the simulation, open the Simulation Data Inspector. In the Results section, click
.
In the Run section, click Run SIL/PIL.
In the MATLAB® base workspace, the simulation generates a variable with the default name,
stackProfile
, which stores the stack usage data. You can specify an
alternative name through the Stack workspace variable configuration
parameter.
View Stack Usage Metrics for Tasks and Functions
Suppose you run a SIL simulation of this model:
When the SIL simulation is complete, the code stack profiling report opens. See Code Stack Profiling Report.
To view stack usage metrics in the Code Profile Analyzer:
Click the SIL/PIL tab.
In the Results gallery, under Stack Profiling Results, click Code Profile Analyser. The app displays information in the Stack Memory and Summary panels.
In the Stack Memory panel, the Profiled Tasks view shows stack usage metrics for these generated code sections:
The model initialization function
mStackProfilingRefModel_initialize
.The task represented by the step function
mStackProfilingRefModel_step
.
For each code section, the table provides this information:
Minimum Usage — Minimum stack memory usage in bytes.
Average Usage — Average stack memory usage in bytes
Maximum Usage — Maximum stack memory usage in bytes
Minimum Function-Call Depth — Minimum number of nested function calls.
Maximum Function-Call Depth — Maximum number of nested function calls.
Calls — Number of times that the generated code section is called.
The Profiled Functions view shows the memory demand of each executed function.
For each function, the table provides this information:
Function — Function name in generated code
Memory Usage — Required stack memory in bytes
Calls — Number of times that function is called
To view the stack usage distribution for a task:
In the Profiled Tasks view, click a task row.
In the Results section, click Generate Distribution.
To view the variation of stack usage over the simulation, in the Results section, click Export to SDI.
Stack memory usage for mStackProfilingRefModel_step
fluctuates
between 112 and 64 bytes. The fluctuation occurs because the nested function generated from
the If Action Subsystem block is called by
mStackProfilingRefModel_step
only when the signal
previous_output
has an even
value.
… if ((int32_T)(uint8_T)((int32_T)rtb_previous_output % 2) == 0) { /* Outputs for IfAction SubSystem: '<Root>/If Action Subsystem' incorporates: * ActionPort: '<S1>/Action Port' */ /* Outputs for Atomic SubSystem: '<S1>/Subsystem' */ Subsystem(rtb_previous_output, &rtY.Out1); /* End of Outputs for SubSystem: '<S1>/Subsystem' */ /* End of Outputs for SubSystem: '<Root>/If Action Subsystem' */ } …
To view the call to a function:
In the Profiled Functions view, click the row that contains the function, for example,
mStackProfilingRefModel_step
.In the Results section, click Highlight Code. The code generation report shows the call in the generated code.
To trace the model component from which code is generated, in the Results section, click Open Model.
Compare Stack Usage Against Baseline
You can compare stack usage values from the current simulation against values from a baseline simulation.
On the toolstrip, in the Analysis section, click Comparison.
From the Compare current data against drop-down list, select the workspace variable that contains results from the baseline simulation. You can update the drop-down list by clicking the Refresh list button.
Click the Compare button.
The panel provides these views:
Task Comparison — A percentage comparison of task stack usage values for the two simulations. You also see a comparison for the number of nested, function calls in each task.
Function Comparison — A percentage comparison of function stack usage values for the two simulations. You also see a comparison for the number of calls to each function.
The table cells are colored:
Green if the current execution-time metric is less than the baseline value.
Yellow if the current execution-time metric is greater than the baseline value.
If the workspace variable for the baseline simulation does not contain data for a code
section, the panel displays NaN
.
Summary Panel (Stack Usage)
The Summary panel provides miscellaneous simulation information.
Profiled component — Simulink model that is the source of generated code
Workflow — Type of code execution
Environment — Simulation environment
Word size (bits), Largest atomic integer, and Pointer size (bits) — Values of configuration parameters
ProdWordSize
,ProdLargestAtomicInteger
, andProdBitPerPointer
respectively. Hardware characteristics that indicate how the target compiler views memory and aligns variables.Max stack allowed — Value of
MaxStackUsageAllowed
property in workspace variable that contains stack usage measurements. See Code Stack Profiling Report.Driver type — Driver used to obtain stack usage data from the target hardware. Custom or Generic.
Time created — Date and time when workspace variable with stack usage metrics was created.
Code Stack Profiling Report
You can also view stack usage metrics for the generated code through the HTML report that opens at the end of the simulation.
Note
If you close the report, you can reopen the report. Use one of these actions:
On the SIL/PIL tab, in the Results gallery, under Stack Profiling Results, click Generate Report.
In the Code Profile Analyzer, in the Results section, click Generate Report.
In section 1, the report:
Provides information that indicates how the target compiler views memory and aligns variables.
States whether a target-specific or generic driver obtained stack usage data from the target hardware.
Provides a timestamp for the report.
For each task, section 2 of the report provides this information:
Minimum Stack Usage in bytes –– Minimum stack usage, in bytes.
Average Stack Usage in bytes –– Average stack usage, in bytes.
Maximum Stack Usage in bytes –– Maximum stack usage, in bytes.
Minimum Function-Call Depth –– Minimum number of nested function calls.
Maximum Function-Call Depth –– Maximum number of nested function calls.
Calls –– Number of times that the generated code is called.
The report provides more information through clickable icons. The specified workspace
variable that contains stack usage data, for example, stackProfile
, must
be present in the base workspace.
If you click , you can view the stack usage distribution for the
simulation.
If you click , you can view the variation of stack usage over the
simulation.
For each function, section 3 of the report provides this information:
Memory in bytes –– Stack memory used, in bytes
Calls –– Number of times function is called.
If you click , you can view the function call in the code generation
report.
If you specify a value for Maximum stack size (bytes)
(MaxStackSize
), the report provides Section 4. This section displays
the maximum stack use for each task with reference to the maximum stack size permitted,
which the bar chart displays as a horizontal red line. If the
MaxStackSize
value is much greater than the stack usage of the tasks,
the bar chart does not display the red line. To help your visual analysis of stack usage
requirements, you can use the MaxStackUsageAllowed
property of the
workspace variable to respecify the maximum stack size value. For example:
stackProfile.MaxStackUsageAllowed = 64; report(stackProfile);
Implement Driver to Obtain Stack Usage Data During PIL Simulation
A PIL simulation requires a driver implementation that obtains stack usage data from the target hardware. The driver must return the value of the stack register.
Note
If you do not specify a driver for your target hardware, the PIL simulation tries to use a default generic driver.
When you set up PIL target connectivity, specify the driver through an
subclass. This
code provides an example.rtw.connectivity.Config
classdef overheadConnectivityConfig < rtw.connectivity.Config methods function this = customConnectivityConfig(componentArgs) % Create builder targetApplicationFramework = ... mypil.TargetApplicationFramework(componentArgs); builder = rtw.connectivity.MakefileBuilder(componentArgs, ... targetApplicationFramework, ''); % Create launcher launcher = mypil.Launcher(componentArgs, builder); % Set up communication hostCommunicator = rtw.connectivity.RtIOStreamHostCommunicator(... componentArgs, ... launcher, ... rtiostreamLibTCPIP); % Call super class constructor to register components this@rtw.connectivity.Config(componentArgs,... builder,... launcher,... hostCommunicator); % Specify driver implementation that obtains stack usage % data from the target hardware stackUsageDriver = coder.profile.StackDriver(); stackUsageDriver.PtrDataType = 'uint64'; stackUsageDriver.HeaderFile = 'myHeaderFile.h'; stackUsageDriver.SourceFile = 'mySourceFile.c'; stackUsageDriver.IncludePaths = {'path/To/myFolder1', ... 'path/To/myFolder2', ... 'path/To/myFolder3'}; stackUsageDriver.DriverFunction = 'myDriverFunction'; this.setStackDriver(stackUsageDriver); end end end
For more information about setting up PIL target connectivity, see: