Fixed-Point Toolbox™

Fixed-Point Embedded MATLAB™ Subset Features

Embedded MATLAB™ MEX

Embedded MATLAB™ MEX converts M-code to C-MEX functions that contain Embedded MATLAB subset optimizations for automatically accelerating fixed-point algorithms to compiled C code speed in MATLAB^®. For more information, refer to Working with Embedded MATLAB™ MEX in the Embedded MATLAB language subset documentation.

Speeding Up Fixed-Point Execution with the emlmex Function

The Embedded MATLAB emlmex function can greatly increase the execution speed of your algorithms; however, improper use of the function can also slow execution. In this example, you will use the emlmex function to compile different parts of a simple algorithm. By comparing the run times of the two cases, you will see the benefits and best use of the emlmex function.

Algorithm.   The algorithm used throughout this example replicates the functionality of the MATLAB sum function, which sums the columns of a matrix. To see the algorithm, type open fi_matrix_column_sum.m at the MATLAB command line.

function B = fi_matrix_column_sum(A)
% Sum the columns of matrix A.
%#eml
    [m,n] = size(A);
    w = get(A,'WordLength') + ceil(log2(m));
    f = get(A,'FractionLength');
    B = fi(zeros(1,n),true,w,f,fimath(A));
    for j = 1:n
        for i = 1:m
            B(j) = B(j) + A(i,j);
        end
    end

Trial 1: Best Performance.   The best way to speed up the execution of the algorithm is to compile the entire algorithm using the emlmex function. To evaluate the performance of the emlmex function when the entire algorithm is compiled, run the following code. The first portion of m-code executes the algorithm using only MATLAB functions. The second portion of the code compiles the entire algorithm using the Embedded MATLAB emlmex function. The MATLAB tic and toc functions keep track of the run times for each method of execution.

% MATLAB
fipref('NumericTypeDisplay','short','FimathDisplay','none');
A = fi(randn(1000,10));
tic
B = fi_matrix_column_sum(A)
t_matrix_column_sum_m = toc

% Embedded MATLAB
emlmex fi_matrix_column_sum -o fi_matrix_column_sum_x -eg {A} ...
-I [matlabroot '/toolbox/fixedpoint/fidemos']
tic
B = fi_matrix_column_sum_x(A);
t_matrix_column_sum_eml = toc

Trial 2: Worst Performance.   Compiling only the smallest unit of computation using the emlmex function leads to much slower execution. In some cases, the overhead that results from calling the emlmex function inside a nested loop can cause even slower execution than using MATLAB functions alone. To evaluate the performance of the emlmex function when only the smallest unit of computation is compiled, run the following code. The first portion of m-code executes the algorithm using only MATLAB functions. The second portion of the code compiles the smallest unit of computation with the emlmex function, leaving the rest of the computations to MATLAB.

% MATLAB
tic
[m,n] = size(A);
w = get(A,'WordLength') + ceil(log2(m));
f = get(A,'FractionLength');
B = fi(zeros(1,n),true,w,f,fimath(A));
for j = 1:n
    for i = 1:m
        B(j) = fi_scalar_sum(B(j),A(i,j));
        % B(j) = B(j) + A(i,j);
    end
end
t_scalar_sum_m = toc

% Embedded MATLAB
emlmex fi_scalar_sum -o fi_scalar_sum_x -eg {B(1),A(1,1)} ...
-I [matlabroot '/toolbox/fixedpoint/fidemos']
tic
[m,n] = size(A);
w = get(A,'WordLength') + ceil(log2(m));
f = get(A,'FractionLength');
B = fi(zeros(1,n),true,w,f,fimath(A));
for j = 1:n
    for i = 1:m
        B(j) = fi_scalar_sum_x(B(j),A(i,j));
        % B(j) = B(j) + A(i,j);
    end
end
t_scalar_sum_eml = toc

Ratio of Times.   A comparison of Trial 1 and Trial 2 appears in the following table. Your computer may record different times than the ones the table shows, but the ratios should be approximately the same. There is an extreme difference in ratios between the trial where the entire algorithm was compiled using emlmex (t_matrix_column_sum_eml) and where only the scalar sum was compiled (t_scalar_sum_eml). Even the M-file with no emlmex compilation (t_matrix_column_sum_m) did better than when only the smallest unit of computation was compiled using emlmex (t_scalar_sum_eml).

Using Data Type Override with Embedded MATLAB™ MEX

Fixed-Point Toolbox™ software ships with a demonstration of how to generate a C-MEX function from M-code. The M-code takes the weighted average of a signal to create a lowpass filter. To run the demo, click the Fixed-Point Lowpass Filtering Using Embedded MATLAB MEX link and follow the instructions in the right pane of the Help browser.

You can specify data type override in this demo by typing an extra command at the MATLAB prompt in the "Define Fixed-Point Parameters" section of the demo. To turn data type override on, type the following command at the MATLAB prompt after running the reset(fipref) demo command in that section:

fipref('DataTypeOverride','TrueDoubles')

This command tells Fixed-Point Toolbox software to create all fi objects with type fi double. When you compile the M-file using the emlmex command in the "Compile the M-File into a MEX File" section of the demo, the resulting MEX-function uses floating-point data.

Back to Top

Embedded MATLAB™ Function Block

The Embedded MATLAB Function block lets you compose a MATLAB language function in a Simulink^® model that generates embeddable code using the Embedded MATLAB subset. When you simulate the model or generate code for a target environment, a function in an Embedded MATLAB Function block generates efficient C code. This code meets the strict memory and data type requirements of embedded target environments. In this way, Embedded MATLAB Function blocks bring the power of MATLAB for the embedded environment into Simulink. For more information, refer to Using the Simulink^® Embedded MATLAB™ Function Block.

Back to Top

Supported Functions and Limitations of Fixed-Point Embedded MATLAB™ Subset

Interoperability with Other Products