Generate Reentrant C Code from MATLAB Code - MATLAB & Simulink (original) (raw)

About This Tutorial

Learning Objectives

This tutorial shows you how to:

• Generate reentrant code from MATLAB® code that does not use persistent or global data.
• Automatically generate C code from your MATLAB code.
• Define function input properties at the command line.
• Specify code generation properties.
• Generate a code generation report that you can use to view and debug your MATLAB code.

Note

This example requires libraries that are specific to the Microsoft® Windows® operating system and, therefore, runs only on Windows platforms.

Prerequisites

To complete this example, install the following products:

• MATLAB
• MATLAB Coder™
• C compiler
  MATLAB Coder locates and uses a supported installed compiler. For the current list of supported compilers, see Supported and Compatible Compilers on the MathWorks® website.
  You can use mex -setup to change the default compiler. See Change Default Compiler.

Required Files

About the Example

This example is a simple, multithreaded example that does not use persistent or global data. Two threads call the MATLAB function matrix_exp with different sets of input data.

In your current working folder, create a file matrix_exp.m that contains this code:

function Y = matrix_exp(X) %#codegen % % The function matrix_exp computes matrix exponential of % the input matrix using Taylor series and returns the % computed output. E = zeros(size(X)); F = eye(size(X)); k = 1; while norm(E+F-E,1) > 0 E = E + F; F = X*F/k; k = k+1; end Y = E;

When you generate reusable, reentrant code, MATLAB Coder supports dynamic allocation of:

• Function variables that are too large for the stack
• Persistent variables
• Global variables

MATLAB Coder generates a header file, _primaryfunctionname_ _types.h, that you must include when using the generated code. This header file contains the following structures:

• _primaryfunctionname_ StackData
  Contains the user allocated memory. Pass a pointer to this structure as the first parameter to functions that use it:
  • Directly (the function uses a field in the structure)
  • Indirectly (the function passes the structure to a called function)
    If the algorithm uses persistent or global data, the _primaryfunctionname_ StackData structure also contains a pointer to the _primaryfunctionname_ PersistentData structure. If you include this pointer, you have to pass only one parameter to each calling function.
• _primaryfunctionname_ PersistentData
  If your algorithm uses persistent or global variables, MATLAB Coder provides a separate structure for them. The memory allocation structure contains a pointer to this persistent data structure. Because you have a separate structure for persistent and global variables, you can allocate memory for these variables once and share them with all threads. However, if the threads do not communicate, you can allocate memory for these variables per thread.

Providing a C main Function

To call the reentrant code, provide a main function that:

• Includes the generated header file matrix_exp.h. This file includes the generated header file, matrix_exp_types.h.
• For each thread, allocates memory for stack data.
• Calls the matrix_exp_initialize housekeeping function. For more information, see Deploy Generated Code.
• Calls matrix_exp.
• Calls matrix_exp_terminate.
• Frees up the for stack data memory.

In your current working folder, create a file main.c that contains this code:

Configuring Build Parameters

You can enable generation of reentrant code using a code generation configuration object.

1. Create a configuration object.
   cfg = coder.config('exe');
2. Enable reentrant code generation.
   cfg.MultiInstanceCode = true;

Generating the C Code

Call the codegen function to generate C code, with the following options:

• -config to pass in the code generation configuration object cfg.
• main.c to include this file in the compilation.
• -report to create a code generation report.
• -args to specify the class, size, and complexity of input arguments using example data.

codegen -config cfg main.c -report matrix_exp.m -args ones(160,160)

codegen generates a C executable, matrix_exp.exe, in the current folder and C code in the /codegen/exe/matrix_exp subfolder. Because you selected report generation, codegen provides a link to the report.

Viewing the Generated C Code

codegen generates a header file matrix_exp_types.h, which defines the matrix_expStackData global structure. This structure contains local variables that are too large to fit on the stack.

To view this header file:

1. Click the View report link to open the code generation report.
2. In the list of generated files, clickmatrix_exp_types.h.

Running the Code

Verify that the example is running on Windows platforms and call the code.

The executable runs and reports completion.

Key Points to Remember

• Create a main function that:
  • Includes the generated header file, _primaryfunctionname_ _types.h. This file defines the _primaryfunctionname_StackData global structure. This structure contains local variables that are too large to fit on the stack.
  • For each thread, allocates memory for stack data.
  • Calls _primaryfunctionname__initialize.
  • Calls _primaryfunctionname_.
  • Calls _primaryfunctionname__terminate.
  • Frees the stack data memory.
• Use the -config option to pass the code generation configuration object to the codegen function.
• Use the -args option to specify input parameters at the command line.
• Use the -report option to create a code generation report.

Learn More