Define the Interfaces Between the Generated Code and Your Deployment Platform

Step 3 of 8 in Develop and Deploy Embedded Software Components to Platform Services by Using Embedded Coder

• 2
• 3
• 4

To generate code that you can deploy in your target environment, create custom code interface definitions that define how the generated code interacts with the target platform software. By defining the code interfaces separately from your models, you can:

• Generate code that conforms to your software architecture by default by applying the code interface configuration to your models.

• Use the same code interface definitions for multiple models that you intend to deploy to the same target environment, such as models across the model hierarchy.

• Maintain separate configurations for separate target deployment environments and quickly switch your models to use a different code interface configuration.

Later in the workflow, you apply the code interface configuration to your models.

Choose a Code Interface Configuration for Your Deployment Goals

Depending on your deployment goals, you define one of these types of interface configurations:

• Service interface configuration (shown in this example) — The code generator creates an algorithm that you intend to deploy within a larger application. The platform middleware calls the algorithm code and provides the services for the target device. The generated code calls the services according to your definitions in the service interface configuration. To create a service interface configuration, you must use an Embedded Coder^® Dictionary that is stored in a Simulink^® data dictionary.

• Data interface configuration — The code generator creates a program intended to run on the target device. The generated code uses the data interfaces that you define in an Embedded Coder Dictionary. For more information, see Create and Verify Storage Class and Create Data Interface Configuration Programmatically.

• AUTOSAR component configuration — If you have AUTOSAR Blockset, you can generate code for an AUTOSAR software component. For more information, see AUTOSAR Component Configuration (AUTOSAR Blockset).

Each type of interface configuration contains definitions for the different types of code interfaces. Later in the workflow, you map elements of your models to the associated code interface definitions so that the code generator generates the corresponding code.

If your deployment scenario requires more advanced customizations that are not available in the Embedded Coder Dictionary, you can create definitions by using the custom storage class designer. To use these definitions, you must configure and maintain model elements individually. For more information, see Create Storage Classes by Using the Custom Storage Class Designer.

Example Platform Middleware Services

For this example, the platform middleware contains a main function that calls the generated algorithm code and provides services that the generated code calls. In this case, the model should use a service interface configuration for code generation. When you set up the service interface configuration, you define the generated code interfaces to match the interfaces of the platform middleware.

The example main function is in the file EvPowerControllerIntegration.c.

 EvPowertrainControllerIntegration.c

/* EvPowertrainControllerIntegration.c
 *
 *  Example handwritten client code to integrate with generated
 *  code from EvPowertrainController.slx
 *
 * Copyright 2022-2023 The MathWorks, Inc. */
 
#include "EvPowertrainController.h"
 
#include <stddef.h>
#include <stdio.h>
 
extern uint64_T tick;   // Variable used by timer service implementation
 
const size_t nIter = 10;
 
int main(void) {
 
    // Run model initialize function
    printf("\nRunning model initialize function\n");
    EvPowertrainController_initialize_func();

    // Read NVM
    printf("\nReading NVM\n");
    EvPowertrainController_readPowertrainControlNVM_func();
 
    for (size_t k = 0; k < nIter; ++k) {
 
        if (k > 4) {
            // The Regen Braking function runs only when k > 4
            printf("\nRunning Regen Braking function (iteration %llu)\n", k);
            EvPowertrainController_RegenBraking_func();
        }

        // Run Motor Power Management at every iteration
        printf("\nRunning Motor Power Management function (iteration %llu)\n", k);
        EvPowertrainController_MotorPwrMgmt_func();

        // Increment timer tick count
        tick++;
    }
 
    // Write NVM
    printf("\nWriting NVM\n");
    EvPowertrainController_writePowertrainControlNVM_func();

    // Run model terminate function
    printf("\nRunning model terminate function\n");
    EvPowertrainController_terminate_func();
}

The platform middleware provides the services in the file EvControllerServices.c.

 EvControllerServices.c

/* EvControllerServices.c
*
*  Example concrete realization of service interface for
*  the code generated from EvPowertrainController.slx.
*
* Copyright 2024 The MathWorks, Inc. */
  
#include "EvServices.h"
#include <stdio.h>
 
static double DataTransfer_storage[1] = {0};
static double input_storage[9] = {0, 0, 0, 0, 0, 0, 0, 0, 0};
static double NVM_storage[1] = {100};
static double output_storage[2] = {0, 0};
 
/* data transfer services */
const double get_EvPowertrainController_MotorPwrMgmt_func_DataTransferAtRegenBrakingOutport1(void) {
    printf("Service function called: get_EvPowertrainController_MotorPwrMgmt_func_DataTransferAtRegenBrakingOutport1.\n");
    return DataTransfer_storage[0];
}
 
void set_EvPowertrainController_RegenBraking_func_DataTransferAtRegenBrakingOutport1(double aVal) {
    printf("Service function called: set_EvPowertrainController_RegenBraking_func_DataTransferAtRegenBrakingOutport1.\n");
    DataTransfer_storage[0] = aVal;
}
 
/* receiver services */
const double get_EvPowertrainController_MotorPwrMgmt_func_AccCmd_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_MotorPwrMgmt_func_AccCmd_outside_ex.\n");
    return input_storage[0];
}

const double get_EvPowertrainController_RegenBraking_func_DecCmd_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_RegenBraking_func_DecCmd_outside_ex.\n");
    return input_storage[1];
}
 
const double get_EvPowertrainController_RegenBraking_func_VehSpdFdbk_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_RegenBraking_func_VehSpdFdbk_outside_ex.\n");
    return input_storage[2];
}

const double get_EvPowertrainController_MotorPwrMgmt_func_BattSoc_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_MotorPwrMgmt_func_BattSoc_outside_ex.\n");
    return input_storage[3];
}

const double get_EvPowertrainController_RegenBraking_func_BattSoc_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_RegenBraking_func_BattSoc_outside_ex.\n");
    return input_storage[4];
}

const double get_EvPowertrainController_MotorPwrMgmt_func_BattPwr_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_MotorPwrMgmt_func_BattPwr_outside_ex.\n");
    return input_storage[5];
}

const double get_BattCrnt_outside_ex(void) {
    printf("Service function called: get_BattCrnt_outside_ex.\n");
    return input_storage[6];
}

const double get_EvPowertrainController_MotorPwrMgmt_func_MotSpd_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_MotorPwrMgmt_func_MotSpd_outside_ex.\n");
    return input_storage[7];
}

const double get_EvPowertrainController_RegenBraking_func_MotSpd_outside_ex(void) {
    printf("Service function called: double get_EvPowertrainController_RegenBraking_func_MotSpd_outside_ex.\n");
    return input_storage[8];
}

const double get_EvPowertrainController_readPowertrainControlNVM_func_NVMIn_outside_ex(void) {
    printf("Service function called: get_EvPowertrainController_readPowertrainControlNVM_func_NVMIn_outside_ex.\n");
    return NVM_storage[0];
}
 
/* sender services */
void set_EvPowertrainController_MotorPwrMgmt_func_MotTrqCmd_outside_ex(double
  rtu_MotTrqCmd_value) {
    printf("Service function called: set_EvPowertrainController_MotorPwrMgmt_func_MotTrqCmd_outside_ex.\n");
    output_storage[0] = rtu_MotTrqCmd_value;
}

void set_EvPowertrainController_RegenBraking_func_MotTrqCmd_outside_ex(double
  rtu_MotTrqCmd_value) {
    printf("Service function called: set_EvPowertrainController_RegenBraking_func_MotTrqCmd_outside_ex.\n");
    output_storage[0] = rtu_MotTrqCmd_value;
}

void set_EvPowertrainController_RegenBraking_func_BrakeCmd_outside_ex(double
  rtu_BrakeCmd_value) {
    printf("Service function called: set_EvPowertrainController_RegenBraking_func_BrakeCmd_outside_ex.\n");
    output_storage[1] = rtu_BrakeCmd_value;
}

void set_EvPowertrainController_RegenBraking_func_NVMOut_outside_ex(double
  rtu_NVMOut_value) {
    printf("Service function called: set_EvPowertrainController_RegenBraking_func_NVMOut_outside_ex.\n");
    NVM_storage[0] = rtu_NVMOut_value;
}

void set_EvPowertrainController_writePowertrainControlNVM_func_NVMOut_outside_ex(double
  rtu_NVMOut_value) {
    printf("Service function called: set_EvPowertrainController_writePowertrainControlNVM_func_NVMOut_outside_ex.\n");
    NVM_storage[0] = rtu_NVMOut_value;
}

For more information about the platform middleware code that integrates the generated code, see Implement Integration Code.

Create an Embedded Coder Dictionary to Contain Interface Definitions

To contain the service interface configuration, create an Embedded Coder Dictionary that you share with the models from which you want to generate code. In the dictionary, you define the interfaces of the generated functions and the calls to platform-provided services.

1. If you have not already done so, follow the steps in the previous part of the workflow, Configure Basic Code Generation Settings, or run the script.

   openExample("EvPowertrainController")
   ConfigureEvPowertrainModel

2. From the model EvPowertrainController, open the Embedded Coder app. On the C Code tab, click Code Interface > Set up shared Embedded Coder Dictionary.

3. In the Set Up Embedded Coder Dictionary dialog box, select Create Embedded Coder Dictionary. In the Create dictionary text box, enter the name CoderDict.sldd.

   

   Embedded Coder creates this data dictionary to store the Embedded Coder Dictionary. Click Next.

4. Select Service Interface and click Create.

   

   The Embedded Coder Dictionary opens to display the service interface configuration. The configuration contains built-in interface definitions.

5. On the General pane, set the Services Header File name to EvServices.h. This file is the header file for the services provided by the target platform software.

   

Because you used the Set Up Embedded Coder Dictionary dialog, the dictionary is automatically shared with the referenced model BatteryManagementSystem. If you adapt this workflow for your own system, you might need to share the dictionary with other models or otherwise manage the code interface configuration. For more information, see Share Code Interface Configuration Between Models and Manage an Embedded Coder Dictionary.

Define Function Interfaces

To control the naming of generated functions, define function customization templates. The platform scheduler executes the generated code by calling the generated functions. Types of functions include:

• Initialize and terminate functions, which are modeled by Initialize Function and Terminate Function blocks and contain startup and shutdown processing code.

• Periodic and aperiodic functions, which contain the algorithm execution code for the model and execute at a periodic rate or aperiodically in response to events. Because this example uses an export-function model, these functions are represented by function-call subsystems.

For this example, add a custom definition for each type of function interface.

1. In the Service Interface pane, click Initialize and Terminate.

2. In the center pane, under Initialize and Terminate Functions, click Create.

3. Select the new template definition and, on the right pane, set these properties:

   • Name — InitTermFuncs

   • Function Naming Rule — $R$N_func

   • Memory Section — None

   When this definition is applied to the model EvPowertrainController, the generated initialize and terminate functions are named EvPowertrainController_init_func and EvPowertrainController_term_func.

4. In the center pane, under Periodic and Aperiodic Functions, click Create.

5. Select the new template definition and, on the right pane, set these properties:

   • Name — ExecutionFuncs

   • Function Naming Rule — $R$N_func

   • Memory Section — None

   When this definition is applied to the model EvPowertrainController, the generated execution functions are named EvPowertrainController_<export function name>_func.

6. Select the definitions that you added as the dictionary default definitions for functions of the respective categories. In the row for each new entry, click the circle below Dictionary Default.

Define Service Interfaces

Specify how the generated code calls the services of the platform middleware by creating service interface definitions.

For this example, add definitions for the sender, receiver, and data transfer service interfaces.

1. In the Service Interface pane, click Data Receiver.

2. In the center pane, under Data Receiver, click Create.

3. Select the new template definition and, on the right pane, set these properties:

   • Name — DataReceiver

   • Data Communication Method — Outside Execution

   • Function Naming Rule — get_$X$N_outside_ex

   When this definition is applied to the model EvPowertrainController, each generated receiver function follows the naming rule and reads data from another function before the function starts executing.

4. In the center pane, under Data Sender, click Create.

5. Select the new template definition and, on the right pane, set these properties:

   • Name — DataSender

   • Data Communication Method — Outside Execution

   • Function Naming Rule for Value — set_$X$N_outside_ex

   • Function Naming Rule for Value By Reference — getref_$X$N_outside_ex

   When this definition is applied to the model EvPowertrainController, each generated sender function follows the naming rule and sends data to another function before the function starts executing.

6. Select the definitions that you added as the dictionary default definitions for functions of the respective categories. In the row for each new entry, click the circle below Dictionary Default.

7. Make parameters tunable and preserve signals for measurement by selecting default definitions for these categories:

   • Parameter Tuning — ParameterTuningExample1

   • Parameter Argument Tuning — ParameterArgumentTuningExample1

   • Measurement — MeasurementExample1

8. On the Dictionary tab, click Save.

To see the other interface customization options that the Embedded Coder Dictionary provides, click the sections in the Service Interface pane on the left. For more information about defining service interfaces, see Create a Service Interface Configuration and Target Environment Services. For examples of service implementations for the communication methods, see Sample Target Environment Service Implementations of Data Communication Methods.