USER'S GUIDE
============

Table of Contents
-----------------
0. Introduction
1. Quick user's guide
2. Introducing the DFP windows
   2.1. Primary windows
        2.1.1. [DFP: Navigator]
               2.1.1.1. Menu Options
        2.1.2. [DFP: Display]
               2.1.2.1. Menu Options
   2.2. Secondary windows
        2.2.1. [DFP: Type and Specifications]
        2.2.2. [DFP: Design Method]
        2.2.3. [DFP: Implementation]
               2.2.3.1. [Filter Realization]
               2.2.3.2. [Filter Coefficients]
        2.2.4. [DFP: Output Format]
               2.2.4.1. [Transfer to MATLAB Workspace]
               2.2.4.2. [Generate Filter Code]
   2.3. Tertiary windows
        2.3.1. [DFP: File I/O]
        2.3.2. [DFP: Properties]
        2.3.3. [DFP: About]  
        2.3.4. Snapshot Windows
               2.3.4.1. Menu Options

3. Recommended screen layout
4. Useful hints
A. Appendix A: Code generation
   A.1: Motorola DSP56k family


0. INTRODUCTION
===============

MATLAB and in particular the MATLAB Signal Processing Toolbox contains
almost all the functions required to design various FIR and IIR filters.
Yet, unless one spends a good deal of time familiarizing oneself with the
syntax of how to use these functions, one barely does possess the
knowledge to tap into this vast resource.  This observation is particularly 
true in a classroom setting.  An instructor has only a limited time, usually 
a semester, to teach a course on digital signal processing including the 
design of digital filters.   The students usually do not have access to the 
MATLAB user guides.  The students may learn the proper syntax of how to 
use the digital filter functions.  But, unless one uses these functions 
continuously, the syntax is easily forgotten.

   The Digital Filter Package (DFP) is an attempt to harness the power of
MATLAB and its Signal Processing Toolbox.  It provides the user with an
environment where digital filter design concepts can be illustrated with
minimal training.  Even if users have not used DFP for a long time, they
should be able to design a digital filter on their own with minimal
guidance.  The user then has the option to save the filter coefficients
in various formats, or alternatively to generate filter code directly.

   I would like to emphasize, that a package such as DFP presents the
user with a very restricted view of the underlying resources.  I
strongly encourage the interested user to learn more about the MATLAB 
and the Signal Processing Toolbox functions.  By doing so, they can easily 
surpass the present filter design capabilities offered by the DFP.



1. QUICK USER'S GUIDE
=====================

The following example illustrates the steps required to design a simple
filter.  In particular, consider that you want to design a lowpass FIR filter 
using the Parks-McClellan optimal equiripple design method (Remez exchange 
algorithm).  The filter will be implemented as a direct form (polynomial) 
filter on a fixed point DSP where data on the target DSP is represented
in 24 bit fractional, two's complement format.

  In the [DFP: Navigator] window
  ------------------------------
   1. Click on the [DESIGN] pushbutton.
   2. Click on the [TYPE/SPEC] checkbox.

  In the [DFP: Type and Specifications] window
  --------------------------------------------
   3. Select [LOW PASS] from the pop-up menu at the top of the window.
   4. Enter the filter parameters into the editable text fields.
   5. When data entry is complete, click on the [APPLY] pushbutton.

  In the [DFP: Design Method] window
  ----------------------------------
   6. Select the [REMEZ] radiobutton.
   7. Click on the [APPLY] pushbutton.
   8. Click on the [CLOSE] pushbutton.

  In the [DFP: Navigator] window
  ------------------------------
   9. Click on the [IMPLEMENT] pushbutton.
  10. Click on the [REAL/QUANT] checkbox.

  In the [DFP: Implementation] window
  -----------------------------------
  11. Select the [POLYNOMIAL] radiobutton in the [FILTER REALIZATION] part.
  12. Select the [FIXED POINT] option from the pop-up menu in the 
      [FILTER COEFFICIENTS] part.
  13. Enter 24 for the [NUMBER OF BITS].
  14. Enter 0 for the [INTEGER BITS].
  15. Select the [TWO'S COMPLEMENT] radiobutton.
  16. Click on the [APPLY] pushbutton.
  17. Click on the [CLOSE] pushbutton.

  In the [DFP: Navigator] window
  ------------------------------
  18. Click on the [O/P FORMAT] checkbox.

  In the [DFP: Output Format] window
  ----------------------------------
  19. Make the appropriate choices and click on the [APPLY] button.

Congratulations, you have completed your first DFP design.  The DFP filter 
design recipe is simple: start DFP, click on the [DESIGN] pushbutton in the 
figure titled [DFP: Navigator] and make the appropriate choices on the 
DFP windows that open on the screen.   To specify an implementation 
method or to quantize filter coefficients, or to generate filter code, 
press the [IMPLEMENT] pushbutton on the [DFP: Navigator] and then activate 
the [REAL/QUANT] or the [O/P FORMAT] checkboxes to open the corresponding
DFP windows.


2. INTRODUCING THE DFP WINDOWS
==============================

The user interacts with DFP through a series of windows.  These windows
are divided into three major groups:

    Primary windows:   [DFP: Navigator]
                       [DFP: Display]

    Secondary windows: [DFP: Type and Specifications]
                       [DFP: Design Method]
                       [DFP: Implementation]
                       [DFP: Output Format]

    Tertiary windows:  [DFP: File I/O]
                       [DFP: Properties]
                       [DFP: About]

2.1. PRIMARY WINDOWS
====================
The DFP functionality is centered about the two primary windows
[DFP: Navigator] and [DFP: Display].


2.1.1. [DFP: Navigator]
=======================
This window is the command centre for the DFP.  The DFP user typically 
interacts with the [DFP: Navigator] window to navigate through the design 
and implementation processes.   All the other windows can be opened and
closed through the GUI objects in the [DFP: Navigator] window.

    At the startup the user first sees with the [DFP: Navigator] window.
The initial [DFP: Navigator] window appears on your computer screen 
as shown in Figure 1.

      +======================================================+
      [ DFP: Navigator                                       ]
      [======================================================]
      [ File   Window   Help                                 ]
      [------------------------------------------------------]
      [                                                      ]
      [         +----------------------------------+         ]
      [         |                                  V         ]
      [   +----------+     +-----------+     +-----------+   ]
      [   |  DESIGN  |---->|  DISPLAY  |<----| IMPLEMENT |   ]
      [   +----------+     +-----------+     +-----------+   ]
      [         ^                                  |         ]
      [         +----------------------------------+         ]
      [                                                      ]
      +======================================================+

     Figure 1: Initial appearance of the [DFP: Navigator] window


Figure 2 shows how the [DFP: Navigator] window will appear in its fully
expanded form with all the frames visible.


      +==============================================================+
      [ DFP: Navigator                                               ]
      [==============================================================]
      [ File   Window   Help                                         ]
      [--------------------------------------------------------------]
      [                                                              ]
      [   +-------------+     +-------------+     +--------------+   ]
      [   |    FILTER   |-----|    DISPLAY  |---->|   IMPLEMENT  |   ]
      [   +-------------+     +-------------+     +--------------+   ]
      [   |             |     |   Magnitude |     | o Real/Quant |   ]
      [   | o Type/Spec |---->|   Phase |v| |<----| o O/P Format |   ]
      [   | o Method    |     | o PoZe/Coef |     |              |   ]
      [   |             |<----|             |-----|              |   ]
      [   +----------- -+     +-------------+     +--------------+   ]
      [                                                              ]
      +==============================================================+

         Figure 2: Expanded view of the [DFP: Navigator] window


The block diagram which appears in the [DFP: Navigator] window is a 
paradigm for the design and implementation of a digital filter.   One 
designs a filter, displays the results, selects an implementation format, 
displays the results again.  If the design specifications are not met, 
one goes back to the design stage to modify the original design parameters.
This interplay between the design and implementation stages continues 
until all filter constraints are satisfied.   

    Figure 3 presents a signal flow diagram which illustrates how the 
secondary and tertiary DFP windows are linked to the UIMENU objects and 
to the pushbuttons on the [DFP: Navigator] window.


 +===[DFP: Navigator]===================================+   (through UIMENU)
 [                                                      ]-->[DFP: Properties]
 [   +----------+     +-----------+     +-----------+   ]-->[DFP: About]
 [   |  DESIGN  |---->|  DISPLAY  |<----| IMPLEMENT |   ]<--------+
 [   +----------+     +-----------+     +-----------+   ]         |
 [      |                                 |             ]         |
 +======|=================================|=============+         |
        |                                 |                       |
        |                                 |                       |
     [DFP: Type and Specifications]     [DFP: Implementation]     |
        |                                 |                       V
     [DFP: Design Method]               [DFP: Output Format]-->[DFP: File I/O]
                                          |                       ^
                                          |                       |
                                          V                       V
                                 +==================+  +================+
                                 | MATLAB Workspace |  | OS File System |
                                 +==================+  +================+


           Figure 3: Interrelation between the the DFP windows


2.1.1.1.  Menu Options
======================
The user initiates a number of DFP operations through the uimenu objects
that appear at the top of the [DFP: Navigator] window.  There are three
top menu choices: [FILE], [WINDOW] and [HELP].

  [FILE] This menu allows the user to initiate major DFP operations,
         including exiting from DFP and from MATLAB.  The individual
         menu, submenu selections and the operations associated with 
         each is explained below.
     [FILE]-[OPEN...] 
            This menu option initiates the tertiary window
            [DFP: File I/O] which allows DFP to interactively retrieve a 
            filename by displaying a dialog box.  DFP saves filter files in
            MATLAB MAT-file format.  The dialog box opens in the
            DFP_Directory if specified or in the MATLAB present working 
            directory if DFP_Directory = ''.  It displays all the MAT-files
            in that directory and prompts the user to make a selection.
     [FILE]-[SAVE...]
            This menu option again initiates the tertiary
            window [DFP: File I/O].  The default directories are identical 
            to the [FILE]-[OPEN...] menu option.   The DFP filter files are
            saved as MAT files.  Note that the [SAVE] option is disabled
            until the user completes a filter design.
     [FILE]-[CLEAR] 
            clears the present DFP workspace and the current design.
     [FILE]-[PROPERTIES] 
            this is the entry to a submenu which allows the
            user to customize DFP or restore default values.
            [FILE]-[PROPERTIES]-[CUSTOMIZE...] 
                   This submenu selection opens the tertiary DFP window 
                   [DFP: Properties].  For further information on how to 
                   customize DFP refer to Section 2.3.2.
            [FILE]-[PROPERTIES]-[DEFAULT VALUES] This submenu restores the
                   global default values given in DFPRCDEF.M file.  This 
                   submenu selection also saves the global default values 
                   specified in the DFPRCDEF.M file to the user customization 
                   file DFPRC.M.
     [FILE]-[CLOSE DFP]
            Closes DFP by deleting all DFP associated global variables
            and by closing all DFP windows.  Any user generated figure
            windows, user variables, or DFP variables transferred to the
            base MATLAB workspace are unaffected.    
     [FILE]-[EXIT MATLAB]
            Exits completely from MATLAB.  BEWARE THAT THERE IS NO
            WARNING BEFORE THIS COMMAND IS EXECUTED.


  [WINDOW] This menu options presents another way of navigating through
        the DFP windows.  When the user selects the [WINDOW] menu, its
        displays open (visible) DFP windows as menu items.
        Clicking on any one one brings that DFP window to the
        foreground.

  [HELP] This is the menu through which help files can be accessed, that
        is in a future release of DFP.  Until that time the only way to
        obtain further information on DFP is by reading through the
        *.txt files in the DFP_ROOT/doc directory or by typing 
        "help name-of-the-Mfile" at the MATLAB prompt.
     [HELP]/[ABOUT...] When the user makes this menu selection a new 
        window pops up which prints information about the current release 
        of DFP.  This information includes the version number, the release 
        date, authorship and a copyright notice.


2.1.2. [DFP: Display]
=====================
The [DFP: Display] window displays the relevant characteristics of the 
digital filter being designed.  The filter characteristics are broadly
grouped into BASIC and EXPANDED categories as shown in Figure 4.

   E--B--------------------------------------------------------------
   X  A   o Desired magnitude response (target);
   P  S   o Magnitude response resulting from the current design;
   A  I   o [Phase response] or [Group delay] or [Impulse response]
   N  C     resulting from the current design.
   D  --------------------------------------------------------------- 
   E      o Pole-zero diagram
   D      o Filter coefficients
   ------------------------------------------------------------------

      Figure 4:  Information displayed in the [DFP: Display] window


To open the [DFP: Display] window the user must press the [DISPLAY]
pushbutton on the [DFP: Navigator] window.  The basic [DFP: Display]
window displays only the target together with the magnitude and phase 
response plots corresponding the current design in order to minimize 
on-screen clutter.  To switch to the expanded [DFP: Display]
window mode, where the pole-zero plot and the filter coefficients are
also visible, the user must activate the [POZE/COEFF] checkbox on the
[DISPLAY] frame in the [DFP: Navigator] window.  This frame is only
visible is the [DFP: Display] window is visible on screen.

    All the other [DFP: Display] options and features are self
explanatory.  Note the status line in the [DFP: Display] window,
located just below the UIMENU objects. The status line has four fields
which display current filter design and implementation parameters:

 [1st field]: Filter type (LPF/HPF/BPF/BSP/ ...)
 [2nd field]: Filter design method (FIR/IIR ...)
 [3rd field]: Realization format (Polynomial/Lattice/Second Order Sections)
 [4th field]: Coefficient format (Float/Fixed point [n,m,f]), where
                n = total number bits used to quantize filter coefficients,
                m = number of integer bits,
                f = quantizer representation with
                    f = t --> two's complement,
                    f = u --> unsigned integer.

    The user can open the [DFP: Display] window by pressing the large
[DISPLAY] pushbutton shown in Figure 1.  Conversely, the user can
close the [DFP: Display] window by pressing the smaller [DISPLAY]
pushbutton which appears on top of the Display frame in the middle of
the [DFP: Navigator] window.


2.1.2.1.  Menu Options
======================
The [DFP: Display] window has a dynamically changing menu structure.
The basic-expanded [DFP: Display] view selection and the choice of secondary
filter response plot determine which menus are visible at any given time.
The filter coefficient format also enables and disables certain
[COEFFICIENT] menu selections.

  [MAGNITUDE] This is main menu which houses all the options that affect
      the filter magnitude plot.

      [MAGNITUDE]-[DB]/[LINEAR].  The [DB]/[LINEAR] menu options allow the
          user to toggle between a logarithmic an linear vertical scale
          for the filter magnitude response.   These two menu options
          are mutually exclusive.  Switching between the two scale modes
          affects both the filter magnitude response and the filter
          target plots.  Please note that NOT all filter types have a target 
          display in both the logarithmic and the linear scale mode.  In 
          the current DFP release the differentiator has only a linear
          target display.

      [MAGNITUDE]-[TARGET].   This menu option turns the display of the
          filter target on or off.  It acts as a toggle switch.  The
          target associated with a design is generated when the user
          first enters the filter type and filter specifications in the
          [DFP: Type and Specifications] window.

      [MAGNITUDE]-[GRID]  This menu toggles between the "grid on" and
          "grid off" states.

      [MAGNITUDE]-[LIMITS...]  The user can zoom into the magnitude plot
          by clicking with the left mouse button or by clicking, holding
          and dragging the rubberbox with the left mouse button in the 
          magnitude plot.  The user has also the option to interactively
          enter the horizontal and vertical display limits.  Selecting
          this menu option opens a dialog box which displays the current
          axis limits and invites the user to change the display limits
          as required.


  [SECONDARY] The [DFP: Display] window shows a secondary plot
      immediately below the magnitude plot.  The user can specify the
      secondary plot through the pop-up menu on the [DISPLAY]
      frame in the [DFP: Navigator] window.  In particular, the user has
      the option of displaying the phase response, the group delay
      function or the filter impulse response.  Depending on the position
      of this pop-up menu, the label of the secondary plot menu changes
      to reflect the secondary plot selection, i.e., the menu label changes
      to [PHASE] or [GDELAY] or [IMPULSE].  

      [PHASE] If the secondary plot is the phase plot the following menu
          selections are available.

          [PHASE]-[RADIANS]/[DEGREES].  The [RADIANS]/[DEGREES] menu
              options allows the user to toggle between displaying the
              phase response measured in radians or in degrees.  These
              two menu options are mutually exclusive.

          [PHASE]-[WRAP]/[UNWRAP].  The [WRAP]/[UNWRAP] menu options
              allows the user to display the phase response with phase
              wrapped or unwrapped format.  If the [WRAP] option is on
              the phase values are limited to the interval [-pi,pi], if
              [RADIANS] menu is on, or to the interval [-180,180], if the
              [DEGREES] menu is on.

          [PHASE]-[GRID]. Same as the [MAGNITUDE]-[GRID] menu.

          [PHASE]-[LIMITS...]. Same as the [MAGNITUDE]-[LIMITS...] menu.

      [GDELAY] or [IMPULSE].  If the user specifies either the group delay
          or the impulse response plots the secondary menu options will
          change to include the following selections.

          [GDELAY] or [IMPULSE]-[128]/[256]/[512]/[1024]/[OTHER...].
              Through these mutually exclusive menu options the user can
              specify to display the group delay or the impulse response
              plots using the specified number of points.   If a
              different number of points than those specified by the
              menu [128]/[256]/[512]/[1024] options is desired, then
              selecting the [OTHER...] option opens a dialog box,
              through which can enter any number of points.

          [GDELAY] or [IMPULSE]-[GRID]. Same as the [MAGNITUDE]-[GRID] menu.

          [GDELAY] or [IMPULSE]-[LIMITS...].Same as the [MAG]-[LIMITS...] menu.


      [COEFFICIENTS] This menu is visible only if the [DFP: Display] window 
          is in its expanded form.  The lower right portion of the 
          [DFP: Display] window displays the filter coefficients in one
          or more scrollable text fields.  The default coefficient
          format is floating point.  If the user has converted
          the filter coefficients into a fixed point format, the the
          [HEX], [OCTAL] and [BINARY] menu options are enabled.  Selecting
          any one of the menu options changes the filter coefficients in
          the scrollable text windows into the specified format.  This
          format change affects only the display and not the internal
          representation of the filter coefficients.

          [COEFFICIENTS]-[FLOAT]/[HEX]/[OCTAL]/[BINARY].  These are the
              mutually exclusive filter coefficient format menu options
              that are enabled by coefficient quantization.

      [SNAPSHOT] This is the menu through which the user may take the
          snapshot, i.e., transfers a specified plot into a separate
          figure window.  The menu options change as a function of the
          plots visible on the [DFP: Display] window.

          [SNAPSHOT]-[MAGNITUDE].  This menu option takes a snapshot of
              the filter's magnitude response.

          [SNAPSHOT]-[PHASE]/[GDELAY]/[IMPULSE].   This menu option takes
              a snapshot of the filter's phase response, or its group
              delay or its impulse response depending on the secondary
              plot selection.

          [SNAPSHOT]-[POLE-ZERO].  This menu option takes a snapshot of
             the of the filter's pole-zero plot.   This menu option is
             visible only in the expanded [DFP: Display] view.



2.2. Secondary windows
======================
The secondary windows appear on the screen as required.  Certain actions
trigger DFP, such that an appropriate secondary window becomes visible.
For example, after one completes the filter specifications in the
[DFP: Type and Specifications] window and indicates that data is ready
to be processed by pressing the [APPLY] pushbutton, DFP activates the 
[DFP: Design Method] window and prompts the user to select a design method.
The user can manually open or close all the DFP windows except the 
[DFP: Navigator] through the corresponding GUI elements in the 
[DFP: Navigator] window.

    All secondary DFP windows can be closed by pressing the [CLOSE]
pushbutton which is always located at the bottom of the secondary
windows.  The user can open and close secondary DFP windows by
toggling the corresponding checkboxes in the [DFP: Navigator] window.


2.2.1. [DFP: Type and Specifications]
=====================================
In the [DFP: Type and Specifications] window the user first selects the 
type of filter (LPF/HPF/...) using the pop-up menu.   In the current
release of DFP the following filter types are supported.
    1. Lowpass filter,
    2. Highpass filter,
    3. Bandpass filter,
    4. Bandpass filter,
    5. Hilbert transformer,
    6, Differentiator.
Then, the user enters filter specifications, such as sampling rate, 
pass-band and stop-band edge frequencies, minimum and maximum allowed 
attenuation levels.  Each filter type has a different set of specifications.
Once the user makes a selection form the pop-up menu, the filter 
specifications fields are set up according to the filter type.

    The filter specifications entered in the editable text fields are
communicated to DFP only after the user presses the [APPLY] pushbutton.


2.2.2. [DFP: Design Method]
===========================
The user first enters the filter specifications into the editable text
fields in the [DFP: Type and Specifications] window.  The user then
proceeds to specify the desired filter design method.  In particular, 
the user must select an FIR or an IIR filter and the specific filter 
approximation method to be used under the selected category.  The available 
filter design methods are:

    FIR: Parks-McClellan optimal equiripple design (Remez).
         Windowed FIR design using Kaiser-Bartlett-Blackmann-Hamming-
            Hanning-Boxcar window functions.
         Least squares error minimization design.

    IIR: Butterworth approximation.
         Chebychev-I approximation (equiripple in passband).
         Chebychev-II approximation (equiripple in stopband).
         Elliptic approximation (equiripple in both bands).

For windowed FIR design the user selects the window type from the pop-up
menu choices.   The filter design method radiobuttons are mutually
exclusive.  The design method is communicated to DFP only by pressing the 
[APPLY] pushbutton.

    DFP estimates the minimum required filter order corresponding to
each design method such that (in all likelihood) a filter with that
order will satisfy the filter specifications entered in the 
[DFP: Type and Specifications] window.   Note that to the right of 
design method radiobuttons there are two columns.  The left column
titled [ORDER-SET] contains editable text fields, and the right column
titled [ORDER-ESTIMATE] contains texts with DFP estimated filter order
values.  On color monitors the entries in the [ORDER-ESTIMATE] are shown
in blue.  Initially, the [ORDER-SET] column values are set equal to 
the [ORDER-ESTIMATE] values.  These represent "reasonable" initial values in
the design process.   The filter order estimates represent best
guesses as determined by the filter order estimation algorithms.
Therefore, the user must verify the filter design by observing the plots
in the [DFP: Display] window.  If the user wants to manually change the
filter order this can easily be accomplished by entering the desired
filter order in the editable text field immediately to the right of the
corresponding radiobutton.

    For bandpass and bandstop filters, the real IIR filter orders are
twice of what is shown in the [ORDER-SET] and [ORDER-ESTIMATE] columns.  
This can be changed such that they show the real filter orders, but I 
decided to follow the MATLAB convention.


2.2.3. [DFP: Implementation]
============================
The [DFP: Implementation] window is divided into two separate areas.
The following sections delineate the functionality of each sub-window.

2.2.3.1. Filter Realization
===========================
The [Filter Realization] area appears in the upper half of the 
[DFP: Implementation] windows.  It presents the user with the following
options:

   FIR filters: Polynomial,
                Lattice.
   IIR filters: Polynomial,
                Lattice,
                Cascade of second order sections (biquads).

The polynomial form is the default realization format for FIR and IIR 
filters.  The filter realization options are mutually exclusive.  The 
magnitude response plots that appear in the [DFP: Display] window represent 
the characteristics of the filter in the specified realization format.
The user should note, however, that the magnitude response plots are 
generated by the MATLAB function FREQZ which expects the filter to be 
in polynomial format.  As an example, let us consider an IIR filter that 
the user wants to implement in a lattice format.  Once the user communicates 
the selection by pressing the [APPLY] button in the [DFP: Implementation] 
window, DFP performs the following operations:

    1. DFP generates the reflection (K coefficients) and the (C
       coefficients) from the internal DFP arrays representing the 
       numerator (B0 coefficients) and denominator (A0 coefficients) 
       polynomials using the DFP function POLY2LAT.

    2. DFP converts the K and C coefficients back to polynomial format
       using the DFP function LAT2POLY.  Let us refer to the "new"
       polynomial coefficients as B1 and A1 coefficients.

    3. Using the "new" B1 and A1 polynomial coefficients, DFP calls the 
       MATLAB function FREQZ which in turn generates the magnitude and
       the pole-zero plots in the [DFP: Display] window.  The K and C 
       coefficients are also displayed in the [DFP: Display]/Coefficients 
       sub-window.

For IIR filters the user has the additional option of implementing the
filter as a cascade of biquad (second order) sections.  This realization
format has the advantage that for a stable and minimum phase IIR filter the
magnitude of all the A and B coefficients in every biquad section will
be less than two.  With proper scaling such filters can be easily
implemented on fixed point DSP architectures.  

   To generate the biquad coefficients, DFP first converts the A0-B0 
polynomials into an equivalent pole-zero format, and then converts to biquad
format using the MATLAB/Signal Processing Toolbox function ZP2SOS.  When 
DFP generates the biquad-sections it uses the default [DISTRIBUTE GAIN] 
option, such that "... the maximum of the transfer function of the first N 
sections in cascade is less than 1, and the product of all the biquad gains 
equals to the overall filter gain.".  For further information please 
refer to the MATLAB/Signal Processing Toolbox Manual.  Alternatively,
the user can select [DO NOT DISTRIBUTE GAIN] option, in which case the
gain of each biquad section equals unity.  There is a non-zero gain
which has to be used with unity gain biquad sections if the user wants
to preserve the original filter gain.

   For an odd order filter the first biquad coefficients b(1,3) = a(1,3) = 0.
This represents a "degenerate" biquad section.


2.2.3.2. Filter Coefficients
============================
The filter coefficients, i.e., the A0-B0 coefficients are first
generated in the default MATLAB double-precision floating point.  
The user can optionally convert the filter coefficients into a fixed point
representation.  

    Immediately below the label entitled [FILTER COEFFICIENTS] there is
pop-up menu which allows the user to toggle between the default floating 
point and the fixed point formats.  If a user selects the fixed point
format, further options are enabled.   In particular, the user can
specify the length of the fixed point format (expressed in number of
bits) and the number of integer bits.  Furthermore, the fixed point
representation can be either in two's complement or in unsigned integer
format.  DFP quantizes filter coefficients using the DFP function
D_QUANT.  For further information on the quantizer characteristics the
user is referred to the online help facility.

    When the user selects a fixed point format and if the realization format 
is POLYNOMIAL, DFP quantizes the A0-B0 coefficients and generates the 
polynomials, A0q and B0q.  For non-polynomial realizations, DFP first 
converts the A0 and B0 coefficients into the specified realization format 
and then quantizes those coefficients.  For example, for an IIR filter in 
lattice format, DFP determines the quantized Kq and Cq coefficients.



2.2.4. [DFP: Output Format]
===========================
The DFP window [DFP: Output Format] is divided into two sub-windows.  
The user can transfer filter coefficients to the MATLAB workspace for
further processing.  The user can also generate filter macro or full
code for a number of target DSPs.  Version 1.0 of DFP supports only
the Motorola DSP56k family.   Future versions of DFP will support
additional DSP families and C language.

2.2.4.1. Transfer to MATLAB Workspace
=====================================
In the top subwindow titled [Transfer to MATLAB Workspace] there are
three checkboxes and to their right there are three editable text fields.
Each pair consisting of a checkbox and an editable text field, is for a
filter realization format: polynomial, lattice and cascade of biquad
sections (if the filter is an IIR filter).

    If the user wants to transfer the filter coefficients corresponding
to a particular realization format from the internal DFP workspace to the 
MATLAB base workspace, then the user has to first enter (or modify)
array names in the editable text field.  The number of array names required 
for different filter realization formats and their respective order is as 
indicated:

    [FIR]
         Polynomial  format:  2, numerator and denominator coefficients;
         Lattice     format:  1, K-coefficients;
         Cascade of biquads:  not applicable, disabled by DFP.

    [IIR]
         Polynomial  format:  2, numerator and denominator coefficients;
         Lattice     format:  2, K- and C-coefficients;
         Cascade of biquads:  2, second order section coefficients array
                              and the gain factor.

Array names must be legitimate MATLAB array names.  If more than one array 
name is required, the array names must be separated by space, " ", or 
by comma, ",".   Sufficient number of array names must be entered, otherwise
DFP will generate an error message.  The order of the array names must
conform to the above list.

    After entering or modifying the required array names in the editable
text fields, the user must select the checkboxes corresponding to the
filter realization formats that are to be transferred to the MATLAB
workspace.  The user must be aware of the following rules:

    o The [Polynomial] option is always available.
    o The [Lattice] option is only available if the user has already selected
      the [Lattice] radiobutton in the [DFP: Implementation] window.
    o The [2nd order sections] option is only available if the filter is an
      IIR filter and if the user has already selected the [2nd order sections]
      radiobutton in the [DFP: Implementation] window.
    o More than one checkbox can be selected.
    o It the user's responsibility to avoid duplication of array names.
    o If duplicate array names are specified, the latter one overwrites
      the earlier one.
    o Transfer to MATLAB workspace does not take place until the user
      presses the [APPLY] pushbutton in the [DFP: Output Format] window.

The arrays transferred to the MATLAB workspace reflect the implementation
choices made by the user.  For example, for an IIR filter implemented in
a lattice format with 16-bit, two's complement fixed point coefficients,
the lattice arrays transferred to the MATLAB workspace are the quantized
K and C coefficients.

WARNING:  There is an important exception to the above rule.  This exception 
is best illustrated by an example.  Consider an FIR filter, which has been 
converted to a lattice format.  Also assume that the filter coefficients are 
in a fixed point format.  DFP has already generated the following filter 
arrays (the terms in brackets indicate their numeric format):

    o A and B coefficients representing the denominator and the
      numerator polynomials, respectively (floating point);
    o K coefficients for the FIR lattice (floating point);
    o Kq coefficients derived from K coefficients by quantizing them in
      the user specified format (fixed point);
    o Aq and Bq coefficients derived from Kq by converting Kq back to a
      polynomial format via the function LAT2POLY (floating point).

Consider the following scenario.  In the [DFP: Output Format] window the 
user enters "b,a" into the first editable text field and selects the 
[POLYNOMIAL] checkbox; the user also enters "k" into the second editable 
text field and selects the [LATTICE] checkbox.  When the user presses the 
[APPLY] pushbutton, DFP generates the arrays "b", "a" and "k" in the MATLAB 
base workspace such that b = Bq, a = Aq, and k = Kq.  The "k" array indeed 
contains the quantized lattice coefficients, whereas the "b" and "a" arrays 
are NOT the quantized numerator and denominator coefficients.  If the
user wants to generate the correct quantized numerator and denominator
coefficients, the proper procedure is to first select the [POLYNOMIAL] 
radiobutton and the [FIXED POINT] option in the [DFP: Implementation] window 
and then transfer the polynomial coefficients to the MATLAB workspace.
If this procedure is correctly implemented, the user should notice that
the only enabled transfer option in the [DFP: Output Format] window is
the [POLYNOMIAL] checkbox.


    The format associated with each transfer array is as shown:

    [POLYNOMIAL]
       "num" and "den" are N-by-1 row vectors,
           num = { b(1), b(2), ..., b(N) },
           den = { a(1), a(2), ..., a(N) },
       where a(1) always equals to 1, and for FIR filters den = 1.

    [LATTICE]
       "K" is a N-by-1 row vector representing the lattice reflection 
       coefficients 
           K = { k(1), ..., k(N) },
       and the array "C" is a (N+1)-by-1 row vector representing the C
       coefficients for an IIR filter, such that
           C = { c(1), ..., c(N+1) }.   

    [2nd ORDER SECTIONS]
       The "sos" array is a L-by-6 array 
          sos = [ b(1,1) b(1,2) b(1,3) a(1,1) a(1,2) a(1,3) 
                  b(2,1) b(2,2) b(2,3) a(2,1) a(2,2) a(2,3)
                  ....
                  b(L,1) b(M,2) b(M,3) a(L,1) a(L,2) a(L,3) ],
       and the "gain" parameter is a scalar variable, where L = fix(N/2)*2.
       If the [DISTRIBUTE GAIN] option has been selected gain = 1, and 
       a(l,1) = 1, for l = 1,...,L.  If the [DISTRIBUTE GAIN[ has been
       set to [NO] then the "gain" parameter may have a non-unity value,
       and b(l,1) = a(l,1) = 1, l = 1,...,L.


2.2.4.2. Generate Filter Code
=============================
The [GENERATE FILTER CODE] sub-window in the [DFP: Output Format] window
allows the user to specify whether DFP should generate filter code.
The main code generation choices are specified through the pop-up menu
immediately below the [GENERATE FILTER CODE] label.  By default this
pop-up menu is set to [DO NOT GENERATE CODE] option.  If the user
selects this option, further [GENERATE FILTER CODE] GUI objects are
disabled.  

    When the user instructs DFP to generate filter code, the resulting
code corresponds to the current implementation format.  For example, if
the IIR filter is realized as a cascade of 2nd order sections then the
DFP generated code will implement the filter as a cascade of 2nd order
sections.

    NOTE: The Motorola assembler code generated by DFP are modified
versions of the filter library taken from the Motorola DSP bulletin
board.  Here is the the disclaimer that comes with these filters:
"This program originally available on the Motorola DSP bulletin board.
It is provided under a DISCLAIMER OF WARRANTY available from
Motorola DSP Operation, 6501 Wm. Cannon Drive W., Austin, Tx., 78735."

    DFP Version 1.0 supports code generation only for the Motorola DSP56k 
family of fixed point processors.  The top pop-up menu selection 
[MOTOROLA DSP56k ASSEMBLER] enables this option.  The code generation 
[OPTIONS] pop-up menus present the following code generation options:

    [1st pop-up menu]
    =================
       [MACRO CODE]  This option generates filter code that is
          implemented in macro format. For a demonstration of such
          filter macros are used please see the "*_macro.asm" and the
          associated "*_coef.asm" files in the 
          DFP_ROOT/codegen/mot56k/samples/ directory.  In this directory
          the "*_coef.asm" files are DFP generated macro files.

       [FULL CODE]  This option generates full in-line assembler code,
          such that when the DFP generated assembler code file is
          assembled it can be run directly on a Motorola DSP56k family of 
          fixed point DSP.  For a sample of full-length filter code please 
          see the "*_full.asm" files in the 
          DFP_ROOT/codegen/mot56k/samples/ directory.  In this directory
          the "*_full.asm" files are DFP generated full in-line
          assembler code files.


    [2nd pop-up menu]
    =================
       [COEFF: Float]  This option specifies a floating format for the
          filter coefficients in the DFP generated macro or full
          Motorola assembler code.

       [COEFF: Hex]  This option specifies a hexadecimal format for the filter
          coefficients in the DFP generated macro or full Motorola assembler 
          code.  The syntax of hexadecimal format is compatible with Motorola 
          assembler (preceded by $).  This option is available only if the 
          filter coefficients have been previously quantized using the 
          [FIXED POINT] option in the [DFP: Implementation] window.

       [COEFF: Binary]  This option specifies a hexadecimal format for the 
          filter coefficients in the DFP generated macro or full Motorola 
          assembler code.  The syntax of hexadecimal format is compatible 
          with Motorola assembler (preceded by %).  This option is available 
          only if the filter coefficients have been previously quantized using 
          the [FIXED POINT] option in the [DFP: Implementation] window.


    [FILE NAME]
    ===========
          The user must specify a file into which DFP will write the
          macro or the full filter code.   The file name must be a legal
          file name for the particular operating system that is being
          used.  Alternatively, the user may click on the pushbutton
          labelled "..." immediately to the right of the editable text
          field.  This will trigger the UIPUTFILE dialog box, through
          which the user may specify the code file name.


2.3. Tertiary windows
=====================
Tertiary windows are generated and opened by DFP as required.  In contrast 
to the primary and secondary DFP windows the functions associated with the
tertiary windows DFP destroys these windows after the user completes 
data entry or option selection processes.  The only exception is the 
[DFP: Properties] window.  During the startup phase DFP does not generate 
this window.  Instead DFP generates this window only when the user first 
customizes the DFP properties.   When the use closes this window, its 
'visible' property is set to 'off'.  This choice is dictated by the 
relatively high MATLAB overhead associated with creating this window.)


2.3.1. [DFP: File I/O]
======================
DFP generates the [DFP: File I/O] windows by calling the built-in 
MATLAB functions UIGETFILE and UIPUTFILE.  These windows allow DFP to 
interactively retrieve a filename by displaying a dialog box.  The user
has the option of moving up or down the directory tree and view files
within each directory.   For further information about the UIGETFILE and
UIPUTFILE functions please use the on-line help facility.


2.3.2. [DFP: Properties]
========================
This is the primary interface to the user customizable features of DFP.
The [DFP: Properties] window is activated by the
[FILE]-[PROPERTIES]-[CUSTOMIZE] menu selection from the [DFP: Navigator]
window.  There are three major sets of user customizable features.
The user accesses these three sets through the large pop-up menu which
always appears on top of the three [DFP: Properties] screens.

[DFP COLORS]  The DFP colors customization screen is the first
   [DFP: Properties] screen.  This screen presents the user with a column 
   of pushbuttons on the left and a smaller pop-up menu on the right. The 
   labels on the pushbuttons refer to the DFP objects whose color properties 
   can be altered.  The label colors show their present settings.  If the 
   user wants to alter the color of a DFP object, then s/he first selects 
   a color form the right pop-up menu, and then clicks on the pushbuttons 
   with labels representing the DFP objects whose colors are to be set to 
   the color shown by the pop-up menu label.  If the user wants to specify 
   a color which is not directly available from the existing list of colors 
   in the pop-up menu, then s/he should select the last pop-up menu option 
   labeled [OTHER...].  This selection creates an editable text field 
   immediately below the pop-up menu into which the user can enter any 
   desired color as an RGB triplet. Each RGB triplet is a 3-by-1 row vector
   with space or comma delimited elements whose numeric values are between 
   0 and 1.  When the user modifies an object color its effect is instantly 
   reflected in the DFP windows.

[DIRECTORIES]
   In the second customization screen the user can specify three DFP 
   directories.   These directories are:

   DFP_Directory :   directory where the *.mat files reside.  The *.mat files
      generated by DFP contain all the information which allows the user to
      recreate the current design at some later time.  This directory is the
      reference point for the [FILE]-[OPEN...] or [FILE]-[SAVE...] uimenu
      selections in the [DFP: Navigator] window.

   DFP_SourceCodeDir :  if the user exercises the filter code generation 
      option then this directory serves as the reference directory for 
      storing the DFP generated filter code files.

   DFP_TemplatesDir  :  when the user asks DFP to generate filter code, DFP 
      simply combines a number of template files with the filter specific
      coefficient data.  This directory tells DFP where it should look for
      these essential template files.

   MATLAB requires that you specify directory names as strings.  Therefore, 
   please make sure that each directory name is given within single quotes as 
   a valid MATLAB string variable.  For example, to set the DFP_TemplatesDir 
   on a UNIX system to /usr/local/matlab/toolbox/dfp/templates the correct 
   syntax is: 
       DFP_TemplatesDir = '/usr/local/matlab/toolbox/dfp/templates/';

   When specifying the directories please make sure that the last
   character in each string variable is a proper file separator 
   for that particular OS.  For example, the last character should be 
   "/" or "\" on a UNIX system and on a DOS system, respectively:
   UNIX: DFP_TemplatesDir = '/usr/local/matlab/toolbox/dfp/templates/';
   DOS : DFP_TemplatesDir = 'c:\usr\local\matlab\toolbox\dfp\template\';

   If you specify a directory name as an empty string such as,
   DFP_Directory = ''; then MATLAB simply references the present
   working directory.  Thus, if you frequently find yourself using DFP from
   different directories, and if you want to keep the DFP generated files 
   separate from each other then a good strategy will be to set the two 
   directories, namely, DFP_Directory and DFP_SourceCodeDir to 
   the empty string, ''.

   In most cases, the user does not need to change the 
   "DFP_TemplatesDir", unless the user has customized the template
   files and keeps them in a separate directory.  


[OTHER]
   The third [DFP: Properties] screen allows the user to specify two DFP
   characteristics.  The first characteristics if the number of points DFP
   passes onto the MATLAB function FREQZ to generate the filter's frequency
   response plots.  The default value is 512.  512 is also the MATLAB
   default value for the function FREQZ.  A greater value will
   generate a more detailed view but it also takes longer to compute and
   requires more memory.  "It is best, although not necessary, to choose
   a value for this parameter, that is an exact power of two, because
   this allows fast computation using an FFT algorithm." 

   In its default mode, all DFP windows have their 'Resize' properties
   set to 'off'.  This means that they cannot be resized.  The user can
   change this property by selecting 'Off' or 'On' from the pop-up menu.


   At the bottom of the [DFP: properties] windows there are three
pushbuttons that are labeled from left to right [SAVE], [CANCEL] and
[CLOSE].   These pushbuttons allow the user to save the customization
values into a user set-up file or to cancel the changes implemented in
the present customization session.

   [SAVE]  When the user presses the [SAVE] pushbutton DFP saves the
      current settings of all the customizable DFP properties to the file
      DFPRC.M in the DFP_Directory.  If the DFP_Directory equals to the 
      empty string '', then DFPRC.M is generated in the present MATLAB 
      working directory.  Any previous DFPRC.M file is overwritten.   

      DFP uses two customization files: DFPRCDEF.M and DFPRC.M.   The 
      first one is the system-wide global initialization file.   When DFP 
      starts via the function DFP.M, it first reads DFPRCDEF.M, and then 
      checks whether there exists a file with the name DFPRC.M anywhere 
      in the MATLAB path. If DFPRC.M exists, DFP opens this file and any 
      directory or color definitions in the file DFPRC.M overrides the 
      global values specified in the DFPRCDEF.M.  Typically, each user 
      will keep his/her DFPRC.M file in his/her local MATLAB directory.
      The DFPRC.M file is time-stamped.

   [CANCEL]  When the user presses the [CANCEL] pushbutton, DFP restores
      all the user modifiable DFP parameters and properties to their 
      user specific default values as specified in the DFPRC.M script file.
      If DFP cannot locate the DFPRC.M file then it beeps, prints a warning
      message in the MATLAB command window and restores the default
      values from the global initialization file DFPRCDEF.M.   If during
      a customization session the user has earlier issued a [SAVE]
      command, then [CANCEL] restores the present DFP workspace to the point
      in time when the user has earlier issued the [SAVE] command.
      If the user wants to return to the global default values, this can
      be done through the [FILE]-[PROPERTIES]-[DEFAULT VALUES] menu
      selection in the [DFP: Navigator] window.  This menu selection
      will also save the global default values as specified in the 
      DFPRCDEF.M file to the user customization file DFPRC.M.

   [CLOSE]  This pushbutton closes the [DFP: Properties] window.


2.3.3. [DFP: About]
===================
When the user makes the [FILE]-[HELP]-[ABOUT...] menu selection in the
[DFP: Navigator] window a new window pops up which prints information
about the current release of DFP.  This information includes the version
number, the release date, authorship and a copyright notice.


2.3.4. Snapshot Windows
=======================
The DFP does not allow the user to customize the frequency response
plots, such as changing a plot title, in a straight-forward,
user-friendly manner.  Yet, it is quite possible that the user wants to 
alter certain characteristics of a plot.  DFP allows the user to take a
"snapshot" of the plots visible in the [DFP: Display] window. For example,
if the user has selected the expanded [DFP: Display] view with the GROUP 
DELAY secondary filter response plot, then the [SNAPSHOT] menu in the 
[DFP: Display] window presents the user with the option of taking separate 
snapshots of the magnitude, group delay and the pole-zero plots.  When the 
user makes a selection from the [SNAPSHOT] menu, DFP generates a new figure 
which has one axes containing a copy of the selected plot. The user can then
customize this figure window.

2.3.4.1. Menu Options
=====================
Each snapshot window has two menu selections [FILE] and [TIME STAMP]
which are briefly explained below.

  [FILE] 
     [FILE]-[PRINT...] 
        This menu selection opens a print dialog box, through which the
        user can specify the MATLAB print options.  The print dialog box
        has been written by D.L. Hallman <hallman@helmholtz.ecn.purdue.edu>.
     [FILE]-[CLOSE]
        This menu option destroys the snapshot window.
    
  [TIME STAMP]
     This menu allows the user to tag the current figure with a time and
     date stamp in the upper right corner.  The time stamp can be turned
     on or off through the mutually exclusive [TIME STAMP]-[ON] and
     [TIME STAMP]-[OFF] menu options.  The time-date functions have been
     written by Kevin G. Kohrt (dateme.m) and Uwe Petersen (timedate.m).




3. RECOMMENDED SCREEN LAYOUT
============================
DFP opens and closes many windows during a typical DFP session.  Even
with a large screen real estate, the screen may become cluttered. The
recommended screen layout is shown in Figure 5.

     +============================================================+
     [+------------------------++-----------------------------+   ]
     [| DFP: Navigator         || DFP: Display                |   ]
     [+------------------------++-----------------------------+   ]
     [|                        ||                             |   ]
     [|                        ||                             |   ]
     [+------------------------+|                             |   ]
     [+-----------------+       |    (Fully expanded)         |   ]
     [| DFP: secondary  |       |                             |   ]
     [+-----------------+       |                             |   ]
     [|                 |-----+ |                             |   ] 
     [|                 |     | |                             |   ] 
     [+-----------------+     | |                             |   ]
     [| MATLAB Command Window | |                             |   ]
     [|                       | |                             |   ]
     [+-----------------------+ +-----------------------------+   ]
     +============================================================+
     
              Figure 5: Recommended DFP screen layout

DFP has been programmed to place the [DFP: Navigator] window in the top
left corner of the screen.  The [DFP: Display] window opens immediately
to the right of [DFP: navigator] flush to the right border of the [DFP:
Navigator] window and flush to the top of the screen. The two primary
DFP windows occupy most of the screen with no overlap.  The secondary DFP
windows open below the [DFP: Navigator] window flush to the right of the
screen.  As DFP directs its error and warning to the MATLAB command
window, the user should keep the MATLAB command window visible on the
screen.  The recommended location for the MATLAB command window is the 
bottom left corner of the screen.

   DFP screen layout has been tested on 14", 17" and 21" monitors.
With all three monitors users have assessed the DFP screen layout as 
satisfactory.  Since these monitor sizes cover the majority of the monitors 
that are currently in use, it may not require further modifications.  
If you still find the default figure sizes unsatisfactory, you can set 
the [DFP FIGURE RESIZE] property to 'on' and modify the figure dimensions.   
Unfortunately, the modified figure sizes are session specific and cannot be 
carried to subsequent DFP sessions.  This may be a feature supported in 
future DFP releases.

   DFP attempts to maximize the height of the [DFP: Display] window to 
cover the entire screen height and most of the screen width to the right
of the [DFP: Navigator] window.  DFP calculates this information from
the root window SCREENSIZE property.   The proper, i.e., non-overlapping 
DFP window placement is also a function of the window frame and titlebar 
dimensions.  These dimensions are different for most operating systems and 
may have been further modified by individual users. I have not investigated 
whether this information can be determined in a universal way.  If you find 
that DFP is not very successful in eliminating window overlap you may want 
to experiment with the [DFP_WinBorderOffset] and [DFP_Offset3] dimensions 
which are defined in D_GLOBAL.M file.

   If your window manager has an automatic or random window placement option
(fvwm on UNIX computers is one), I would recommend that you turn it off.


4. USEFUL HINTS
===============

1. Never, ever attempt to close the DFP windows by DESTROYING them using
   your OS or window manager commands.  When you "close" a DFP window, DFP
   simply makes that window temporarily invisible.  All DFP functions 
   rely on the presence of DFP windows even if they are not visible on the
   screen.   If a DFP window has been destroyed, DFP will no longer be able 
   to locate the figure and its children, and therefore DFP will not be able 
   to extract the information it needs for its proper operation.  If this
   happens, the only cure is to exit DFP (the MATLAB command, 
   "close all; clear all" would do) and start again.

2. Open and close all DFP windows ONLY through the GUI objects in the
   [DFP: Navigator] window and through the [CLOSE] pushbuttons that are
   located at the bottom of the DFP windows.

3. In the initial [DFP: Navigator] window shown in Figure 1, the user is
   first presented by three large pushbuttons labelled [DESIGN],
   [DISPLAY] and [IMPLEMENT].  Clicking any one of these pushbuttons
   opens a frame in place of that pushbutton with a view of further
   functions available in that category.  Each frame has a smaller
   pushbutton at the top.  These smaller pushbuttons are labelled
   [FILTER], [DISPLAY] and [IMPLEMENT].  If all three frames are visible,
   the [DFP: Navigator] window will be as shown in Figure 2.  Clicking on the
   checkboxes shown in the frames, control the opening and closing of
   secondary DFP windows.

4. While the secondary windows can be individually closed using their
   respective checkboxes, secondary windows within each frame can be
   simultaneously closed using the small pushbutton that appears at the
   top of each frame.  For example, if one presses the [FILTER]
   pushbutton in the left most frame, then both of the 
   [DFP: Type and Specifications] and [DFP: Design Method] windows close.


A. Appendix A: Code generation
==============================

Appendix A presents useful information about the DFP's code generation 
options.  DFP makes a number of assumptions about the target DSP platform 
while generating filter code.  These assumptions are mostly functions of
the underlying DSP hardware on which the DFP generated code will eventually
run. Since, it is impossible to generate code that is universal, the
user should expect some site-specific customization to make the DFP
generated code suitable for running on his/her DSP platform.  Most of
the differences stem from the input (ADC) and the output (DAC) subsystems
attached to these DSP platforms.  The easiest method to adapt DFP for
a particular site is always to generate coefficient macro files rather than 
the full in-line assembler code.  The user can then use these macro files 
with the user written code which calls the DFP generated macro files as 
required.  The "*_macro.asm" and the "*_coef.asm" files in the 
DFP_ROOT/codegen/mot56k/samples directory represent Motorola DSP56k
family specific files that can be used as a starting point for this
particular DSP target platform.  The other, more demanding option is to 
modify the template files together with the DFP function D_CODGEN which is 
the primary M-file responsible for code generation.

    The remarks and the observation are target DSP platform specific.
Therefore, this manual presents such information in a separate appendix
section for each DSP target platform supported by DFP.

A.1: Motorola DSP56k family
===========================

1. The macro files and the template files used by the the full in-line 
   assembler code generation option are tailored for the Motorola DSP56k
   family application development systems (ADS-CLAS56000x) from Motorola.
   In their default configuration the ADS's input/output subsystems are
   connected to the DSP's SSI port.  The full in-line code polls the SSI
   port by checking bit 7 of the SSI port's status register.  If the code 
   detects that bit 7 is set, which indicates that a new sample, x[n], has 
   arrived, it reads x[n] from the SSI port's receiver register and starts 
   processing it.  At the completion of processing the output sample
   y[n] is written to the SSI port's transmit register.  The code then jumps
   to the top of of the processing loop and waits for the next input sample.

2. In the full in-line code there is a call to a macro AISET.ASM.
   This macro initializes the ADS DSP's SSI port for proper operation.
   For further information please see the macro AISET.ASM in 
   DFP_ROOT/codegen/mot56k/macrolib.
   
       If the user selects the full code generation option, DFP first 
   checks whether the user has an environment variable MOT56k_MACLIB by 
   issuing the MATLAB command
   
           maclib = getenv( 'MOT56k_MACLIB' ) 

   If as a result of the above command maclib is set to a non-empty
   string, then DFP assumes that the contents of this environment
   variable is the directory where the user keeps all the MACRO files.
   Thus, the DFP generated full code will contain the following assembler
   code which uses the assembler directive MACLIB:

           MACLIB  string-contained-in-maclib 

   In this case, the user can assemble the DFP generated filter code
   without having to worry about whether the macro file AISET.ASM is located
   in the current directory.  I am assuming the the directory defined by
   the environment variable MOT56k_MACLIB indeed contains the macro file
   AISET.ASM.

       On the other hand if the maclib variable is empty, then DFP writes
   the following assembler code into the target file:

           INCLUDE 'aiset.asm'
  
   In this case it is the user's responsibility to ensure that the file
   AISET.ASM is located in a directory accessible to the assembler and the
   linker.

3. The code I use to generate the full, in-line code files for
   lattice implementation of IIR filters (as well as the associated macro
   files) does provide a somehow inaccurate filter realization.  The DSP
   implementation of the filter realization is there but the finer detail 
   is missing.  I did not have the time to investigate this problem further.
   Until I (or someone else) clarifies this disparity between the expected
   and realized filter responses, you should use the lattice IIR filter code
   with some degree of caution.

   Author: Mehmet Zeytinoglu (mzeytin@ee.ryerson.ca)
           Department of Electrical and Computer Engineering
           Ryerson Polytechnic University
           Toronto, Ontario, M5B 2K3 
           CANADA

    Copyright (c) 1997 Mehmet Zeytinoglu

    $Revision: 1.2 $
    $Date: 1997/03/11 13:39:22 $

