Documentation Center

  • Trial Software
  • Product Updates

Contents

Detect Overflows Using the Fixed-Point Conversion Tool

This example shows how to detect overflows using the Fixed-Point Conversion tool. 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™

Create a Project

In a local writable folder, create a MATLAB Coder project named overflow.

At the MATLAB command line, enter

coder -new overflow.prj

By default, the project opens in the MATLAB workspace.

Add File

  1. In the same 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
    
  2. On the project Overview tab, click the Add files link. Browse to the file overflow.m and then click OK to add the file to the project.

Define Input Types

  1. Create a test file, overflow_test.m to exercise the overflow algorithm. You use this test file to define input types for b, x, and reset, and, later, to verify the fixed-point version of the 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);
            set(gca,'FontSize',12);
        end
        figure(gcf)
    end
    
  2. On the project Overview tab, click the Autodefine types link.

  3. In the Autodefine Input Types dialog box, add overflow_test as a test file and then click Run.

    The test file runs and displays the outputs of the filter for each of the input signals.MATLAB Coder determines the input types from the test file and then displays them.

  4. In the Autodefine Input Types dialog box, click Use These Types.

    MATLAB Coder sets the types of b to double(1x12), x to double(256x1), and reset to logical(1x1).

Fixed-Point Conversion

  1. On the project Overview tab Fixed-Point Conversion pane, select Convert to fixed-point at build time.

    The project indicates that you must first define the fixed-point data types.

  2. In the Fixed-Point Conversion pane, click Define and validate fixed-point types.

    The Fixed-Point Conversion tool opens and generates an instrumented MEX function for your entry-point MATLAB function. After generating the MEX function, the tool displays compiled information — type, size, and complexity — for variables in your code. For more information, see View and Modify Variable Information.

  3. In the Fixed-Point Conversion tool, click Advanced to view the advanced settings. Set the fimath Product mode and Sum mode to KeepLSB. These settings models the behavior of integer operations in the C language.

  4. In the Fixed-Point Conversion tool, click Run Simulation and verify that the overflow_test file is selected as the test file to run and then click the Run Simulation button.

    The simulation runs and the conversion tool displays simulation minimum and maximum ranges on the Variables tab. Using the simulation range data, the software proposes fixed-point types for each variable based on the default type proposal settings, and displays them in the Proposed Type column. The Validate Types option is now enabled.

  5. To validate the build using the proposed types, click Validate Types.

    The software validates the proposed types, displays a Validation succeeded message, and enables the Test Numerics option.

    If the errors or warnings occur during validation, they are displayed on the Type Validation Output tab. For more information, see Validating Types.

Test Numerics and Check for Overflows

  1. Click Test Numerics, select Use scaled doubles to detect overflows, and then click the Test Numerics button.

    The tool runs the test file that you used to define input types to test the fixed-point MATLAB code. Because you selected to detect overflows, it also runs the simulation using scaled double versions of the proposed fixed-point types. Scaled doubles store their data in double-precision floating-point, so they carry out arithmetic in full range. They also retain their fixed-point settings, so they are able to report when a computation goes out of the range of the fixed-point type.

    The simulation runs and the tool detects an overflow which it reports on the Overflow tab.

    Overflow error in expression 'acc + b( j )*z( k )'. Percentage of Current Range = 103.52%.
  2. Click the overflow message. The tool highlights the expression that overflowed in the code window.

    acc + b( j )*z( k )
  3. Determine whether it was the sum or the multiplication that overflowed.

    In the Advanced settings, set Product mode to FullPrecision, and then click Test Numerics.

    The overflow still occurs, indicating that it is the addition in the expression that is overflowing.

Was this topic helpful?