Specifying Properties of Primary Function Inputs

On this page…
Why You Must Specify Input Properties Properties to Specify Rules for Specifying Properties of Primary Inputs Methods for Defining Properties of Primary Inputs Defining Input Properties by Example at the Command Line

Why You Must Specify Input Properties

To generate code in a statically typed language, fiaccel must determine the properties of all variables in the MATLAB code at compile time. Therefore, you must specify the class, size, and complexity of inputs to the primary function (also known as the top-level or entry-point function). If your primary function has no input parameters, fiaccel can compile your MATLAB algorithm without modification. You do not need to specify properties of inputs to subfunctions or external functions called by the primary function. For fiaccel requirements, refer to its reference page.

Back to Top

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
Structure inputs*				(if structure field is fixed-point)	(if structure field is fixed-point)
All other inputs

* When a primary input is a structure, fiaccel treats each field as a separate input.

Default Property Values

fiaccel 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, fiaccel uses defaults when you don't explicitly specify values for properties—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 may need to specify default values for properties of structure fields. For examples, see Example: Specifying Class and Size of Scalar Structure and Example: Specifying Class and Size of Structure Array.

Specifying Default fimath Values for MEX Functions.  MEX functions generated with fiaccel use the MATLAB default fimath. The MATLAB factory default fimath has the following properties:

           RoundMode: nearest
        OverflowMode: saturate
         ProductMode: FullPrecision
MaxProductWordLength: 128
             SumMode: FullPrecision
    MaxSumWordLength: 128

For more information, see Working with fimath Objects.

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

For example, suppose 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 will rely on the default fimath object at compile time. At the MATLAB prompt, generate the MEX function text_mex to use the factory setting of the MATLAB default fimath:

fiaccel test
% fiaccel 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

Supported Classes

The following table presents the class names supported by fiaccel:

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

Back to Top

Rules for Specifying Properties of Primary Inputs

Follow these rules when specifying the properties of primary inputs:

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

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

Back to Top

Methods for Defining Properties of Primary Inputs

You can use any of the following methods to define the properties of primary function inputs:

Method	Pros	Cons
Defining Input Properties by Example at the Command Line	Easy to use Does not alter original MATLAB code Designed for prototyping a function that has a small number of 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
Defining Input Properties Programmatically in the MATLAB File	Integrated with MATLAB code so you do not need to redefine properties each time you invoke fiaccel Provides documentation of property specifications in the MATLAB code Efficient for specifying memory-intensive inputs such as large structures	Uses complex syntax

Note   To specify the properties of inputs for any given primary function, use one of these methods or the other, but not both.

Back to Top

Defining Input Properties by Example at the Command Line

• Command Line Option -args

• Rules for using the -args option

• Specifying Constant Inputs

• Specifying Variable-Size Inputs

Command Line Option -args

fiaccel provides a command-line option -args for specifying the properties of primary function inputs as a cell array of example values. The cell array can be a variable or literal array of constant values.

Example: 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

Example: 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:

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

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

2. Define the fimath properties for x, as in this 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 you just defined, as in this example:

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

4. 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;

Rules for using the -args option

Follow these rules when using the -args command-line option to define properties by example:

• The cell array of sample values must contain the same number of elements as primary function inputs.

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

Specifying Constant Inputs

In cases where you know your primary inputs will not change at run time, you can specify them as constant values than as variables to eliminate unnecessary overhead in generated code. Common uses of constant inputs are for flags that control how an algorithm executes and values that specify the sizes or types of data.

You can define inputs to be constants using this command-line option:

-args {coder.Constant(constant_input)}

This expression specifies that an input will be a constant with the size, class, complexity, and value of 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.

Example: Specifying a Structure as a Constant Input.  Suppose 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)

Specifying Variable-Size Inputs

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:

Expression	Description
-args {coder.typeof(example_value, size_vector, dim_vector)}	Specifies a variable-size input with: Same class and complexity as example_value Same size and upper bounds as size_vector dim_vector specifies which dimensions are variable. A value of true or one means that the corresponding dimension is variable. A value of false or zero means that the corresponding dimension is fixed.

Example: Specifying 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(numberofelements(A),n) == 0) && ...
     (n>=1 && n<=numberofelements(A)))
       B = fi(zeros(1,numberofelements(A)/n),Tb);
       k = 1; 
       for i = 1 : numberofelements(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
   
   

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),[1 100],1),0}...
       -report

   Note   You do not need to explicitly cast these inputs as double because fiaccel assumes the default properties of inputs are real, double scalars.

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),[1 100],1)
   fiaccel nway -args {vareg, double(0)}

   Note   For comparison, this command does explicitly cast the inputs to double.

Back to Top

Setting MEX Compilation Options

Best Practices for Accelerating Fixed-Point MATLAB Code

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS