Get Started with C API - MATLAB & Simulink (original) (raw)
Use the C API to monitor and tune generated model elements during the execution of generated model code on the target platform. The C API is an optional programmatic interface that you can add to the code generated from a Simulink® model.
Use the C API:
- through the development of your model, to fine tune values of model elements.
- after deployment of the generated model code, to calibrate the value of model elements in the generated model code in real time, while it is running on the target platform.
C API Background and Prerequisites
To use the C API, you need to be familiar with these concepts.
To learn about other ways to monitor and tune elements in generated model code, see:
- Generate Calibration Files
- Get Code Description of Generated Code
- Create Tunable Calibration Parameter in the Generated Code
- Generate ASAP2 and CDF Calibration Files
C API Technology
C API is a MathWorks® developed technology. It is an additional layer to the primary generated model code. The primary generated model code, generated from the model by theSimulink Coder (or the Embedded Coder®), includes a programmatic interface that your external code uses to invoke the generated code and control its execution. The C API layer provides an additional programmatic interface through which your external code can access the structure and real-time values of model elements. The C API code is written in the same programming language as the primary generated model code. This additional layer provides tools for monitoring and tuning (calibrating) model elements in the generated code in real time, while it is running on the target platform. The C API layer serves as a gateway to accessing elements in the primary code and depends on the primary code. Model elements that are optimized away do not exist in the primary generated code, and are inaccessible through the C API interface.
Instantiation of C API Data Structure Arrays
Once C API is enabled for model model, Simulink Coder (or Embedded Coder) generates two additional files:
- A header file
_`model`__capi.h - A source file
_`model`__capi.c(or_`model`__capi.cpp)
The C API data structures are instantiated in the source file. You do not need to fully understand the instantiation code, but you can examine it to get a general idea about which C API elements were generated. It can also be helpful for debugging purposes. The instantiated C API elements are structure arrays and primitive type arrays. This page provides a high level description of the arrays instantiation. To learn how to write external code that uses these C API structures, see Write External Code to Access Generated C API Code.
The arrays are instantiated statically in the source file. Each model element that is included in the generated C API code has a corresponding entry in one of these arrays. In addition, each array contains a sentinel entry, with all elements set to null values. These are the model element arrays.
| Structure Array Variable | Corresponding Element Type |
|---|---|
| rtBlockSignals | Block output signals |
| rtRootInputs | Output signal of root-level input ports |
| rtRootOutputs | Input signal of root-level output ports |
| rtBlockParameters | Block parameters |
| rtModelParameters | Model parameters |
| rtBlockStates | Model states |
This code is an example of the instantiation of the root-level input ports array:
/* Root Inputs information */
static const rtwCAPI_Signals rtRootInputs[] = {
/* addrMapIndex, sysNum, blockPath,
* signalName, portNumber, dataTypeIndex,
* dimIndex, fxpIndex, sTimeIndex
*/
{ 0, 0, TARGET_STRING("CapiConfigDemo/Inport1"),
TARGET_STRING(""), 1, 0, 0, 0, 0 },
{ 1, 0, TARGET_STRING("CapiConfigDemo/Inport2"),
TARGET_STRING(""), 2, 0, 0, 0, 0 },
{ /* Sentinel entry */
0, 0, (NULL), (NULL), 0, 0, 0, 0, 0
}
};C API General Workflow
There are two major steps in using C API:
- Configure the model to include, in the generated code, C API elements that correspond to the model elements you want to monitor and tune. For more information, see Configure Model to Generate C API Code.
- Write code that interacts with the generated C API elements during the execution of the generated model code on the target platform. For more information, see Write External Code to Access Generated C API Code.
Get Started with C API Example
This example demonstrates how to use the C API to tune parameters while interacting with generated code.
Use these links to see and launch the steps of the example. In this example you:
- Explore Measurable and Tunable Model Elements
- Configure Model to Add C API Signals in Code Generation
- Write Code that Interacts with C API Code
C API Limitations
The C API has these limitations.
- The C API does not support bus structures with bit-fields.
- The C API does not support these values for the
CodeFormatTLC variable:S-FunctionAccelerator_S-Function(for accelerated simulation)
- For ERT-based targets, the C API requires that you enable support for floating-point code.
- Local block output signals are not supported.
- Local Stateflow® parameters are not supported.
- These custom storage class objects are not supported:
- Objects without the
csc_registrationfile - Grouped custom storage classes
- Objects defined by using macros
BitFieldobjectsFileScopeobjects
- Objects without the
- Customized data placement is disabled when you are using the C API. The interface looks for global data declaration in
_`model`_.hand_`model`__private.h, where_model_ is the name of the model that the code is generated from. Declarations placed in any other file by customized data placement result in code that does not compile.