Define Types of Entry-Point Inputs at the Command Line

R2026b

When generating code from MATLAB® functions, the code generator must determine the class and size of all variables in your MATLAB code. To enable the code generator to perform this action, you must specify the types of all inputs to your entry-point function. The code generator then uses these types to determine the types of all the other variables in your MATLAB code.

When you generate code using the codegen (MATLAB Coder) command or accelerate fixed‑point code using the fiaccel command, you can specify the types of MATLAB entry‑point function inputs by using the -args option. This topic explains how to use this option to define entry‑point input types.

For alternative methods of specifying input types, see Specify Properties of Entry-Point Function Inputs.

Using the Command-Line Option -args

The codegen and fiaccel functions provide a command-line option -args for specifying the properties of entry-point function inputs:

  • This option accepts a cell array, each of whose elements is either an example value or a coder.Type (MATLAB Coder) object. The cell array can be a variable or literal array of constant values.

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

  • If some of the input arguments are unused, you do not have to specify the types of these input variables in the cell array that you supply with the -args option. However, all used variables must appear before all unused variables in the function declaration. Unused and unspecified variables do not appear in the generated code.

  • If all of the inputs to your MATLAB entry-point functions are unused, pass an empty cell array {} to -args.

If you have a MATLAB Coder™ license and a test function or script that calls the entry-point MATLAB function with the required types, you can use coder.getArgTypes (MATLAB Coder) to determine the types of the function inputs. The coder.getArgTypes function returns a cell array of coder.Type (MATLAB Coder) objects that you can pass to codegen using the -args option.

Specify Fixed-Size Inputs at the Command Line

To specify the properties of an input whose size does not change at run time, provide an example input value to the -args option of the codegen or fiaccel command.

Specify Types of Simple Entry-Point Inputs

Consider a MATLAB entry-point function that adds its two inputs:

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

The following examples show how to specify different types of the 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 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 a 1-by-4 vector of unsigned 16-bit integer type and input v is a scalar, fixed-point value:

    fiaccel 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 fixed-point vectors of size 1-by-4:

    a = fi([1;2;3;4],0,8,0)
b = fi([5;6;7;8],0,8,0)
ex = {a,b}
fiaccel emcf -args ex

Specify numerictype and fimath Properties of Fixed-Point Input

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

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

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

To specify the properties of the 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. Generate code for the function sqrtfi using the codegen or the fiaccel command. Passing the variable myeg as the argument to the -args option.

    codegen sqrtfi -args myeg;
% OR
fiaccel sqrtfi -args myeg;

Specify Constant Inputs at the Command Line

If you know that an entry-point input does not change at run time, you can reduce overhead in the generated code by specifying that this input is a constant value. Use constant inputs for flags that control how an algorithm executes and for values that specify the sizes or types of data.

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

-args {coder.Constant(constant_input)}

Call Functions with Constant Inputs

The fiaccel command hard-codes 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 function identity which copies its input to its output:

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

To generate a MEX function with a constant input, run this command:

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

To run the MATLAB function, you must supply the constant argument:

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

    0.1000

When running MEX function, do not supply the constant argument.

identity_mex
ans =

    0.1000

Specify 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 the y:

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

To specify that input u is a fixed-point scalar variable and the input p is a constant structure, execute this command:

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

To run both the MATLAB function and the generated MEX function, use the following syntaxes:

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. Code generation supports both bounded and unbounded variable-size data. 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)}
This code patten specifies a variable-size input with:

  • Same class 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 whose upper bounds are not known during code generation.

For more information, see Generate Code for Variable-Size Arrays (MATLAB Coder).

Specify a Variable-Size Vector Input

  1. 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
end

  2. 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

  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(fi(0,1,16,15,'SumMode','KeepLSB'),[1 100],1)
fiaccel nway -args {vareg, double(0)} -report

See Also

(MATLAB Coder) |

Topics