Deploy Single-Rate, Rate-Based Component Configured for C Service Interface Code Generation

Since R2022b

This example shows how to develop a single-rate model as a component that includes service interface support for interacting with target platform software. In this example you:

Assess project requirements.
Define the service code interface configuration in the coder dictionary.
Design the component model.
Configure the component model interfaces for code generation.
Assess component model readiness for code generation.
Generate and inspect the generated component code.
Test the generated service interface code by using a software-in-the-loop (SIL) or processor-in-the-loop (PIL).
Get meta-information about the generated code interface for integration with target platform software.
Integrate generated component code with target environment code.

Assess Project Requirements

This example assumes these component and target platform requirements.

Component Description and Requirements

The component model must:

Favor memory optimization over data freshness when communicating data.
Include an initialize function that reads a value from nonvolatile memory and uses that value to initialize a state variable.
Include a component algorithm that receives the value of the state variable from the initialize function, increments the value by one, and applies a gain value, which is tunable during execution. The algorithm gets called every 1 second and maintains the most recent value of the state variable.
Include a terminate function that writes the output of the integrator function to nonvolatile memory after the function stops executing.
Make the state variable accessible for monitoring during execution.

Target Platform Requirements

The target platform for this example project has these requirements:

To initiate component initialization, the target platform function scheduler expects to call entry-point function CD_initialize with no arguments.
To execute the component algorithm, the target platform function scheduler expects to call entry-point function CD_accumulator with no arguments.
To complete component termination, the target platform function scheduler expects to call entry-point function CD_terminate with no arguments.
The component reads from and writes to target platform nonvolatile memory.
The platform receiver service function is named get_CD_accumulator_InBus_u and uses outside-execution data communication. For more information, see Data Communication Methods.
The platform sender service function is named getref_CD_accumulator_OutBus_y and uses outside-execution data communication.
The variable for the tunable gain value applied by the accumulator function is named CD_tunable.k.
The variable that represents the delay state value is named CD_measured.delay.

Define Service Code Interface Configuration

You address the target platform requirements by defining a service code interface configuration in a shared Embedded Coder Dictionary. For this example, the requirements are defined in the dictionary file ComponentDeploymentCoderDictionary.sldd, which is configured for the example model.

Open example component model ComponentDeploymentRate.

open_system('ComponentDeploymentRate');

Open the Embedded Coder Dictionary (ComponentDeploymentCoderdictionary.sldd), which is configure for the model.

Open the Embedded Coder app.
In the toolstrip, under Code interface, select Embedded Coder Dictionary (Shared). The Embedded Coder Dictionary configured for the example model opens. You can create a coder dictionary in the Model Explorer (click File > New > Embedded Coder Dictionary) or in the model Configuration Parameters dialog box (click Set up to the right of the Shared coder dictionary parameter).
Under Service Interface, select Receiver. The Embedded Coder Dictionary shows content in three panes. Use the left pane to navigate through the dictionary configurations. The center pane lists the interfaces that are defined in a code interface configuration for the item you select in the navigation pane. From the center pane you can create and delete interfaces and specify a default interface. The right pane shows the property settings for the interface selected in the center pane. The Pseudocode Preview updates as you change property settings.

In the dictionary, browse through the interface settings. Check that the settings align with the requirements noted in Target Platform Requirements.

Based on requirements listed in Assess Project Requirements, the dictionary defines these relevant interfaces:

Initialize and terminate callable entry-point function interface InitTermInterface, which specifies naming rule CD_$N, where $N is initialize or terminate, depending on the type of function generated.
Periodic and aperiodic callable entry-point function interface PeriodicAperiodicInterface, which specifies naming rule CD_$N, where $N is the name of the function-call inport block. Later, you override the default naming in the code mappings.
Receiver service interface ReceiverOutsideExe specifies outside-execution data communication and naming rule get_$X$N, where $X is the name of the callable function and $N is the name of the receiver port for the receive operation.
Sender service interface SenderOutsideExe specifies outside-execution data communication and naming rules set_$X$N and getref_$X$N for the by value and by reference functions, where $X is the name of the callable function and $N is the name of the sender port for the send operation.
Parameter tuning service interface ParameterTuningService applies storage class TunableStruct to data elements. To align with the platform requirements for naming tunable parameters, property Type Name is set to CD_tunable_T$M and property Instance Name is set to CD_tunable.
Measurement service interface, MeasurementService, applies storage class MeasurementStruct. To align with the platform requirements for naming state data, property Type Name is set to CD_measured_T$M and property Instance Name is set to CD_measured.

The during-execution and direct-access receiver and sender service interfaces are defined so that you can explore differences in the generated code for the different data communication methods.

Later, in Configure Component Model Interface for Code Generation, you map elements of the example model to interfaces defined by the service interface configuration in the dictionary.

For more information about defining code interface configurations, see Code Interface Definitions and Embedded Coder Dictionary.

Design Component Model

The design of example component model ComponentDeploymentRate reflects the requirements listed in Assess Project Requirements.

The timing legend for the model identifies three callable functions: functions Init and Term and a discrete periodic function. To open the timing legend, on the Debug tab, click Information Overlays > Timing Legend.

The component algorithm receives the value of the state variable from the initialize function, increments the value by one, and applies a gain value, which is tunable during execution. The algorithm gets called every 1 second and maintains the most recent value of the state variable. See cgsl_0401: Modeling styles for component deployment.
The Initialize Function block represents a function that initializes a state variable x with a value read from nonvolatile memory before the algorithm executes. See cgsl_0404: Model startup and shutdown events by using Initialize Function and Terminate Function blocks for component deployment and cgsl_0411: Access nonvolatile memory by using Initialize Function and Terminate Function blocks.

The In Bus Element block InBus.NVM, which feeds the initialize function, represents a call to the platform service that reads values from nonvolatile memory. See cgsl_0402: Signal interfaces for component deployment and cgsl_0405: Data receive for component deployment.
The inport for the model algorithm, InBus.u, represents a call to the platform receiver service for reading the input value from the target environment. See cgsl_0402: Signal interfaces for component deployment and cgsl_0405: Data receive for component deployment.
The outport of the algorithm represents a call to the platform sender service for writing the output value of the Gain block. See cgsl_0402: Signal interfaces for component deployment and cgsl_0406: Data send for component deployment.
The Terminate Function block represents the function that writes the output of the integration to nonvolatile memory after the component stops executing. See cgsl_0404: Model startup and shutdown events by using Initialize Function and Terminate Function blocks for component deployment and cgsl_0411: Access nonvolatile memory by using Initialize Function and Terminate Function blocks.

The outport of the terminate function represents a call to the platform service that writes values to nonvolatile memory. See cgsl_0402: Signal interfaces for component deployment and cgsl_0406: Data send for component deployment.

For more information about modeling guidelines that can help you develop and deploy component models that use a service code interface, see Modeling Guidelines for Generated Code.

Configure Component Model Interface for Code Generation

For the code generator to produce interface code that aligns with the target environment requirements, there needs to be a mapping between the interface elements in the model and code interfaces. A model can be associated with one of two types of code interfaces: data interface or service interface. The code generator determines the type of code interface to apply automatically based on this information:

Modeling styles and patterns used in the model
Embedded Coder app Output selection
Type and contents of the Embedded Coder Dictionary associated with the model

For this example, the code generator applies a service interface because the model is configured to a shared Embedded Coder Dictionary that defines a service interface configuration. The code generator uses the configured dictionary to establish default mappings that you can view and, in some cases, change by using the Code Mappings Editor or code mappings programming interface.

To open the Code Mappings editor and explore the interface settings, in the toolstrip, under Code Interface, select Component Interface.

For elements for which the default interface aligns with the requirements, you do not need to make changes. Depending on your model, your code generation goals, and available interfaces, you might need to make some adjustments.

For this example, to meet the code interface requirements listed in Assess Project Requirements, these adjustments were made:

On the Functions tab, the default function customization template for the periodic algorithm function produces function name CD_Periodic. To align with target platform requirements for this function, the code mapping overrides the default function name, by specifying the function name CD_accumulator.
On the Signals/States tab, a code identifier was specified for the state associated with delay. To see the identifier setting for the state, select the row for the state and click the pencil icon. In the dialog box that appears, see the value specified for the Identifier property, delay. The identifier informs the code generator how to represent the corresponding variable in the generated code.

In the Code Mappings editor, you can change the interfaces for the sender and receiver services by clicking the corresponding tab and, in the service column, selecting an alternative service. The default interfaces use the outside-execution data communication method. Alternative interfaces use during-execution and direct-access data communication. Consider changing the interfaces to view differences in the generated code. If you choose to change the interfaces, for each service called along the data path of a signal, set the interfaces such that they apply the same data communication method.

For guidance on setting up a model to use a service interface configuration, see cgsl_0414: Configure service interface for component model. For more information about model code mappings for service interfaces, see C Service Interfaces and Code Mappings Editor – C.

Assess Component Model Readiness for Code Generation

Run the Simulink Model Advisor to confirm that the component model passes component modeling guideline checks.

In the Embedded Coder app, select C/C++ Code Advisor.
In the System Selector dialog box, select ComponentDeploymentFcn. Click Ok.
In the Code Generation Advisor dialog box, in the left pane, select Model Advisor.
In the Model Advisor dialog box, in the left pane, expand By Product and Embedded Coder.
Select the checks Check modeling style for component deployment, Check signal interfaces, and Check configuration for component deployment.
Run the selected checks.

If the checks do not pass, use the information provided to correct the conditions reported.

For more information, see Modeling Guidelines for Generated Code and Model Readiness for Code Generation.

Generate and Inspect Generated Component Code

In the toolstrip, click Generate Code. From the component model, the code generator creates the folder ComponentDeploymentRate_ert_rtw in the current working folder and places source code files in that folder. The generated code is in two primary files: header file ComponentDeploymentRate.h and source code file ComponentDeploymentRate.c. Model data and entry-point functions are accessible to a caller by including the header file.

The code generator also produces an interface header file, which by default the code generator names services.h. This file includes declarations for platform service interface functions called by the component code.

To inspect the generated code, use the generated Code Interface Report or, in the Embedded Coder app, use the Code view. The report is helpful for verifying that the generated interface code aligns with the target platform requirements.

For each callable entry-point function, the Code Interface Report provides:

Function prototype
Description
Header file name
Information about platform services called, such as prototypes and data communication method used

For each platform service called, the report provides:

Function prototypes
Data communication method used
Callable functions that call the service

For more information, see Analyze Generated Service Code Interface Report.

Header File

Header file ComponentDeploymentRate.h includes interface header file services.h and declares:

Structure for representing measurable state data
Structure for representing tunable parameters
Callable entry-point functions

#include"ComponentDeploymentRate_types.h"
#include "services.h"

typedef struct {
  real_T delay[10];
} CD_measured_T;

typedef struct {
  real_T k;
} CD_tunable_T;

extern void CD_initialize(void);
extern void CD_accumulator(void);
extern void CD_terminate(void);
extern CD_measured_T CD_measured;
extern CD_tunable_T CD_tunable;

Source Code File

Generate source code file ComponentDeploymentRate.c shows the code for the functions represented in the component model:

Accumulator function, for each element of the bus signal, calls the receiver service function get_CD_accumulator_Inbus_u() to read the value of the state variable, increments the value by one, applies the delay and gain value, and calls the sender service function getref_CD_accumulator_OutBus_y to send the results.
Initialize function calls the receive service function get_CD_initialize_InBus_NVM to initialize state data that is read from nonvolatile memory.
Terminate function calls the sender service function getref_CD_terminate_OutBus_NVM to write the output of the accumulator algorithm to memory.

#include "services.h"
#include "rtwtypes.h"
#include <string.h>
#include "ComponentDeploymentRate.h"

CD_measured_T CD_measured;
CD_tunable_T CD_tunable = {

  0.0
};

void CD_accumulator(void)
{
  int32_T i;
  for (i = 0; i < 10; i++) {
    CD_measured.delay[i] += (get_CD_accumulator_InBus_u())[i];
    (getref_CD_accumulator_OutBus_y())[i] = CD_tunable.k * CD_measured.delay[i]; 
  }
}

void CD_initialize(void)
{
  memcpy(&CD_measured.delay[0], &(get_CD_initialize_InBus_NVM())[0], (uint32_T)
         (10U * sizeof(real_T)));
}

void CD_terminate(void)
{
  memcpy(&(getref_CD_terminate_OutBus_NVM())[0], &CD_measured.delay[0], (uint32_T)
         (10U * sizeof(real_T)));
}

Services Header File

The services header file services.h declares prototypes for calling receiver and sender services that run as platform software in a target environment.

/* receiver services */
extern const real_T * get_CD_accumulator_InBus_u(void);
extern const real_T * get_CD_initialize_InBus_NVM(void);

/* sender services */
extern real_T * getref_CD_accumulator_OutBus_y(void);
extern real_T * getref_CD_terminate_OutBus_NVM(void);

Test Generated Service Interface Code by Using SIL and PIL Simulations

Consider using a software-in-the-loop (SIL) and processor-in-the-loop (PIL) simulations to verify the generated code. A SIL simulation compiles and runs the generated code on your development computer. A PIL simulation compiles and runs the generated code on a target computer. During a SIL and PIL simulations, you can collect code coverage and execution-time metrics for the generated code. For example, you can use the SIL simulation results to check for numerical equivalence between a normal mode simulation and the SIL simulation.

To test numeric equivalence between the model and generated code:

Run a normal mode simulation and capture the results.
Run a SIL or PIL simulation and capture the results.
Compare the results from steps 1 and 2.

To run SIL and PIL simulations on the example model, you can use the example test harness model ComponentDeploymentRateTestHarness.slx and data file ComponentDeploymentBus.mat.

open_system('ComponentDeploymentRateHarness');

For more information, see Software-in-the-Loop Simulation and Processor-in-the-Loop Simulation.

Get Meta-Information About Generated Code Interface for Integration

By default, the code generator creates a code descriptor file (codedescriptor.dmr) in the build folder. That file contains meta-information about the generated code, including:

Data interfaces (inports, outports, parameters, datastores, and internal data)
Function interfaces (initialize, output, update, and terminate)
Execution information for the data and function interfaces, such as timing requirements
Model hierarchy information and information for referenced models

You can use the code descriptor programming interface to get access to the contents of the code descriptor file and use the results to confirm that generated interfaces meet integration requirements. You can also use the programming interface to provide input to tools that generate interfaces for target platform services.

For more information, see Get Code Description of Generated Code and coder.codedescriptor.CodeDescriptor class.

Integrate Generated Component Code with Target Environment Code

To integrate the generated component code with a main function and other target environment code, you must:

Match the data and function interfaces of the generated code with other interfaces of existing system code.
Connect input data.
Connect output data.
Access other data, such as block state values, local parameters, and time.

The model used in this example is designed and configured such that the generated code aligns with the code interfaces of the target environment.

The target environment software calls the generated entry-point functions, which provide input signal data and scheduling information.
The generated algorithm computes output data that the calling environment uses.
The set of input and output data and the data access mechanisms constitute the interfaces of the entry-point functions.

In a model, root-level inports and outports represent the primary inputs and outputs of the component algorithm. By default, the code generator aggregates this input and output data into standard structures.

You can generate code for a component model and compile a component model library by clearing model configuration parameter Generate code only and initiating a model build. If code for the component model is already generated, you can build a component model library by using the codebuild command with the path codeGenerationFolder/modelBuildFolder/services/lib. You can link the generated component model library with a main function and other target environment code to create an executable program.

For the component model library, you can also create a:

CMake configuration (CMakeLists.txt) file by using the codebuild function
ZIP file by setting model configuration parameter Package code and artifacts and using the packNGo function

For more information, see Manage Build Process Folders, Approaches for Building Code Generated from Simulink Models, Configure CMake Build Process, Compile Code in Another Development Environment, and Deploy Component Algorithm as Component Model Library by Using CMake.

For examples, see Configure Generated Code According to Interface Control Document Specifications and Integrate External Application Code with Code Generated from PID Controller.

For more information, see Deployment, Integration, and Supported Hardware.