Main Content

Specify Properties of Entry-Point Function Inputs

Why You Must Specify Input Properties

Because C and C++ are statically typed languages, MATLAB® Coder™ must determine the properties of all variables in the MATLAB files at compile time. To infer variable properties in MATLAB files, MATLAB Coder must be able to identify the properties of the inputs to the primary function, also known as the top-level or entry-point function. Therefore, if your primary function has inputs, you must specify the properties of these inputs, to MATLAB Coder. If your primary function has no input parameters, MATLAB Coder can compile your MATLAB file without modification. You do not need to specify properties of inputs to local functions or external functions called by the primary function.

Note

Your primary function cannot be within a package. Create a wrapper function as the primary function outside the package. Call the desired function within the new function as the primary function.

If you use the tilde (~) character to specify unused function inputs:

  • In MATLAB Coder projects, if you want a different type to appear in the generated code, specify the type. Otherwise, the inputs default to real, scalar doubles.

  • When generating code with codegen, you must specify the type of these inputs using the -args option.

Properties to Specify

If your primary function has inputs, you must specify the following properties for each input.

ForSpecify properties
 ClassSizeComplexitynumerictypefimath
Fixed-point inputs

Each field in a structure input

 Specify properties for each field according to its class

Other inputs

  

Default Property Values

MATLAB Coder assigns the following default values for properties of primary function inputs.

PropertyDefault
classdouble
sizescalar
complexityreal
numerictypeNo default
fimathMATLAB default fimath object

Specifying Default Values for Structure Fields.  In most cases, when you do not explicitly specify values for properties, MATLAB Coder uses defaults except for structure fields. The only way to name a field in a structure is to set at least one of its properties. Therefore, you might need to specify default values for properties of structure fields. For examples, see Specifying Class and Size of Scalar Structure and Specifying Class and Size of Structure Array.

Specifying Default fimath Values for MEX Functions.  MEX functions generated with MATLAB Coder use the default fimath value in effect at compile time. If you do not specify a default fimath value, MATLAB Coder uses the MATLAB default fimath. The MATLAB factory default has the following properties: 

RoundingMethod: Nearest
OverflowAction: Saturate
ProductMode: FullPrecision
SumMode: FullPrecision
CastBeforeSum: true
For more information, see fimath for Sharing Arithmetic Rules (Fixed-Point Designer).

When running MEX functions that depend on the default fimath value, do not change this value during your MATLAB session. Otherwise, you receive a run-time warning, alerting you to a mismatch between the compile-time and run-time fimath values.

For example, suppose that you define the following MATLAB function test:

function y = test %#codegen
y = fi(0);

The function test constructs a fi object without explicitly specifying a fimath object. Therefore, test relies on the default fimath object in effect at compile time. At the MATLAB prompt, generate the MEX function text_mex to use the factory setting of the MATLAB default fimath:

codegen test
% codegen generates a MEX function, test_mex, 
% in the current folder

Next, run test_mex to display the MATLAB default fimath value:

test_mex
 
ans =
 
     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

Now create a local MATLAB fimath value. so you no longer use the default setting:

F = fimath('RoundingMethod','Floor');

Finally, clear the MEX function from memory and rerun it:

clear test_mex
test_mex

The mismatch is detected and causes an error:

??? This function was generated with a different default
fimath than the current default.

Error in ==> test_mex

Specifying Multiple Signatures for MEX Function.  To generate a multisignature MEX function from an entry-point function, provide multiple -args specifications for the same entry-point function. The generated MEX function works with the multiple signatures that you provide during code generation. For more information on multisignature MEX, see Generate One MEX Function for Multiple Signatures.

Supported Classes

The following table presents the class names supported by MATLAB Coder.

Class NameDescription
logicalLogical array of true and false values
charCharacter array
int88-bit signed integer array
uint88-bit unsigned integer array
int1616-bit signed integer array
uint1616-bit unsigned integer array
int3232-bit signed integer array
uint3232-bit unsigned integer array
int6464-bit signed integer array
uint6464–bit unsigned integer array
singleSingle-precision floating-point or fixed-point number array
doubleDouble-precision floating-point or fixed-point number array
structStructure array
embedded.fiFixed-point number array

Rules for Specifying Properties of Primary Inputs

When specifying the properties of primary inputs, follow these rules:

  • The order of elements in the cell array must correspond to the order in which inputs appear in the primary function signature. For example, the first element in the cell array defines the properties of the first primary function input.

  • To generate fewer arguments than those arguments that occur in the MATLAB function, specify properties for only the number of arguments that you want in the generated function.

  • If the MATLAB function has input arguments, to generate a function that has no input arguments, pass an empty cell array to -args.

  • For each primary function input whose class is fixed point (fi), specify the input numerictype and fimath properties.

  • For each primary function input whose class is struct, specify the properties of each of its fields in the order that they appear in the structure definition.

Methods for Defining Properties of Primary Inputs

MethodAdvantagesDisadvantages

Specify Properties of Entry-Point Function Inputs Using the App

  • If you are working in a MATLAB Coder project, easy to use

  • Does not alter original MATLAB code

  • MATLAB Coder saves the definitions in the project file

  • Not efficient for specifying memory-intensive inputs such as large structures and arrays

Define Input Properties by Example at the Command Line

Note

If you define input properties programmatically in the MATLAB file, you cannot use this method

  • Easy to use

  • Does not alter original MATLAB code

  • Designed for prototyping a function that has a few primary inputs

  • Must be specified at the command line every time you invoke codegen (unless you use a script)

  • Not efficient for specifying memory-intensive inputs such as large structures and arrays

Define Input Properties Programmatically in the MATLAB File

  • Integrated with MATLAB code; no need to redefine properties each time you invoke MATLAB Coder

  • Provides documentation of property specifications in the MATLAB code

  • Efficient for specifying memory-intensive inputs such as large structures

  • Uses complex syntax

  • MATLAB Coder project files do not currently recognize properties defined programmatically. If you are using a project, you must reenter the input types in the project.

Define Input Properties by Example at the Command Line

Command-Line Option -args

The codegen function provides a command-line option -args for specifying the properties of primary (entry-point) function inputs as a cell array of example values or types. The cell array can be a variable or literal array of constant values. Using this option, you specify the properties of inputs at the same time as you generate code for the MATLAB function with codegen.

You can pass the output type from one entry-point function as the input to another. See Pass an Entry-Point Function Output as an Input. For information about specifying cell array inputs, see Specify Cell Array Inputs at the Command Line.

If you have a test function or script that calls the entry-point MATLAB function with the required types, you can use coder.getArgTypes to determine the types of the function inputs. coder.getArgTypes returns a cell array of coder.Type objects that you can pass to codegen using the -args option. See Specifying General Properties of Primary Inputs for codegen.

You can also create coder.Type objects interactively by using the Coder Type Editor. See Create and Edit Input Types by Using the Coder Type Editor.

Rules for Using the -args Option

When using the -args command-line option to define properties by example, follow these rules:

  • The order of elements in the cell array must correspond to the order in which inputs appear in the primary function signature. For example, the first element in the cell array defines the properties of the first primary function input.

  • To generate fewer arguments than those arguments that occur in the MATLAB function, specify properties for only the number of arguments that you want in the generated function.

  • If the MATLAB function has input arguments, to generate a function that has no input arguments, pass an empty cell array to -args.

  • For each primary function input whose class is fixed point (fi), specify the input numerictype and fimath properties.

  • For each primary function input whose class is struct, specify the properties of each of its fields in the order that they appear in the structure definition.

Specifying Properties of Primary Inputs by Example at the Command Line

Consider a MATLAB function that adds its two inputs:

function y = mcf(u,v)
%#codegen
y = u + v;

The following examples show how to specify different properties of the primary inputs u and v by example at the command line:

  • Use a literal cell array of constants to specify that both inputs are real scalar doubles:

    codegen mcf -args {0,0}

  • Use a literal cell array of constants to specify that input u is an unsigned 16-bit, 1-by-4 vector and input v is a scalar double:

    codegen  mcf -args {zeros(1,4,'uint16'),0}

  • Assign sample values to a cell array variable to specify that both inputs are real, unsigned 8-bit integer vectors:

    a = uint8([1;2;3;4])
b = uint8([5;6;7;8])
ex = {a,b}
codegen mcf -args ex

Specifying Properties of Primary Fixed-Point Inputs by Example at the Command Line

To generate a MEX function or C/C++ code for fixed-point MATLAB code, you must install Fixed-Point Designer™ software.

Consider a MATLAB function that calculates the square root of a fixed-point number:

%#codegen
function y = sqrtfi(x)
y = sqrt(x);

To specify the properties of the primary fixed-point input x by example, follow these steps:

  1. Define the numerictype properties for x, for example:

    T = numerictype('WordLength',32,...
                'FractionLength',23,...
                'Signed',true);

  2. Define the fimath properties for x, for example:

    F = fimath('SumMode','SpecifyPrecision',...
           'SumWordLength',32,...
           'SumFractionLength',23,...
           'ProductMode','SpecifyPrecision',...
           'ProductWordLength',32,...
           'ProductFractionLength',23);

  3. Create a fixed-point variable with the numerictype and fimath properties that you defined, for example:

    myeg = { fi(4.0,T,F) };

  4. Compile the function sqrtfi using the codegen command, passing the variable myeg as the argument to the -args option, for example:

    codegen sqrtfi -args myeg;

Specify Constant Inputs at the Command Line

If you know that your primary inputs do not change at run time, you can reduce overhead in the generated code by specifying that the primary inputs are constant values. Constant inputs are commonly used for flags that control how an algorithm executes and values that specify the sizes or types of data.

To specify that inputs are constants, use the -args command-line option with a coder.Constant object. To specify that an input is a constant with the size, class, complexity, and value of constant_input, use the following syntax:

-args {coder.Constant(constant_input)}

Calling Functions with Constant Inputs

The code generator compiles constant function inputs into the generated code. In the generated C or C++ code, function signatures do not contain the constant inputs. By default, MEX function signatures contain the constant inputs. When you call a MEX function, you must provide values that match the compile-time values. You can control whether a MEX function signature includes constant inputs and whether the MEX function checks the values that you provide for constant inputs. See Constant Input Checking in MEX Functions.

Specifying a Structure as a Constant Input

Suppose that you define a structure tmp in the MATLAB workspace to specify the dimensions of a matrix:

tmp = struct('rows', 2, 'cols', 3);

The following MATLAB function rowcol accepts a structure input p to define matrix y:

function y = rowcol(u,p) %#codegen
y = zeros(p.rows,p.cols) + u;

The following example shows how to specify that primary input u is a double scalar variable and primary input p is a constant structure:

codegen rowcol -args {0,coder.Constant(tmp)}

Specify Variable-Size Inputs at the Command Line

Variable-size data is data whose size might change at run time. MATLAB supports bounded and unbounded variable-size data for code generation. Bounded variable-size data has fixed upper bounds. This data can be allocated statically on the stack or dynamically on the heap. Unbounded variable-size data does not have fixed upper bounds. This data must be allocated on the heap. You can define inputs to have one or more variable-size dimensions — and specify their upper bounds — using the -args option and coder.typeof function:

-args {coder.typeof(example_value, size_vector, variable_dims)}
Specifies a variable-size input with:

  • Same class and complexity as example_value

  • Same size and upper bounds as size_vector

  • Variable dimensions specified by variable_dims

When you enable dynamic memory allocation, you can specify Inf in the size vector for dimensions with unknown upper bounds at compile time.

When variable_dims is a scalar, it is applied to all the dimensions, with the following exceptions:

  • If the dimension is 1 or 0, which are fixed.

  • If the dimension is unbounded, which is always variable size.

For more information, see coder.typeof and Generate Code for Variable-Size Data.

Specifying a Variable-Size Vector Input

  1. Write a function that computes the average of every n elements of a vector A and stores them in a vector B:

    function B = nway(A,n) %#codegen
% Compute average of every N elements of A and put them in B.

coder.extrinsic('error');
if ((mod(numel(A),n) == 0) && (n>=1 && n<=numel(A)))
    B = ones(1,numel(A)/n);
    k = 1;
    for i = 1 : numel(A)/n
         B(i) = mean(A(k + (0:n-1)));
         k = k + n;
    end
else
    B = zeros(1,0);
    error('n <= 0 or does not divide number of elements evenly');
end

  2. Specify the first input A as a vector of double values. Its first dimension stays fixed in size and its second dimension can grow to an upper bound of 100. Specify the second input n as a double scalar.

    codegen -report nway -args {coder.typeof(0,[1 100],1),1}

  3. As an alternative, assign the coder.typeof expression to a MATLAB variable, then pass the variable as an argument to -args:

    vareg = coder.typeof(0,[1 100],1)
codegen -report nway -args {vareg, 0}

Input Type Specification and arguments blocks

Using function argument validation (arguments blocks) to specify input types of entry-point functions is not supported. Even if your entry-point function contains arguments blocks that validate the input arguments, you must specify the properties of these input arguments by using one of the three approaches listed in Methods for Defining Properties of Primary Inputs.

Default Values for Entry-Point Function Inputs in Generated Code

The arguments block allows you to specify default values for one or more positional input arguments. Specifying a default value in the argument declaration makes a positional argument optional because MATLAB can use the default value when you do not pass a value in the function call. When you generate code by using the codegen command or accelerate fixed-point code by using the fiaccel (Fixed-Point Designer) command, you can choose to not specify the properties of one or more optional positional arguments that have constant default values. In such situations, the default values of these optional arguments are hard-coded in the generated code and these arguments do not appear in the generated code interface. For examples, see the following table.

MATLAB Code

Generated Code

function out = useDefaults_1(a,b,c)
arguments
    a (1,1) double = 3
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen command:

codegen -config:lib -c useDefaults_1 -args {} -report

Generated code:

double useDefaults_1(void)
{
  return 15.0;
}

function out = useDefaults_2(a,b,c)
arguments
    a (1,1) double
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen command:

codegen -config:lib -c useDefaults_2 -args 0 -report

Generated code:

double useDefaults_2(double a)
{
  return (a + 5.0) + 7.0;
}

codegen command:

codegen -config:lib -c useDefaults_2 -args {0,0} -report

Generated code:

double useDefaults_2(double a, double b)
{
  return (a + b) + 7.0;
}

Related Topics