Detect Overflows

This example shows how to detect overflows using the fiaccel function. At the numerical testing stage in the conversion process, the tool simulates the fixed-point code using scaled doubles. It then reports which expressions in the generated code produce values that would overflow the fixed-point data type.

Prerequisites
Create a New Folder and Copy Relevant Files
Set Up Configuration Object
Enable Overflow Detection
Set fimath Options
Convert to Fixed Point
Review Results

Prerequisites

To complete this example, you must install the following products:

MATLAB^®
Fixed-Point Designer™
C compiler
See Supported Compilers.
You can use mex -setup to change the default compiler. See Change Default Compiler.

Create a New Folder and Copy Relevant Files

In a local, writable folder, create a function overflow.m.

function y = overflow(b,x,reset)
    if nargin<3, reset = true; end
    persistent z p
    if isempty(z) || reset
        p = 0;
        z = zeros(size(b));
    end
    [y,z,p] = fir_filter(b,x,z,p);
end
function [y,z,p] = fir_filter(b,x,z,p)
    y = zeros(size(x));
    nx = length(x);
    nb = length(b);
    for n = 1:nx
        p=p+1; if p>nb, p=1; end
        z(p) = x(n);        
        acc = 0;
        k = p;
        for j=1:nb
            acc = acc + b(j)*z(k);
            k=k-1; if k<1, k=nb; end
        end        
        y(n) = acc;
    end
end

Create a test file, overflow_test.m, to exercise the overflow algorithm.

function overflow_test
    % The filter coefficients were computed using 
    % the FIR1 function from Signal Processing Toolbox.
    %   b = fir1(11,0.25);
    b = [-0.004465461051254
         -0.004324228005260
         +0.012676739550326
         +0.074351188907780
         +0.172173206073645
         +0.249588554524763
         +0.249588554524763
         +0.172173206073645
         +0.074351188907780
         +0.012676739550326
         -0.004324228005260
         -0.004465461051254]';
    
    % Input signal
    nx = 256;
    t = linspace(0,10*pi,nx)';

    % Impulse
    x_impulse = zeros(nx,1); x_impulse(1) = 1;

    % Max Gain
    % The maximum gain of a filter will occur 
    % when the inputs line up with the
    % signs of the filter's impulse response.
    x_max_gain = sign(b)';
    x_max_gain = repmat(x_max_gain,ceil(nx/length(b)),1);
    x_max_gain = x_max_gain(1:nx);


    % Sums of sines
    f0=0.1; f1=2;
    x_sines = sin(2*pi*t*f0) + 0.1*sin(2*pi*t*f1);

    % Chirp
    f_chirp = 1/16;                  % Target frequency
    x_chirp = sin(pi*f_chirp*t.^2);  % Linear chirp

    x = [x_impulse,x_max_gain,x_sines,x_chirp];
    titles = {'Impulse','Max gain','Sum of sines','Chirp'};
    y = zeros(size(x));

    for i=1:size(x,2)
        reset = true;
        y(:,i) = overflow(b,x(:,i),reset);
    end

    test_plot(1,titles,t,x,y)

end
function test_plot(fig,titles,t,x,y1)
    figure(fig)
    clf
    sub_plot = 1;
    font_size = 10;
    for i=1:size(x,2)
        subplot(4,1,sub_plot)
        sub_plot = sub_plot+1;
        plot(t,x(:,i),'c',t,y1(:,i),'k')
        axis('tight')
        xlabel('t','FontSize',font_size);
        title(titles{i},'FontSize',font_size);
        ax = gca;
        ax.FontSize = 10;
    end
    figure(gcf)
end

It is best practice to create a separate test script to do all the pre- and post-processing such as loading inputs, setting up input values, calling the function under test, and outputting test results.

Type	Name	Description
Function code	`overflow.m`	Entry-point MATLAB function
Test file	`overflow_test.m`	MATLAB script that tests `overflow.m`

Set Up Configuration Object

Create a coder.FixptConfig object, fixptcfg, with default settings.
```
fixptcfg = coder.config('fixpt');
```
Set the test bench name. In this example, the test bench function name is overflow_test.
```
fixptcfg.TestBenchName = 'overflow_test';
```
Set the default word length to 16.
```
fixptcfg.DefaultWordLength = 16;
```

Enable Overflow Detection

fixptcfg.TestNumerics = true;
fixptcfg.DetectFixptOverflows = true;

Set fimath Options

Set the fimath Product mode and Sum mode to KeepLSB. These settings models the behavior of integer operations in the C language.

fixptcfg.fimath = 'fimath( ''RoundingMethod'', ''Floor'', ''OverflowAction'', ''Wrap'', ''ProductMode'', ''KeepLSB'', ''SumMode'', ''KeepLSB'')';

Convert to Fixed Point

Convert the floating-point MATLAB function, overflow, to fixed-point MATLAB code. You do not need to specify input types for the fiaccel command because it infers the types from the test file.

fiaccel -float2fixed fixptcfg overflow

The numerics testing phase reports an overflow.

Overflow error in expression 'acc + b( j )*z( k )'. 
Percentage of Current Range = 104%.

Review Results

Determine if the addition or the multiplication in this expression overflowed. Set the fimath ProductMode to FullPrecision so that the multiplication will not overflow, and then run the fiaccel command again.

fixptcfg.fimath = 'fimath( ''RoundingMethod'', ''Floor'', ''OverflowAction'', ''Wrap'', ''ProductMode'', ''FullPrecision'', ''SumMode'', ''KeepLSB'')';
fiaccel -float2fixed fixptcfg overflow

The numerics testing phase still reports an overflow, indicating that it is the addition in the expression that is overflowing.