Specify Properties of Entry-Point Function Inputs

Why You Must Specify Input Properties

Fixed-Point Designer™ must determine the properties of all variables in the MATLAB^® files at compile time. To infer variable properties in MATLAB files, Fixed-Point Designer 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 Fixed-Point Designer. If your primary function has no input parameters, Fixed-Point Designer 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.

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
Fixed-point inputs
Each field in a structure input	Specify properties for each field according to its class When a primary input is a structure, the code generator treats each field as a separate input. Therefore, you must specify properties for all fields of a primary structure input in the order that they appear in the structure definition: For each field of input structures, specify class, size, and complexity. For each field that is fixed-point class, also specify `numerictype`, and `fimath`.
Other inputs

Default Property Values

Fixed-Point Designer 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

Supported Classes

The following table presents the class names supported by Fixed-Point Designer.

Class Name	Description
`logical`	Logical array of true and false values
`char`	Character array
`int8`	8-bit signed integer array
`uint8`	8-bit unsigned integer array
`int16`	16-bit signed integer array
`uint16`	16-bit unsigned integer array
`int32`	32-bit signed integer array
`uint32`	32-bit unsigned integer array
`int64`	64-bit signed integer array
`uint64`	64–bit unsigned integer array
`single`	Single-precision floating-point or fixed-point number array
`double`	Double-precision floating-point or fixed-point number array
`struct`	Structure array
`embedded.fi`	Fixed-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

Method	Advantages	Disadvantages
	If you are working in a project, easy to use Does not alter original MATLAB code 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 `fiaccel` (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 (MATLAB Coder)	Integrated with MATLAB code; no need to redefine properties each time you invoke Provides documentation of property specifications in the MATLAB code Efficient for specifying memory-intensive inputs such as large structures	Uses complex syntax 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
Rules for Using the -args Option
Specifying Properties of Primary Inputs by Example
Specifying Properties of Primary Fixed-Point Inputs by Example

Command-Line Option -args

The fiaccel 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 fiaccel.

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 (MATLAB Coder).

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

Consider a function that adds its two inputs:

function y = emcf(u,v) %#codegen
% The directive %#codegen indicates that you
% intend to generate code for this algorithm
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, fixed-point values:
```
fiaccel -o emcfx emcf ...
   -args {fi(0,1,16,15),fi(0,1,16,15)}
```
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, fixed-point value:
```
fiaccel -o emcfx emcf ...
   -args {zeros(1,4,'uint16'),fi(0,1,16,15)}
```
Assign sample values to a cell array variable to specify that both inputs are real, unsigned 8-bit integer vectors:
```
a = fi([1;2;3;4],0,8,0)
b = fi([5;6;7;8],0,8,0)
ex = {a,b}
fiaccel -o emcfx emcf -args ex
```

Specifying Properties of Primary Fixed-Point Inputs by Example

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

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

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

Define the numerictype properties for x, as in this example:

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

Define the fimath properties for x, as in this example:

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

Create a fixed-point variable with the numerictype and fimath properties you defined, as in this example:
```
myeg = { fi(4.0,T,F) };
```
Compile the function sqrtfi using the fiaccel command, passing the variable myeg as the argument to the-args option, as in this example:
```
fiaccel 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

fiaccel compiles constant function inputs into the generated code. As a result, the MEX function signature differs from the MATLAB function signature. At run time, you supply the constant argument to the MATLAB function, but not to the MEX function.

For example, consider the following function identity which copies its input to its output:

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

To generate a MEX function identity_mex with a constant input, type the following command at the MATLAB prompt:

fiaccel -o identity_mex identity...
    -args {coder.Constant(fi(0.1,1,16,15))}

To run the MATLAB function, supply the constant argument as follows:

identity(fi(0.1,1,16,15))

You get the following result:

ans =

    0.1000

Now, try running the MEX function with this command:

identity_mex

You should get the same answer.

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, as follows:

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 = fi(zeros(p.rows,p.cols),1,16,15) + 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:

fiaccel rowcol ...
   -args {fi(0,1,16,15),coder.Constant(tmp)}

To run this code, use

u = fi(0.5,1,16,15)
y_m = rowcol(u,tmp)

y_mex = rowcol_mex(u)

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.

Specifying a Variable-Size Vector Input

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

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

coder.extrinsic('error');
Tb = numerictype(1,32,24);
if ((mod(numel(A),n) == 0) && ...
  (n>=1 && n<=numel(A)))
    B = fi(zeros(1,numel(A)/n),Tb);
    k = 1; 
    for i = 1 : numel(A)/n
        B(i) = sum(A(k + (0:n-1)));
        k = k + n;
    end
else
    B = fi(zeros(1,0),Tb);
    error('n<=0 or does not divide evenly');
end

Specify the first input A as a fi object. 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.
```
fiaccel nway ...
-args {coder.typeof(fi(0,1,16,15,'SumMode','KeepLSB'),[1 100],1),0}...
-report
```
As an alternative, assign the coder.typeof expression to a MATLAB variable, then pass the variable as an argument to -args:
```
vareg = coder.typeof(fi(0,1,16,15,'SumMode','KeepLSB'),[1 100],1)
fiaccel nway -args {vareg, double(0)} -report
```

Documentation