Embedded MATLAB™

Embedded MATLAB Coding Style

Writing Reusable Code

With the Embedded MATLAB subset, you can write reusable code in the following ways:

• Write reusable functions using standard MATLAB function file names which you can call from different locations, for example, in a Simulink model or M-function library.

• Compile external functions on the MATLAB path and integrate them into generated C code for embedded targets.

• Generate code for external M-functions that are compliant with Embedded MATLAB syntax and semantics.

See How the Embedded MATLAB Subset Resolves Function Calls.

Common applications include:

• Overriding an Embedded MATLAB library function with a custom implementation

• Implementing a reusable library on top of standard library functions that can be used with Simulink

• Swapping between different implementations of the same function

Back to Top

Writing Efficient Code

The Embedded MATLAB subset provides methodologies for writing efficient code:

• Unrolling for-Loops

• Inlining Functions

Unrolling for-Loops

Unrolling for-loops eliminates the loop logic by creating a separate copy of the loop body in the generated code for each iteration. Within each iteration, the loop index variable becomes a constant. By unrolling short loops with known bounds at compile time, Embedded MATLAB functions generate highly optimized code with no branches.

You can also force loop unrolling for individual functions by wrapping the loop header in an eml.unroll function. For more information, see eml.unroll in the Embedded MATLAB Function Reference.

Inlining Functions

The Embedded MATLAB subset uses internal heuristics to determine whether or not to inline functions in the generated code. In most cases, these heuristics produce highly optimized code. However, you can use the eml.inline directive to fine-tune these optimizations for individual functions. See eml.inline in the Embedded MATLAB Function Reference.

Back to Top

Working with Variables

• Rules for Declaring Variables

• Declaring Variables By Assignment

• Declaring Uninitialized Variables

• Declaring Persistent Variables

• Initializing Persistent Variables

• Supported Variable Types

Rules for Declaring Variables

Observe the following rules when defining variables in an Embedded MATLAB function:

Declare Variables Explicitly Before Using Them.   You must explicitly and unambiguously declare the size, type, and complexity of variables before using them in operations or returning them as outputs in Embedded MATLAB functions. To declare variables, assign them to data with known properties, as described in Declaring Variables By Assignment.

By default, the assignment copies the size, type, complexity, and value to the new variable. Initializing the new variable to the value of the assigned data sometimes results in redundant copies in the generated code. To avoid redundant copies, you can define variables without initializing their values by using the eml.nullcopy construct as described in Declaring Uninitialized Variables.

Do not change properties of variables after the initial assignment.   You cannot change size, type, or complexity of a variable after setting these properties as part of the initial assignment. In the following example, the last two statements each cause errors:

x = 2.75; % OK
y = [1 2; 3 4]; % OK
x = int16(x); % ERROR: cannot recast x
y = [1 2 3; 4 5 6]; %ERROR: cannot resize y

Declaring Variables By Assignment

As in MATLAB, you declare variables by assignment. However, in Embedded MATLAB code, you cannot change the size, type, or complexity of the variable after the initial assignment. Therefore, you must set these properties as part of the assignment declaration. The data that you assign to a variable can be a scalar, matrix, or structure.

For example, the following assignments define variables in an Embedded MATLAB function:

...
% a is a scalar of type double.
a = 14.7;

% b has properties of a, scalar of type double.
b = a;

% c is a 5-by-2 double array of zeros.
c = zeros(5,2);

% d has properties of c (5-by-2 double array of zeros).
d = c;

% e is 5-by-2 array of type double.
e = [1 2 3 4 5; 6 7 8 9 0];
...

When you declare variables, they are local by default; they do not persist between function calls. To make variables persistent, see Declaring Persistent Variables.

Using Type Cast Operators in Variable Declarations.   By default, constants are of type double. To declare variables of other types, you can use type cast operators in variable declarations. For example, the following code declares variables y and z as integers:

x = 15; % x is of type double by default.
y = int16(3); % y is a constant of type int16.
z = uint8(x); % z has the value of x, but cast to uint8.

Setting Properties of Indexed Variables.   Unlike in MATLAB, you cannot set the size of an indexed variable in an assignment statement. You must define the matrix first before assigning values to any of its elements.

For example, the following initial assignment is not allowed in Embedded MATLAB functions:

g(3,2) = 14.6; % Not allowed for creating g 
				     % OK for assigning value once created

For more information about indexing matrices, see Using Matrix Indexing Operations.

Declaring Uninitialized Variables

Variable declarations in the Embedded MATLAB subset not only copy the properties of the assigned data to the new variable, but also initialize the new variable to the assigned value. This forced initialization sometimes results in redundant copies in C code generated using Real-Time Workshop software. Embedded MATLAB technology eliminates many copies automatically. To eliminate copies that are not automatically handled, you can declare uninitialized variables by using the eml.nullcopy function.

Use caution when declaring uninitialized variables, as described in Rules for Declaring Uninitialized Variables.

Rules for Declaring Uninitialized Variables.   Follow these rules when declaring uninitialized variables:

• After declaring a variable with eml.nullcopy, you must explicitly initialize the variable before reading it. Otherwise, you may get unpredictable results.

   What happens if you access uninitialized data?

  Uninitialized memory contains arbitrary values. Therefore, accessing uninitialized data may lead to segmentation violations or nondeterministic program behavior (different runs of the same program may yield inconsistent results).

• When the uninitialized variable is an array, you must initialize all of its elements before passing the array as an input to a function or operator — even if the function or operator does not read from the uninitialized portion of the array.

Example: Declaring Uninitialized Variables.   In the following code, the assignment statement X = zeros(1,N) not only declares X to be a 1-by-5 vector of real doubles, but also initializes each element of X to zero.

function X = fcn %#eml

N = 5;
X = zeros(1,N);
for i = 1:N
   if mod(i,2) == 0
      X(i) = i;
   else
      X(i) = 0;
   end
end

This forced initialization creates an extra copy in the generated code. To eliminate this overhead, use eml.nullcopy in the declaration of X:

function X = fcn2 %#eml

N = 5;
X = eml.nullcopy(zeros(1,N));
for i = 1:N
   if mod(i,2) == 0
      X(i) = i;
   else
      X(i) = 0;
   end
end

Declaring Persistent Variables

Persistent variables are local to the function in which they are declared, but they retain their values in memory between calls to the function. To declare persistent variables in Embedded MATLAB functions, use the persistent statement, as in this example:

persistent PROD_X;

The declaration should appear at the top of the function body, after the header and comments, but before the first use of the variable.

See Also.  

Initializing Persistent Variables

Initializing Persistent Variables

You initialize persistent variables in Embedded MATLAB functions the same way as in MATLAB (see Persistent Variables in the MATLAB Programming Fundamentals documentation). When you declare a persistent variable, Embedded MATLAB initializes its value to an empty matrix. After the declaration statement, you can assign your own value to it using the isempty statement, as in this example:

function findProduct(inputvalue)
persistent PROD_X

if isempty(PROD_X)
   PROD_X = 1;
end
PROD_X = PROD_X * inputvalue;

Supported Variable Types

Embedded MATLAB functions support a subset of MATLAB data types:

Back to Top

Using Matrix Indexing Operations

The Embedded MATLAB subset supports matrix indexing operations for a matrix M with limitations for the following types of expressions:

• M(i:j) where i and j change in a loop

  Embedded MATLAB never dynamically allocates memory for the size of the expressions that change as the program executes. To implement this behavior, use for loops as shown in the following example:

  M = ones(10,10);
  for i=1:10
  	for j = i:10
  		M(i,j) = 2 * M(i,j);
  	end
  end
  

  Note   The matrix M must be defined before entering the loop, as shown in the highlighted code.

• M(i:i+k) where i is unknown but k is known

  In this case, since i — and therefore i+k — are not known, memory cannot be allocated for the numerical result. However, memory can be allocated for the following workaround:

  M(i + (0:k))
  

  In this case, an unknown scalar value i is added to each element of the known index vector 0...k. This means that memory for k+1 elements of M is allocated.

• Initialization of the following style:

  for i = 1:10
  	M(i) = 5;
  end
  

  In this case, the size of M changes as the loop is executed.

Back to Top

Working with Complex Numbers

The Embedded MATLAB subset supports complex numbers and operations.

• Creating Local Complex Variables By Assignment

• Semantic Rules for Complex Numbers

Creating Local Complex Variables By Assignment

As in MATLAB, you create complex variables by assignment. Unlike in MATLAB, you must set complexity at the time of assignment, either by assigning a complex constant to the variable or using the complex function, as in these examples:

x = 5 + 6i; % x is a complex number by assignment.
y = 7 + 8j; % y is a complex number by assignment.
x = complex(5,6); % x is the complex number 5 + 6i.

Use the following rules to specify and use complex variables in Embedded MATLAB functions:

• Once you set the type and size of a variable, you cannot cast it to another type or size.

  In the following example, the variable x is declared complex and stays complex:

  x = 1 + 2i; % x is declared a complex variable.
  y = int16(x); % Real and imaginary parts of y are int16.
  x = 3; % x now has the value 3 + 0i.
  

  Conflicts can occur from operations with real operands that can have complex results. For example, the following code generates an error:

  z = 3; % Sets type of z to double (real)
  z = 3 + 2i; % ERROR: cannot recast z to complex
  

  The following is a possible workaround that you can use if you know that a variable can be assigned a complex number:

  m = complex(3); % Sets m to complex variable of value 3 + 0i
  m = 5 + 6.7i; % Assigns a complex result to a complex number
  

• Cases in which a function can return a complex number for a real argument are handled individually for each function.

  Generally, this can result in a complex result or a warning that the function takes only arguments producing real results. For example, for negative arguments, the function sqrt warns that only real positive or complex arguments are allowed.

• In general, if an expression has a complex number or variable in it, its result is a complex number, even if the result is 0.

  For example, the following code produces the complex result z:

  x = 2 + 3i;
  y = 2 - 3i;
  z = x + y;  % z is 4 + 0i.
  

  In MATLAB, this code generates the real result z = 4. However, when the Embedded MATLAB subset generates code for z = x + y, the types for x and y are known, but their values are not. Because either or both operands in this expression are complex, z is declared a complex variable requiring storage for both a real and an imaginary part. This means that z has the complex result 4 + 0i in Embedded MATLAB, not 4 as in MATLAB.

  An exception to the preceding rule is a function call that takes complex arguments but produces real results, as shown in the following examples:

  y = real(x); % y is the real part of the complex number x.
  y = imag(x); % y is the real-valued imaginary part of x.
  y = isreal(x); % y is false (0) for a complex number x.
  

  Another exception is a function call that takes real arguments but produces complex results, as shown in the following example:

  z = complex(x,y); % z is a complex number for a real x and y.
  

Semantic Rules for Complex Numbers

with the following exceptions:

• The first use of a variable that is later assigned a complex result must also be complex. For example,

  X = 3;
  	.
  	.
  	.
  X = 4 + 5i;
  

  fails because X is not defined as a complex variable by its first assignment. However,

  X = 3 + 0i;
  	.
  	.
  	.
  X = 4 + 5i;
  

  succeeds because X is defined as a complex variable in its first assignment.

• Even if the imaginary part is zero, if the result might be complex, the Embedded MATLAB subset will treat it as complex. For example, although

  X = ifft(fft(Y));
  

  yields a real answer, Embedded MATLAB assumes that the function ifft might return a complex result. The workaround is to use the real function:

  X = real(ifft(fft(Y)));
  

Back to Top

Working with Characters

The Embedded MATLAB subset represents characters in 8 bits and, therefore, does not support the complete set of Unicode^® characters. Because many mathematical operations require more than 8 bits of precision, it is recommended that you do not perform arithmetic with characters in Embedded MATLAB code.

Back to Top

Using Embedded MATLAB Technology with MathWorks Products

Supported Operators