How MATLAB Coder Partitions Generated Code - MATLAB & Simulink (original) (raw)

Partitioning Generated Files

By default, during code generation, MATLAB® Coder™ partitions the code to match your MATLAB file structure. This one-to-one mapping lets you easily correlate your files generated in C/C++ with the compiled MATLAB code. MATLAB Coder cannot produce the same one-to-one correspondence for MATLAB functions that are inlined in generated code (see File Partitioning and Inlining).

Alternatively, you can select to generate all C/C++ functions into a single file. For more information, see How to Select the File Partitioning Method. This option facilitates integrating your code with existing embedded software.

How to Select the File Partitioning Method

Using the MATLAB Coder App

1. To open the Generate dialog box, on theGenerate Code page, click theGenerate arrow .
2. Click More Settings.
3. On the Code Appearance tab, set the Generated file partitioning method to Generate one file for each MATLAB file or Generate all functions into a single file.

At the Command Line

Use the codegen configuration objectFilePartitionMethod option. For example, to compile the function foo that has no inputs and generate one C/C++ file for each MATLAB function:

1. Create a MEX configuration object and set theFilePartitionMethod option:
   mexcfg = coder.config('mex');
   mexcfg.FilePartitionMethod = 'MapMFileToCFile';
2. Using the -config option, pass the configuration object tocodegen:
   codegen -config mexcfg -O disable:inline foo
   % Disable inlining to generate one C/C++ file for each MATLAB function

Partitioning Generated Files with One C/C++ File Per MATLAB File

By default, for MATLAB functions that are not inlined, MATLAB Coder generates one C/C++ file for each MATLAB file. In this case, MATLAB Coder partitions generated C/C++ code so that it corresponds to your MATLAB files.

How MATLAB Coder Partitions Entry-Point MATLAB Functions

For each entry-point (top-level) MATLAB function, MATLAB Coder generates one C/C++ source, header, and object file with the same name as the MATLAB file.

For example, suppose you define a simple function foo that calls the function identity. The source filefoo.m contains the following code:

function y = foo(u,v) %#codegen s = single(u); d = double(v); y = double(identity(s)) + identity(d);

Here is the code for identity.m :

function y = identity(u) %#codegen y = u;

In the MATLAB Coder app, to generate a C static library for foo.m:

1. Define the inputs u and v. For more information, see Specify Types of Entry-Point Inputs Using the App.
2. To open the Generate dialog box, on theGenerate Code page, click theGenerate arrow .
3. Set the Build type to Static Library
4. Click More Settings.
5. On the All Settings tab, under Function Inlining, set the Inline threshold parameter to 0
6. Click Close
7. To generate the library, click Generate.

To generate a C static library for foo.m, at the command line, enter:

codegen -config:lib -O disable:inline foo -args {0, 0} % Use the -args option to specify that u and v are both % real, scalar doubles

MATLAB Coder generates source, header, and object files for foo and identity in your output folder.

How MATLAB Coder Partitions Local Functions

For each local function, MATLAB Coder generates code in the same C/C++ file as the calling function. For example, suppose you define a function foo that calls a local functionidentity:

function y = foo(u,v) %#codegen s = single(u); d = double(v); y = double(identity(s)) + identity(d);

function y = identity(u) y = u;

To generate a C++ library, before generating code, select a C++ compiler and set C++ as your target language. For example, at the command line:

1. Select C++ as your target language:
   cfg = coder.config('lib')
   cfg.TargetLang='C++'
2. Generate the C++ library:
   codegen -config cfg foo -args {0, 0}
   % Use the -args option to specify that u and v are both
   % real, scalar doubles
   In the primary function foo, MATLAB Coder inlines the code for the identity local function.
   
   Note
   If you specify C++, MATLAB Coder wraps the C code into.cpp files so that you can use aC++ compiler and interface with externalC++ applications.
   Here is an excerpt of the generated code infoo.cpp:
   ...
   /* Function Definitions */
   double foo(double u, double v)
   {
   return (double)(float)u + v;
   }
   ...

How MATLAB Coder Partitions Overloaded Functions

An overloaded function is a function that has multiple implementations to accommodate different classes of input. For each implementation (that is not inlined), MATLAB Coder generates a separate C/C++ file with a unique numeric suffix.

For example, suppose you define a simple functionmultiply_defined:

%#codegen function y = multiply_defined(u)

y = u+1;

You then add two more implementations of multiply_defined, one to handle inputs of type single (in an @single subfolder) and another for inputs of type double (in an@double subfolder).

To call each implementation, define the functioncall_multiply_defined:

%#codegen function [y1,y2,y3] = call_multiply_defined

y1 = multiply_defined(int32(2)); y2 = multiply_defined(2); y3 = multiply_defined(single(2));

Next, generate C code for the overloaded functionmultiply_defined. For example, at the MATLAB command line, enter:

codegen -O disable:inline -config:lib call_multiply_defined

MATLAB Coder generates C source, header, and object files for each implementation ofmultiply_defined, as highlighted. Use numeric suffixes to create unique file names.

Generated Files and Locations

The types and locations of generated files depend on the target that you specify. For all targets, if errors or warnings occur during build or if you explicitly request a report, MATLAB Coder generates reports.

Each time MATLAB Coder generates the same type of output for the same code or project, it removes the files from the previous build. If you want to preserve files from a build, copy them to a different location before starting another build.

Generated Files for MEX Targets

By default, MATLAB Coder generates the following files for MEX function (mex) targets.

Generated Files for C/C++ Static Library Targets

By default, MATLAB Coder generates the following files for C/C++ static library targets.

Generated Files for C/C++ Dynamic Library Targets

By default, MATLAB Coder generates the following files for C/C++ dynamic library targets.

Generated Files for C/C++ Executable Targets

By default, MATLAB Coder generates the following files for C/C++ executable targets.

Changing Names and Locations of Generated Files

Using the MATLAB Coder App

To change	Action
The output file name	To open the Generate dialog box, on the Generate Code page, click theGenerate arrow.In the Output file name field, enter the file name.
The output file location	To open the Generate dialog box, on the Generate Code page, click theGenerate arrow.Click More Settings.On the Paths tab, set Build folder to Specified folder.For the Build folder name field, either browse to the output file location or enter the full path. The output file location must not contain: Spaces (Spaces can lead to code generation failures in certain operating system configurations).Tabs\, $,#, *,?Non-7-bit ASCII characters, such as Japanese characters.

At the Command Line. You can change the name and location of generated files by using the codegen options-o and -d.

File Partitioning and Inlining

How MATLAB Coder partitions generated C/C++ code depends on whether you choose to generate one C/C++ file for each MATLAB file and whether you inline your MATLAB functions.

Tradeoffs Between File Partitioning and Inlining

Weighing file partitioning against inlining represents a trade-off between readability, efficiency, and ease of integrating your MATLAB code with existing embedded software.

How Disabling Inlining Affects File Partitioning

Inlining is enabled by default. Therefore, to generate one C/C++ file for each top-level MATLAB function, you must:

• Select to generate one C/C++ file for each top-level MATLAB function. For more information, see How to Select the File Partitioning Method.
• Explicitly disable inlining, either globally or for individual MATLAB functions.

How to Disable Inlining Globally Using the MATLAB Coder App

1. To open the Generate dialog box, on theGenerate Code page, click theGenerate arrow .
2. Click More Settings.
3. On the All Settings tab, under Function Inlining set the Inline threshold to0.

How to Disable Inlining Globally at the Command Line. To disable inlining of functions, use the -O disable:inline option with codegen. For example, to disable inlining and generate a MEX function for a function foo that has no inputs:

codegen -O disable:inline foo

For more information, see the description of codegen.

How to Disable Inlining for Individual Functions. To disable inlining for an individual MATLAB function, use the coder.inline directive or call the function using coder.nonInlineCall. The coder.inline directive applies only to the function in which it appears, while thecoder.nonInlineCall applies only to that specific function call.

Consider this example function, circleFun, which is called by functionfoo.

function foo ... [x,y] = circleFun(n) ... end

function [a,c] = circleFun(n) coder.inline("never"); a = getArea(n); c = coder.nonInlineCall(getCircum,n); end

In this example, the coder.inline("never") directive instructs the code generator not to inline function circleFun in the body of foo. The coder.inline directive in the body of circleFun does not affect the calls to user-written functionsgetArea and getCircum. However,coder.nonInlineCall explicitly instructs the code generator not to inline getCircum in the body ofcircleFun.

It can be more efficient to disable inlining for multiple functions simultaneously at the command line. See How to Disable Inlining Globally at the Command Line.

Correlating C/C++ Code with Inlined Functions

To correlate the C/C++ code that you generate with the original inlined functions, add comments in the MATLAB code to identify the function. These comments will appear in the C/C++ code and help you map the generated code back to the original MATLAB functions.

Modifying the Inlining Threshold

To change inlining behavior, adjust the inlining threshold parameter.

Modifying the Inlining Threshold Using the MATLAB Coder App

1. To open the Generate dialog box, on theGenerate Code page, click theGenerate arrow .
2. Click More Settings.
3. On the All Settings tab, under Function Inlining, set the value of theInline threshold parameter.

Modifying the Inlining Threshold at the Command Line. Set the value of the InlineThreshold parameter of the configuration object. See coder.MexCodeConfig, coder.CodeConfig, coder.EmbeddedCodeConfig.