Debugging C MEX S-Functions

About Debugging C MEX S-Functions

This section provides high-level tips on how to debug C MEX S-functions within the Simulink environment and using third-party software. The following lists highlight some of the more common errors made when writing an S-function. For a more detailed analysis, use the debugger provided with your C compiler.

The examples at the end of this section show how to debug a C MEX S-function during simulation, using third-party software.

• The first example uses the Microsoft^® Visual C++^® .NET (version 7.0) environment.

• The second example debugs an S-function on The Open Group UNIX^® platform.

Refer to your compiler documentation for further information on debugging files.

Back to Top

Debugging C MEX S-Functions in the Simulink Environment

Before you begin, make sure you have a good understanding of how to write C S-functions and the required callback methods. For assistance:

• Read the section Selecting an S-Function Implementation to determine if you implemented your S-function using the most appropriate method.

• Use the S-Function Builder block to generate simple S-functions and study the contents of the source files.

• Inspect the S-function demo models available in sfundemos.mdl. The directory matlabroot/simulink/src contains the S-function source files for these models.

If your S-function is not compiling, first ensure that the mex command is properly configured and your S-function includes all necessary files:

• Run mex -setup to ensure that your compiler is correctly installed.

• Confirm that you are passing all the source files needed by your S-function to the mex command.

• Check that these additional source files are on the MATLAB path.

• Make sure that your S-function includes the simstruc.h header file. If you are accessing legacy code, make sure that any header files needed by that code are also included in your S-function.

• Make sure that your S-function does not include the simstruc_types.h or rtwtypes.h header files. These Simulink and Real-Time Workshop header files are automatically included for you. If you are compiling your S-function as a MEX-file for simulation, including the rtwtypes.h file results in errors.

If the mex command compiles your S-function, but your S-function does not simulate or the simulation produces incorrect results, inspect your S-function's source code to ensure that:

• You are not overwriting important memory

• You are not using any uninitialized variables

The following table describes additional common S-function constructs that can lead to compilation and simulation errors.

set_param(model_name,'TryForcingSFcnDF','on')

matlabroot/simulink/src/sfuntmpl_directfeed.txt

// In mdlInitializeSizes
ssSetInputPortRequiredContiguous(S, 0, 0);
   
// In mdlOutputs, access the inputs using 
InputRealPtrsType uPtrs1 = 
    ssGetInputPortRealSignalPtrs(S,0);   

// In mdlInitializeSizes
ssSetInputPortRequiredContiguous(S, 0, 1);

// In mdlOutputs, access the inputs using
const real_T  *u0  = 
   (const real_T*) ssGetInputPortSignal(S,0); 

/* If ssSetInputPortRequiredContiguous is 0, 
ssGetInputPortSignal returns an invalid pointer.*/ 

Debugging Techniques

You can use the following techniques for additional assistance with debugging your S-function.

• Compile the S-function in debug mode using the -g option for the mex command. This enables additional diagnostics features that are called only when you compile your S-function in debug mode.

• Place ssPrintf statements inside your callback methods to ensure that they are running and that they are executing in the order you expect. Also, use ssPrintf statements to print return values to the MATLAB command prompt to check if your code is producing the expected results.

• Type feature memstats at the MATLAB command prompt to query the memory usage.

• Use the MATLAB File & Directory Comparisons tool, or other text differencing application, to look for textual changes in different versions of your S-function. This can help you locate changes that disabled an S-function that previously compiled and ran. See Comparing Files and Folders in MATLAB Desktop Tools and Development Environment for instructions on how to use the File & Directory Comparisons tool.

• Use settings on the Configuration Parameters dialog box to check for memory problems.

  • Set the Solver data inconsistency diagnostic to warning.

  • Set the Array bounds exceeded diagnostic to warning or error. (See Checking Array Bounds for more information on how to use this diagnostic.)

  • Turn the Signal storage reuse optimization off.

• Separate the S-function's algorithm from its Simulink interface then use the S-Function Builder to generate a new Simulink interface for the algorithm. The S-Function Builder ensures that the interface is implemented in the most consistent method.

Back to Top

Debugging C MEX S-Functions Using Third-Party Software

You can debug and profile the algorithm portion of your S-function using third-party software if you separate the algorithm from the S-function's Simulink interface. You cannot debug and profile the S-function's interface with the Simulink engine because the Simulink interface code does not ship with the product.

You can additionally use third-party software to debug an S-function during simulation, as shown in the following two examples. These examples use the Simulink model sfcndemo_timestwo.mdl and the C MEX S-function timestwo.c.

Debugging C MEX S-Functions Using the Microsoft Visual C++ .NET Environment

Before beginning the example, save the files sfcndemo_timestwo.mdl and timestwo.c into your working directory.

1. Open the Simulink model sfcndemo_timestwo.mdl.

2. Create a debuggable version of the MEX-file by compiling the C-file using the mex command with the -g option.

   mex -g timestwo.c

   The -g option creates the executable timestwo.mexw32 with debugging symbols included. At this point, you may want to simulate the sfcndemo_timestwo model to ensure it runs properly.

3. Without exiting the MATLAB environment, start the Microsoft Development Environment.

4. From the Microsoft Development Environment menu bar, select Tools > Debug Processes.

5. In the Processes dialog box that opens:

   1. Select the MATLAB.exe process in the Available Processes list.

   2. Click Attach.

6. In the Attach to Process dialog box that opens:

   1. Select Native in the list of program types to debug.

   2. Click OK.

   You should now be attached to the MATLAB process.

7. Click Close on the Processes dialog box.

8. From the Microsoft Development Environment File menu, select Open > File. Select the timestwo.c source files from the file browser that opens.

9. Set a breakpoint on the desired line of code by right-clicking on the line and selecting Insert Breakpoint from the context menu. If you have not previously run the model, the breakpoint may show up with a question mark, indicating that the executable is not loaded. Subsequently running the model loads the .mexw32 file and removes the question mark from the breakpoint.

10. Start the simulation from the sfcndemo_timestwo Simulink model. You should be running the S-function in the Microsoft Development Environment and can debug the file within that environment.

Debugging C MEX S-Functions on The Open Group UNIX Platforms

Before beginning the example, save the files sfcndemo_timestwo.mdl and timestwo.c into your working directory.

1. Open the Simulink model sfcndemo_timestwo.mdl.

2. Create a debuggable version of the MEX-file by compiling the C-file using the mex command with the -g option

   mex -g timestwo.c

   The -g option creates the executable timestwo.mexw32 with debugging symbols included. At this point, you may want to simulate the sfcndemo_timestwo model to ensure it runs properly.

3. Exit the MATLAB environment.

4. Start the MATLAB environment in debugging mode using the following command.

   matlab -D<nameOfDebugger>

   The -D flag starts the MATLAB environment within the specified debugger. For example, to use the dbx debugging tool on Sun™ Solaris™ platform, enter the following command.

   matlab -Ddbx

5. Once the debugger has loaded, continue loading the MATLAB environment by typing run at the debugger prompt.

   (dbx) run
   Running: matlab
   (process id 9375)

6. After the MATLAB environment starts, enable debugging by entering the following command at the MATLAB command prompt.

   dbmex on

7. Open the sfcndemo_timestwo Simulink model.

8. Simulate the model. This brings you into the debugger.

9. Set breakpoints in the source code, for example:

   (dbx) stop in mdlOutputs
   (2) stop in `timestwo.mexs64`timestwo.c`mdlOutputs
   (dbx) file timestwo.c

10. Issue the cont command to continue.

    (dbx) cont

11. Use your debugger routines to debug the S-function.

Back to Top

Using S-Functions in Normal Mode Referenced Models

Converting Level-1 C MEX S-Functions to Level-2

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