Documentation

Specify Source Code and Dependencies

Specify your external source code file that contains your C functions.

Call C Caller Block and Specify Ports

You can start your custom C code integration into Simulink by typing C Caller in the Simulink canvas. Alternatively, drag a C Caller block from the Library Browser > User-Defined Functions. Double-click the block to open the Block Parameters dialog box to see the names of your functions and port specifications.

Map C Function Arguments to Simulink Ports

You can map C function arguments from your source code to Simulink ports using the Port specification table in the C Caller block and by creating a FunctionPortSpecification object through the command line . In your source code, the header file includes the C function arguments to be connected to Simulink ports.

extern void mean_filter(const unsigned char* src,
                           unsigned char* dst,
                           unsigned int width, unsigned int height,
                           unsigned int filterSize);

Port specification shows the details of your arguments and how they connect to your C Caller block in Simulink.

Name — Specifies the name of input and output arguments. Name is the function argument or parameter name as defined in your C functions from source code. This column is for reference purposes only.

Scope — Specifies how C function arguments map to the Simulink scope. Your arguments have default scopes depending on the function definition and you can change the scopes depending your function definition in the source code.

For an argument passed by pointer, when you have a constant qualifier definition such as const double *u, the argument can only be an input or a parameter. When there is no constant qualifier, the argument is an InputOutput by default, and you can change it to an Input, Output, or Parameter scope. In the case of an Input or Parameter scope, ensure that the C function does not modify the memory pointed by the pointer. If the argument is of an Output scope, every element pointed to by this pointer should be reassigned in every call for the function.

Use the InputOutput port to map an input passed by a pointer in your C functions. Ports created using an InputOutput port have the same name for input and output ports. InputOutput ports enables reuse of buffer for input and output ports. This may optimize the memory use depending on the signal size and the block layout.

To map C function arguments to an InputOutput port, define the variable as a pointer in your function definitions.

extern void mean_filter(unsigned char* src,
                           unsigned int width, unsigned int height,
                           unsigned int filterSize);

Then, select the port specification to the InputOutput scope in the Port Specification table, and assign the resulting function output to the input variable in the custom function.

You can use global variables in your custom code, mapping them to the appropriate Simulink scope. To enable the use of global variables in your model, select Enable global variables as function interfaces from Model Settings > Configuration Parameters > Simulation Target. You can map the global variables to an Input, Output, InputOutput or Global scope on the C Caller block. The availability of the these scopes depend on the use of the global variable in your custom code.

A Global scope enables you to transfer data between custom code and the C Caller block and lets you use the global variable during calculations on the block. Values transferred using Global scope are not visible on the block interface. This table shows example code snippets and their default and available ports.

double data;

void foo(void)
    {
        int temp = data;  
    }

double data;

void bar(void)
    {
        data = 0;
    }

double data;

void foo2(void)
    {
        data = data + 1;
    }

Label — Indicates the label for the corresponding argument in a Simulink block. By default, your argument label is the same as the argument name, unless you change it.

Type — Demonstrates the match between the Simulink data type and the C function argument data type.

Size — Specifies the data dimensions in the argument.

myCCallerConfigObj = get_param(gcb, 'FunctionPortSpecification')

myCCallerConfigObj = 

  FunctionPortSpecification with properties:

        CPrototype:  'real_T add(real_T u1, real_T u2);'
    InputArguments:  [1×2 Simulink.CustomCode.FunctionArgument]
    ReturnArgument:  [1×1 Simulink.CustomCode.FunctionArgument] 
    GlobalArguments: [1×0 Simulink.CustomCode.FunctionArgument]

Create a Custom C Caller Library

You can create a library model to group your C Caller blocks and keep your models organized.

Generate Debug Symbols for Custom Code

To attach an external debugger to the MATLAB process, and debug external C code, generate the debug symbols using:

Simulink.CustomCode.debugSymbols('on')

Turn this setting off using:

Simulink.CustomCode.debugSymbols('off')

Simulate Custom Code in a Separate Process

When simulating a model containing custom C or C++ code, you have the option to run the custom code in a separate process outside of MATLAB. This option may be useful when debugging your custom code. By running in a separate process, problems with the custom code do not cause MATLAB to crash, and you can more easily debug and resolve such problems. Problems could arise due to unexpected exceptions in the custom code or errors in the interface between Simulink and the custom code.

To enable this option, in the model configuration parameters, in the Simulation target pane, select Simulate custom code in a separate process. The option applies to custom C/C++ code integrated into your model using any of these blocks:

For example, this model contains a C Caller block that calls the function adder(), which accesses an object called adderObj. Before calling the function, the object must be created, which can be done by calling initAdder() from the Initialize function of the Simulation Target pane of the model configuration parameters.

static Adder* adderObj = nullptr;

int adder(int increment)
{
    adderObj->add_one(increment);
    return adderObj->get_val();
}

void initAdder()
{
    adderObj = new Adder();
}

If initAdder() is not called before adder(), then adder() attempts to access an uninitialized pointer, which causes a run-time exception. If the Simulate custom code in a separate process parameter is not selected, this exception could cause MATLAB to crash when you simulate the model. However, if the parameter is selected, simulating the model produces an error message within Simulink.

You can then click Open to launch your external debugger and resolve the issue that caused the error.

After the debugger launches, it will restart the simulation and stop at the breakpoints of custom function entries automatically.

Once your custom code is fully debugged, you can unselect Simulate custom code in a separate process for faster simulation time.

Limitations

To test models that include C Caller blocks, see Test Integrated C Code (Simulink Test).