Specify Properties of EntryPoint 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 toplevel or entrypoint 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 theargs
option.
Methods for Defining Properties of Primary Inputs
Method  Advantages  Disadvantages 


 
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 


Use Argument and Property Validation to Specify EntryPoint Input Types 


Define Input Properties Using assert Statements in MATLAB Code 


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

Class  Size  Complexity  numerictype  fimath  
Fixedpoint inputs 





Each field in a structure input  
Other inputs 



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

class  double 
size  scalar 
complexity  real 
numerictype  No default 
fimath  MATLAB 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
When running MEX functions that depend on the default
fimath
value, do not change this value during your
MATLAB session. Otherwise, you receive a runtime warning, alerting you
to a mismatch between the compiletime and runtime 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: Fixedpoint: 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 entrypoint function,
provide multiple args
specifications for the same
entrypoint function. The generated MEX function works with the multiple
signatures that you provide during code generation. For more information on
multisignature MEX, see Generate Code for Functions with Multiple Signatures.
Supported Classes
The following table presents the class names supported by MATLAB Coder.
Class Name  Description 

logical  Logical array of true and false values 
char  Character array 
int8  8bit signed integer array 
uint8  8bit unsigned integer array 
int16  16bit signed integer array 
uint16  16bit unsigned integer array 
int32  32bit signed integer array 
uint32  32bit unsigned integer array 
int64  64bit signed integer array 
uint64  64–bit unsigned integer array 
single  Singleprecision floatingpoint or fixedpoint number array 
double  Doubleprecision floatingpoint or fixedpoint number array 
struct  Structure array 
embedded.fi  Fixedpoint 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 inputnumerictype
andfimath
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.
Define Input Properties by Example at the Command Line
Specifying Properties of Primary Inputs by Example at the Command Line
Specifying Properties of Primary FixedPoint Inputs by Example at the Command Line
CommandLine Option args
The codegen
function provides a
commandline option args
for specifying the properties of
primary (entrypoint) 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 entrypoint function as the input to another. See Pass an EntryPoint 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
entrypoint 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
commandline 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 inputnumerictype
andfimath
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 16bit, 1by4 vector and inputv
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 8bit 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 FixedPoint Inputs by Example at the Command Line
To generate a MEX function or C/C++ code for fixedpoint MATLAB code, you must install FixedPoint Designer™ software.
Consider a MATLAB function that calculates the square root of a fixedpoint number:
%#codegen function y = sqrtfi(x) y = sqrt(x);
To specify the properties of the primary fixedpoint input x
by
example, follow these steps:
Define the
numerictype
properties forx
, for example:T = numerictype('WordLength',32,... 'FractionLength',23,... 'Signed',true);
Define the
fimath
properties forx
, for example:F = fimath('SumMode','SpecifyPrecision',... 'SumWordLength',32,... 'SumFractionLength',23,... 'ProductMode','SpecifyPrecision',... 'ProductWordLength',32,... 'ProductFractionLength',23);
Create a fixedpoint variable with the
numerictype
andfimath
properties that you defined, for example:myeg = { fi(4.0,T,F) };
Compile the function
sqrtfi
using thecodegen
command, passing the variablemyeg
as the argument to theargs
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
commandline
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 compiletime 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 VariableSize Inputs at the Command Line
Variablesize data is data whose size might change at run time. MATLAB supports bounded and unbounded variablesize data for code generation.
Bounded variablesize data has fixed upper bounds. This data
can be allocated statically on the stack or dynamically on the heap.
Unbounded variablesize data does not have fixed upper
bounds. This data must be allocated on the heap. You can define inputs to have one or
more variablesize dimensions — and specify their upper bounds — using the
args
option and coder.typeof
function:
args {coder.typeof(example_value, size_vector, variable_dims)}
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 VariableSize Data.
Specifying a VariableSize Vector Input
Write a function that computes the average of every
n
elements of a vectorA
and stores them in a vectorB
: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:n1))); k = k + n; end else B = zeros(1,0); error('n <= 0 or does not divide number of elements evenly'); end
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 inputn
as a double scalar.codegen report nway args {coder.typeof(0,[1 100],1),1}
As an alternative, assign the
coder.typeof
expression to a MATLAB variable, then pass the variable as an argument toargs
:vareg = coder.typeof(0,[1 100],1) codegen report nway args {vareg, 0}