Specify Clock Resolution Used by Target Environment Clock

Open Live Script

For model functions that include blocks that request absolute or elapsed time values, improve the entry-point code generated for those functions by configuring the model to use a specific clock resolution. Clock resolution is the smallest increment of a clock value. For example, if a clock increments its value once per second, the clock resolution is 1 second.

Benefits of specifying a clock resolution include:

Clock resolution that aligns with target environment clock requirements. For models configured to use a service code interface, specifying a clock resolution results in code that reads time values more accurately.
Decoupling of the clock resolution and the solver properties that Simulink uses during simulation, such as the fixed-step size and sample times. The decoupling enables you to generate code that aligns with the target environment clock resolution and produces more accurate results.
Influencing the data type that Simulink and the code generator use to represent time values. For example, in normal, accelerator, and rapid accelerator modes, Simulink uses the specified clock resolution to deduce fixed-point data types, which produces fixed-point simulation and generated code execution output that match.
Portability of models between code interface configurations. You can attach a model that has a specified clock resolution to a shared Embedded Coder Dictionary that defines a data or service code interface configuration.
Generated code that is easier to read.

Specify Clock Resolution

To specify a clock resolution for the code generator to apply for a model, configure the model with these model configuration parameter settings:

Set System target file (SystemTargetFile) to ert.tlc.
Set solver parameter Type (SolverType) to Fixed-step.
Set Clock resolution (ClockResolution) to a scalar value of type double, which represents the clock resolution in seconds.

If the model includes periodic functions, the clock resolution that you specify must divide the sample times used by the periodic functions with no remainder. For example, if a model includes periodic functions that use sample times 1, 0.2, and 0.1, then 0.05 is a valid clock resolution setting, but 0.03 is not valid. If you must specify a clock resolution that is not a divisor of the sample times, change the offending sample time.

You can specify a clock resolution for components and subcomponents in a model hierarchy. The clock resolution settings for models across the hierarchy must match. For models configured to use a service interface, the code generator checks for clock resolution consistency among corresponding entry-point functions generated for models across the model hierarchy. If the clock resolution settings are not consistent, the code generator returns an error.

How Code Generator Uses Specified Clock Resolution

How the code generator uses a specified clock resolution depends on the model code interface configuration. For models configured to use a data code interface, a specified clock resolution influences how the code generator represents the clock tick in the generated code. The clock tick is the increment of a processor clock. For models that you configure with a service code interface, a specified clock resolution influences timer service interface calls in the code.

For a model configured to use a service code interface, the code generator checks the value of the related Application lifespan parameter. Timer service interfaces support 32-but clock tick values. If the Application lifespan parameter setting is large enough to result in a clock tick that cannot be stored as a 32-bit value, then an overflow condition results and the code generator returns and error.

For aperiodic functions that are driven by an S-function that specifies the SS_OPTION_ASYNCHRONOUS option and a clock resolution, the clock resolution that the S-function specifies overrides the setting of the Clock resolution parameter.

For a model that uses a service code interface, when you specify a clock resolution, the code generator facilitates implementation of the timer service functions that run in the target environment and are called by the generated entry-point functions by including the clock resolution in two places:

In the Timer Service Interface section of the Code Interface Report. See Analyze Generated Service Code Interface Report.
As metadata in the generated code descriptor file codedescriptor.dmr. You can access the metadata by using the code descriptor programming interface. See Get Metadata About Service Interface.

If you choose not to specify a clock resolution, the code generator uses these default values for the clock resolution:

Model fixed-step size (fundamental sample time), for aperiodic functions
Function sample time, for periodic functions

Suppose a model includes a periodic function and an aperiodic function, both of which use a block that requests absolute time from a target environment clock. The fixed-step size (fundamental sample time) configured for the model is 1 second. The sample time configured for the periodic function is 4 seconds. The model is configured to use a service code interface that applies the during-execution data communication method.

For the preceding scenario, the figure below shows the periodic and aperiodic functions requesting the absolute time value at time A. The first row shows time for the Simulink scheduling clock. The second row shows the timing for function requests based on inherited clock resolution behavior. The third row shows the timing for function requests based on a specified scalar clock resolution value.

The horizontal arrows represent time (t).
The spacing between tick marks along the horizontal arrows represents the sample time/rate (r).
The blue boxes above the horizontal arrows represent execution time of the function.
The curved arrows represent function requests for the absolute time value at time A.

When using the inherited clock resolution behavior (with Clock resolution set to -1), you can get time values that are more accurate by using aperiodic functions rather than periodic functions. For this example:

Clock resolution behavior varies whether a function is periodic or aperiodic.
With a sample rate of 4 seconds, the periodic function requests the absolute time at 0 seconds.
Based on the model fixed-step size of 1 second, the aperiodic function requests the absolute time at 1 second.
Because the time that elapses between the aperiodic function request and time A is less than that of the periodic function, the time value received by the aperiodic function is more accurate than the value received by the periodic function.

You can get time values that are even more accurate by specifying a clock resolution as a scalar value. As the figure shows:

If you set the Clock resolution parameter to 0.5, the periodic and aperiodic functions request the absolute time at 1.5 seconds.
Because the time that elapses between the function requests and time A is less than that of the requests when the clock resolution is inherited, the time value received by the functions is more accurate.

Improve Accuracy of Time Values Read by Generated Entry-Point Functions

This example shows that for a model that is configured to use a service code interface, you can improve the accuracy of the time values read by generated entry-point functions by configuring the model with a specific clock resolution. The aperiodic function Integrator in example model ComponentDeploymentFcn includes the Discrete Time Integrator block, which requests the clock tick. Model configuration parameter Fixed-step size (fundamental sample time) is set to auto.

Generate and inspect the code for the model with the Clock resolution parameter set to the default value -1. In this case, the code generator initializes the clock resolution based on scheduling properties for the model style and the type of entry-point function.

Open example model ComponentDeploymentFcn.

open_system("ComponentDeploymentFcn.slx");

Use the default clock resolution to generate code, then inspect the code.

Open the Embedded Coder app.
Configure the Integrator function to use a timer service interface that is configured for during-execution communication. In the Code Mappings Editor – C, on the Functions tab, select the row for function Exported Funciton:Aperiodic. Click the pencil button . In the dialog box that appears, set the Timer Service property to get_tick_during. Save the model.
In the toolstrip, in the Modeling tab, click Modeling Settings.
In the Configuration Parameters dialog box, search for and select the Clock resolution parameter. The parameter is set to the default value -1. Close the dialog box.
Generate code.
In the code generation report, select the Code Interface Report and navigate to the Timer Service Interfaces section. The report shows that the clock resolution is set to 1 second.
In the generated file ComponentDeployentFcn.c, inspect the code for entry-point function cd_integrator. The code generator uses the clock resolution to calculate the integer value in the assignment statement for variable tmp. The value 1.25 is the product of the clock resolution (1) and the gain value specified for the Discrete Time Integrator block (1.25) and is the frequency at which the function requests the elapsed time.

tmp = 1.25 * (real_T)Integrator_ELAPS_T;

Configure the model with a clock resolution of 0.5. Then, generate and reinspect the code.

Set model configuration parameter Clock resolution to 0.5.
Generate code.
Check that the Code Interface Report shows that the clock resolution is set to 0.5 seconds.
In the generated file ComponentDeployentFcn.c, reinspect the code for entry-point function cd_integrator. In this case, the code generator uses the specified clock resolution 0.5 to calculate the integer value in the assignment statement for variable tmp. The value 0.625 is the product of the clock resolution (0.5) and the gain value specified for the Discrete Time Integrator block (1.25). The generated code calls the timer service more frequently, which results in the function reading time values that are more accurate.

tmp = 0.625 * (real_T)Integrator_ELAPS_T;

For more information about configuring timer service interfaces for models configured to use a service interface configuration, see Timer Service Interfaces. For information about configuring a model that uses a data code interface, see Data Interfaces.