Detect Overflows

This example shows how to detect overflows at the command line. 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:

• MATLAB^®

• MATLAB Coder™

• Fixed-Point Designer™

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

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

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 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'')';

Create a code generation configuration object to generate a standalone C static library.

cfg = coder.config('lib');

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

codegen -float2fixed fixptcfg -config cfg overflow

The numerics testing phase reports an overflow.

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

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 codegen command again.

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

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