Main Content

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

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

Create a New Folder and Copy Relevant Files

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

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

TypeNameDescription
Function codeoverflow.mEntry-point MATLAB function
Test fileoverflow_test.mMATLAB script that tests overflow.m

Set Up Configuration Object

  1. Create a coder.FixptConfig object, fixptcfg, with default settings.

    fixptcfg = coder.config('fixpt');
  2. Set the test bench name. In this example, the test bench function name is overflow_test.

    fixptcfg.TestBenchName = 'overflow_test';
  3. 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.