Generating Reentrant C Code from MATLAB Code

About This Tutorial

Learning Objectives

This tutorial shows you how to:

• Generate reentrant code from MATLAB code that uses no persistent or global data

  Note   This example runs on Windows only.

• 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.

Prerequisites

To complete this tutorial, install the required products and set up your C compiler as described in Prerequisites

Required Files

To run the tutorial, copy these files to a local folder. For instructions, see Copying Files Locally.

Back to Top

Copying Files Locally

Copy the tutorial files to a local working folder.

1. Create a local working folder, for example, c:\ecoder\work.

2. Change to the matlabroot\help\toolbox\ecoder\examples folder. At the MATLAB command line, enter:

   cd(fullfile(docroot, 'toolbox', 'ecoder', 'examples'))
   

3. Copy the reentrant_win folder to your local working folder.

   Your work folder now contains the files you need to complete this tutorial.

4. Set your MATLAB current folder to the work folder that contains your files for this tutorial. At the MATLAB command line, enter:

   cd work

   where work is the full path of the work folder containing your files.

Back to Top

About the Example

This example requires libraries that are specific to the Microsoft Windows operating system and, therefore, runs only on Windows platforms. It is a simple, multithreaded example that uses no persistent or global data. Two threads call the MATLAB function matrix_exp with different sets of input data.

 Contents of matrix_exp.m

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, codegen supports dynamic allocation of function variables that are too large for the stack, as well as persistent and global variables. codegen generates a header file, primary_function_name_types.h, which you must include when using the generated code. This header file contains the following structures:

• primary_function_nameStackData

  Contains the user allocated memory. You must pass a pointer to this structure as the first parameter to all functions that use it either directly, because the function uses a field in the structure, or indirectly, because the function passes the structure to a called function.

  If the algorithm uses persistent or global data, the primary_function_nameStackData structure also contains a pointer to the primary_function_namePersistentData structure. Including this pointer means that you have to pass only one parameter to each calling function.

• primary_function_namePersistentData

  If your algorithm uses persistent or global variables, codegen provides a separate structure for them and adds a pointer to this structure to the memory allocation structure. Having a separate structure for persistent and global variables allows you to allocate memory for these variables once and share them with all threads if desired. However, if there is no communication between threads, you can choose to allocate memory for these variables per thread or per application.

Back to Top

Providing a main Function

To call the reentrant code, you must 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 Calling Initialize and Terminate Functions in the MATLAB Coder documentation.

• Calls matrix_exp.

• Calls matrix_exp_terminate.

• Frees the memory used for stack data.

 Contents of main.c

#include <stdio.h>
#include <stdlib.h>
#include <windows.h>
#include "matrix_exp.h"
#include "matrix_exp_initialize.h"
#include "matrix_exp_terminate.h"
#include "rtwtypes.h"
#define NUMELEMENTS (160*160)

typedef struct {
    real_T in[NUMELEMENTS];
    real_T out[NUMELEMENTS];
    matrix_expStackData* spillData;
} IODATA;

/* The thread_function calls the matrix_exp function written in MATLAB */
DWORD WINAPI thread_function(PVOID dummyPtr) {
    IODATA *myIOData = (IODATA*)dummyPtr;
    matrix_exp_initialize();
    matrix_exp(myIOData->spillData, myIOData->in, myIOData->out);
    matrix_exp_terminate();
    return 0;
}

void main() {
  HANDLE thread1, thread2;
  IODATA data1;
  IODATA data2;
  int32_T i;
  
  /*Initializing data for passing to the 2 threads*/
  matrix_expStackData* sd1 = (matrix_expStackData*)calloc(1,sizeof(matrix_expStackData));
  matrix_expStackData* sd2 = (matrix_expStackData*)calloc(1,sizeof(matrix_expStackData));
  
  data1.spillData = sd1;
  data2.spillData = sd2;
  
  for (i=0;i<NUMELEMENTS;i++) {
      data1.in[i] = 1;
      data1.out[i] = 0;
      data2.in[i] = 1.1;
      data2.out[i] = 0;
  }
  
  /*Initializing the 2 threads and passing data to the thread functions*/
  printf("Starting thread 1...\n");
  thread1 = CreateThread(NULL , 0, thread_function, (PVOID) &data1, 0, NULL);
  if (thread1 == NULL){
	     perror( "Thread 1 creation failed.");
		   exit(EXIT_FAILURE);
  	}

  printf("Starting thread 2...\n");
  thread2 = CreateThread(NULL, 0, thread_function, (PVOID) &data2, 0, NULL);
  if (thread2 == NULL){
      perror( "Thread 2 creation failed.");
      exit(EXIT_FAILURE);
  }
  
  /*Wait for both the threads to finish execution*/
  if (WaitForSingleObject(thread1, INFINITE) != WAIT_OBJECT_0){
	     perror( "Thread 1 join failed.");
		  exit(EXIT_FAILURE);
  	}
   
  if (WaitForSingleObject(thread2, INFINITE) != WAIT_OBJECT_0){
		  perror( "Thread 2 join failed.");
		  exit(EXIT_FAILURE);
	  }  
  
  free(sd1);
  free(sd2);
  
  printf("Finished Execution!\n");
  exit(EXIT_SUCCESS);
  }

Back to Top

Configuring Build Parameters

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

1. Create a configuration object.

   e = coder.config('exe', 'ecoder', true);

   This command creates a coder.EmbeddedCodeConfig object which contains all the configuration parameters that the codegen function needs to generate standalone C/C++ static libraries and executables for an embedded target.

2. Enable reentrant code generation.

   e.MultiInstanceCode = true;

Back to Top

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 e.

• main.c to include this file in the compilation.

• -report to create a code generation report.

• -args to specify an example input with the class, size, and complexity.

codegen -config e 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.

Back to Top

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 report, click the C code tab.

3. On this tab, click the link to matrix_exp_types.h.

/*
 * matrix_exp_types.h
 *
 * MATLAB Coder code generation for function 'matrix_exp'
 */
#ifndef __MATRIX_EXP_TYPES_H__
#define __MATRIX_EXP_TYPES_H__

/* Type Definitions */
typedef struct {
    struct {
        real_T F[25600];
        real_T Y[25600];
    } f0;
 } matrix_expStackData;
 
#endif
/* End of code generation (matrix_exp_types.h) */

Back to Top

Running the Code

Call the code, first verifying that the example is running on Windows platforms.

% This example can only be run on Windows platforms
if ~ispc
 error('This example requires Windows-specific libraries and can only be run on 
 Windows.');
end
system('matrix_exp.exe')

The executable runs and reports completion.

Back to Top

Key Points to Remember

• Create a main function that

  • Includes the generated header file, primary_function_name_types.h. This file defines the primary_function_nameStackData 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 primary_function_name_initialize .

  • Calls primary_function_name.

  • Calls primary_function_name_terminate.

  • Frees the memory used for stack data.

• 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.

Back to Top

Learn More

Back to Top

Controlling C Code Style

Tracing Between Generated C Code and MATLAB Code

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit