
                     BDM GDB DRIVER AND LIBRARY PACKAGE
                     ==================================

INTRODUCTION
============

This package contains everything you need to know to be able to run GDB on
Linux, FreeBSD, SCO Unix, and Windows and control a Motorola CPU32+ (68360) or
Coldfire (5206/5307) target through a standard PC parallel port.

 o The CPU32 interfaces supported are PD and the IDC interface. GDB 
   should now operate with the CPU32 processor without error.

 o The Coldfire interface is the P&E type interface.

 o You can build Insight if you apply the Insight patch. See the 
   Insight README in this directory.

 o For WindowsNT or Window2000 you will need the GiveIO package. You 
   are best to search the net for the GiveIO (giveio.sys) package. You
   will also need the INSTDRV.EXE file that is also available on the net.
   GiveIO has been test on Windows 2000 and Windows XP.

 o For Unix users the library is built with I/O perm support by 
   default. The same library allows an application to directly 
   access the hardware or use an installed BDM kernel driver.

   I/O Permission is a means getting at the parallel port hardware
   without the need for a kernel driver. This BDM package still provides
   support to build a kernel driver, but you do not need to if you to avoid
   kernel drivers. Some people wish to use kernel drivers and some do not.

   If you wish to learn more about I/O Perm support please refer to the
   section at the end of the file.

   You can disable I/O perm support by editing the Makefile. It is hoped
   autoconf support in the future will provide a better way to handle this.

The subdirectories contain:

  config
    Autotools support files.

  driver
    Source for a Linux, SCO, FreeBSD, I/O Perm, and Windows BDM device 
    driver module.

  gdbPatches
    Move to outside this tree. Please refer to the Sourceforge
    project for the patches.

  gdbScripts
    Example GDB command scripts that show how to initialize and run
    a Motorola 68360 system using standard GDB commands.

  lib
    User-level library routines for accessing the BDM device driver.

  flashlib
    Library for flash support. This library currently supports host-only
    and host-assisted operation modes of 29Fxxx and 49Fxxx chips in
    any combination of bus_width=[1|2|4] and chip_width=[1|2|4]. It is
    already prepared for target-only operation mode and addition of different
    flash algorithms.

  local_scripts
    Scripts to run on the host machine the driver is being installed
    on.

  server 
    The BDM server. This is a daemon which interfaces to the local BDM
    driver remotely. The BDM library can be built to support local and remote,
    just local or just remote access.

  test
    Programs to test the BDM library and driver routines.

  utils
    contains some utilities which might be useful.

WINDOWS
=======

Windows is supported on Windows 98, Windows 2000 and Windows XP. It may run on
other version of Windows, but the ones listed have been tested. Windows 2000
and Windows XP need to the GiveIO driver to gain direct access to the
hardware. You can download the GiveIO package from the net plus you will need
the INSTDRV.EXE program. To install GiveIO place the 'giveio.sys' and
INSTDRV.EXE in a directory and log in as an Administrator or equivalent then:

  c:\tmp> insdrv givio c:\tmp\giveio.sys

The package builds under Cygwin and MinGW.

The MinGW support provides you with a version that directly accesses the
Windows APIs and does not need a Cygwin DLL. To build with MinGW you need to
get the MinGW and MSYS packages from the MinGW web site:

  http://www.mingw.org/

The MinGW package provides the compiler and MSYS provides a shell capable of
running the configure script.

QUICK START
===========

You have unpacked the package. Next to the top of the package create an empty
directory and enter it, configure the package, make, then install.

  $ tar xzf bdm-xx.tar.gz
  $ mkdir build
  $ cd build
  $ ../gdb-bdm-xxx/m68k/configure
  $ make
  $ make install

Note: this process by default creates an IOPERM type BDM driver. If you wish to
build a Linux kernel driver please follow the INSTALLATION directions.

INSTALLATION
============

The Makefiles in all the subdirectories are set up to install their
results in /usr/{bin,lib,.....}.

On FreeBSD remember to use `gmake' rather than `make'.

Notes:

   1. For Windows move to Step 2 as the driver is built into the library. You
      may also need to add `CC=gcc' to make's command line.

   2. For I/O Permission users move to step 2 as the driver is built into the
      library.

   3. Driver users will still have a library with I/O perm support unless the
      default of the library Makefile is manually changed.

   4. You can specify a different `prefix' for the installation directory by
      running all the `make install' commands described below as:

  $ make prefix=/some/directory install

Step 1 -- Compile and install the BDM device driver

  If you do not wish to use a driver and just want the I/O perm support move to
  Step 2.

  Make sure the kernel source code is installed under the /usr/src path.

  Support for more than Linux has been added. You must enter the OS specific
  directory then enter the make command. We assume Linux for the remainder of
  this file.

  If your Linux kernel has been configured for module versions you must
  uncomment the #MODVERSIONS=-DMODVERSIONS line in driver/linux Makefile.  If
  the kernel is configured for module versions and you fail to uncomment this
  line the driver will install and work properly, but depmod will complain
  about unresolved symbols.

  For Coldfire users the driver now looks for the debug module version and will
  use the PST signals if it detects a version 1 debug module. The debug version
  1 is found on the 5307.

    # cd driver/linux
    # make all install

  You may get a bunch of error messages like:
    In file included from /usr/include/linux/fs.h:277,
       from linux-bdm.c:63:
    /usr/include/linux/hpfs_fs_i.h:5: parse error before `ino_t'
    /usr/include/linux/hpfs_fs_i.h:5: warning: no semicolon at \
            end of struct or union
    /usr/include/linux/hpfs_fs_i.h:12: parse error before `:'

  If this happens, try adding `-I /usr/include' to the beginning of the CFLAGS
  definition in the Makefile in driver/linux.

  A script is provided in `local_scripts' called MAKEDEV which create the
  special files needed for the CPU32 and Coldfire.

  To make the special files by hand you can enter:

    # mknod /dev/bdmcpu320 c 34 0
                             ^^ ^
                             |  |
                             |  +--Minor device number (see below).
                             |
                             +--This value must match the
                                BDM_MAJOR_NUMBER in driver/bdm.h

  To have the module module loaded by kerneld when needed
  adding to /etc/conf.modules the line:

     alias char-major-34 bdm

  To automaticially load the driver into the kernel every time
  you reboot you can add the line:

     # /sbin/insmod bdm

  to your startup script, such as /etc/rc.d/rc.local.
    
  You will need to create the device names. The local script MAKEDEV can do
  this for you:

    # ./local_scripts/MAKEDEV

Step 2 -- Compile and install the library and user programs

  The package provides a configure script that you use to build the
  package. All testing I have performed is not to build in the source tree. For
  the default configuration just run the configure script:

    $ mkdir build
    $ cd build
    $ ../gdb-bdm-xx/m68k/configure

  You will need to change the 'gdb-bdm-xx' to the name of the directory in the
  version of the package you have downloaded.

  Once the package has configured itself you can make it:

    $ make

  To install you may need to obtain the appropriate permissions. Once you have:

    $ make install

  The library can be built to access a BDM driver locally via the kernel's
  driver interface, remotely via a TCP/IP socket interfacei, or with direct
  hardware access via the ioperm system call. You can have a library which
  supports all or a mix of interfaces. This allows you to build the
  library and therefore gdb on a host which does not support the driver
  interface.

  On Windows 2000 install the GiveIO driver. This is detailed in the WINDOWS
  section earlier.

  The package supports a number of configuration options over and above the
  standard configure options such as '--prefix'. These are:

    --enable-debug:    Turn on compiler debug information
                       On by default.

    --enable-remote:   Turn on the remote protocol and build it into
                       the library. On by default.

    --enable-ioperm:   Turn on direct IOPERM hardware access. On by
                       default.

    --enable-driver:   Turn on driver access from the library. On by
                       default.

    --enable-server:   Turn on building the BDM server. On by default.

    --enable-flashlib: Turn on building of the flashlib.

    --enable-bdmctrl:  Turn on building of the bdmctrl utility. Since there
                       might be problems to locate bfd.h/libbfd.a which
                       know how to handle target object files, building
                       the bdmctrl utility is disabled unless you have
		       specified the configure options --with-libbfd,
		       --with-libiberty and --with-bfd-include-dir.


  To turn off an option use '--disable-*' where '*' is one of the above.

  Some host settings automatically disable some options:

    Linux : All default settings.
    Cygwin: All default settings.
    MinGW : Server is not built.

  The prefix defaults to the platform specific default. Please refer to your
  documentation for this default setting or just try and see what happens.

  Note, the BDM library is now installed under the package directory of 'bdm'
  under the prefix. For example a prefix of '/usr/local' as found on Linux
  results in the library being under '/usr/local/lib/bdm/libBDM.a'.

  The BDM package also supports cross-compiling. For example you can build
  for a mingw32 host on a Linux machine if you have a MinGW cross-compiler
  and runtime installed:

    $ ../gdb-bdm-xx/m68k/configure --host=ming32 \
                --build=`./gdb-bdm-xx/m68k/config/config.guess`

Step 3 -- Installing the Server

  You only need the BDM server if you intend to use the ioperm method of
  accessing the parallel port, or you wish to support remote access. If you
  wish to use a driver and your access is local to your development machine
  then this step may be skipped.

  Before using the server, please make sure you understand the implications
  of such a setup. You probably want to restrict access to the bdmd port
  to trusted machines.

  The BDM server allows a lab to contain your target hardware and you can
  access it from your development machine. The BDM server can support clients
  on different platforms. This means a Linux server can be accessed from MacOS
  or Windows clients.

  The server runs from the xinetd or inetd daemon, and installs into
  the 'sbin' directory under the configure prefix when building the user
  programs in Step 2 above.

  For inetd users:

    You need to edit the /etc/services file to add the port number bdmd
    uses. Add this line at the bottom of the /etc/services file:

    bdm             6543/tcp                        # BDM server

    You need to edit the /etc/inetd.conf file. Add this line at the end of
    /etc/inetd.conf:

    bdm     stream  tcp     nowait  root  /usr/sbin/bdmd bdmd 

    You can specify any user including root. If you are wishing to use the
    ioperm support then the user must be root.

  For xinetd users as root install the follow in a file called:

    /etc/xinetd.d/bdm

      service bdm
      {
        socket_type  = stream
        port    = 6543 
        wait    = no
        user    = root
        server    = /usr/sbin/bdmd
        server_args  = -n
        log_on_failure  += USERID
        disable    = no
      }

  then get xinetd to reload its configuration.

Step 4 -- (Optional) Testing the driver.

  It a good idea to build and run the test program called `bdm-chk' for
  Coldfire processors and 'bdm-cpu32-chk' for CPU32 processors. This will show
  the library built correctly, the driver loads and functions, and your
  hardware is connected correctly and functioning.

  You will need to select the correct device for the Coldfire.  The example
  below is for the CPU32 interface on LPT1. To test a CPU32 processor do:

    $ cd test
    $ ./bdm-chk /dev/bdmcpu320

  To test a Coldfire processor do:

    $ ./bdm-chk /dev/bdmcf0

  Note, the number at the end of the device path is the parallel 
  port number your pod hardware is connected too. The device nodes
  start from 0, while the standard PC LPT ports number from 1. This
  means '/dev/bdmcf0' will look for a Coldfire processor on LPT1.

  To test using a BDM server on a remote host call 'foo':

    $ /bdm-chk foo:/dev/bdmcpu320

  Note, do not use the MSYS rxtv shell to test from. It currently transforms
  program arguments and the device path used in these example becomes
  something very different.

Step 5 -- Patch your GDB distribution

    $ cd /where/you/keep/gdb-5.3
    $ patch -p1 < /where/you/unpacked/this/BDM/gdbPatches/gdb-5.3-patch

  Don't worry about complaints like:
  mkdir: Failed to make directory "gdb"; File exists

  (Please adjust the patch file name if you are using a snapshot 
  release which is dated.)

Step 6 -- Compile and install the cross-GDB with BDM support

  There is an example script I use to configure, build, and install
  the cross-GDB on my Linux machine in local_scripts/makegdb68kbdm.
  Note that although the target is `m68k-bdm-elf', the debugger 
  should work just fine with COFF executables.
   
  GDB asks the driver which processor being used. The driver uses 
  the minor numbers to select the processor and interface type.
  This means the single configure target will do both the CPU32 and
  Coldfire.

    $ ../gdb-5.3-bdm/configure --target=m68k-bdm-elf --prefix=???

  where ??? is your local prefix path. A prefix path is where
  gdb and the other files it needs are installed too. Providing
  a prefix stops gdb being installed into the default location. 
  This is usually a system location. If you are testing a new gdb
  release it is sometime a good idea to configure and build with
  a test path in the prefix so an installed and working gdb is
  not over written until you have tested the new version.

  Once you have configured GDB you can build it. If you decided not
  to install the BDM library above you will need to do more than
  just enter make as shown here:

    $ make

  For users who have not installed the BDM library you need to:

    $ make \
       CFLAGS="-I/fix-this-path/m68k/lib \
               -I/fix-this-path/m68k/driver" \
       LDFLAGS="-L/fix-this-path/m68k/lib"

  where 'fix-this-path' is the path to your built BDM library.

Step 7 -- (Optional) Install the GDB scripts

    $ cd gdbScripts
    $ make install

  You will have to change the scripts to match your CPU32(+) hardware.

Step 8 -- Build a BDM interface

  See the Schematics directory for an example circuit.

Step 7 -- Try it out

  This is left as an exercise for the reader.....

I/O PERM SUPPORT
================

The I/O Permission support is based around the 'ioperm' system call. This call
allows a root executed program direct access to the I/O ports of a PC. Unix
programs such as X windows use this call to gain control of the video card I/O
ports without the need for a driver.

The support for the ioperm call has been added to the BDM package because it:

  1. Allows a user to build a BDM application without installing kernel 
     sources.

  2. The BDM driver is included in the user land application rather than
     the kernel. A kernel upgrade or change does not require the building
     of the BDM driver.

  3. Binary programs can be created and distributed removing the need for
     users to build a driver to use them.

  4. Stops the kernel jitter seen when downloading.

The library that BDM applications link to by default now contains the ioperm
call as well as the BDM driver code. If you link the default library to GDB it
will contain the ioperm call. Having an application such as GDB make an ioperm
call will fail unless GDB is executing as root. The ioperm call requires the
program making the call be executing as root and executing GDB as root is not
recommended and is actively discouraged.

The remote protocol that is also built by default into the BDM library provides
an easy means to have GDB executing as a user and the BDM server executing as
root. The BDM server being root can make the ioperm call and gain direct
control of the parallel ports.

To use the ioperm call make sure you install the BDM server. See Step 3 of the
INSTALLATION procedure above.

The ioperm support performs the following when opening the BDM port:

  1. Issue the ioperm call. If it passes the direct I/O accessing of the
     parallel port is performed.

  2. If the ioperm call fails, the kernel driver open is attempted. If
     is succeeds the kernel driver is used.

  3. If the driver call fails an attempt to connect to a local BDM
     server is performed. Therefore if ioperm and driver opens fail the
     following check command:

       $ ./chk /dev/bdmcf0

     is transformed into the equivalent command line command of:

       $ ./chk localhost:/dev/bdmcf0

     where we are attempting to open LPT1 for a Coldfire target. The
     device entry at the end should be changed to suite your specific
     parallel port and processor.

A side effect of the current I/O perm implementation is the simulation of
device nodes under the '/dev' tree. This design is copied from the Windows
version of the BDM package. The Windows build is a kind of I/O perm driver
where the GiveIO driver provides the Windows application direct access to the
parallel port rather than the ioperm system call. The simulation of BDM device
nodes under the '/dev' directory is used to keep the documentation consisent,
and to allow GDB scripts or BDM programs a common way to operate on different
platforms. The simulation means you will not find device nodes under a '/dev'
tree. This can be confusing for experienced Unix users accustomed to finding
device nodes in the '/dev' directory.

The I/O perm interface has about the same performance as the kernel
module. This is based on limited testing. The kernel module should be a little
faster for most block read/write operations. This is mostly due to the kernel
being blocked while the bit bashing occurs. If you perform a large number of
small BDM requests the performance will about the same for the ioperm direct
accesses and the kernel driver.

The Library
===========

The library provides a higher level interface to the driver without requiring
you to make low level Linux driver calls.

The library interface consists of two parts:

  1) The driver interface, and
  2) The remote protocol.

The driver interface make Unix driver calls via the open, close, read, write
and ioctl system calls.

The library also contains the remote protocol that talks to the BDM
server. This protocol is not the GDB remote protocol. It operates at a much
lower level than the GDB remote protocol and is designed to support a server
operating from xinetd or inetd. It also allows flash programming tools built
with the BDM library to work remotely.

The library does not contain the download support anymore. The need to contain
a specific BFD header file is broken. The GDB patch contains the code to
perform a download to target.

Windows 9x,NT,2000
==================

The library will build the driver in one pass. There is no driver 
needed for Windows 9x. This should allow GDB to be built. The Cygwin
or MinGW packages are needed to build the library.

I have tested the package on Windows 98, Windows 2000 and Windows XP using
MinGW. This is cross-compiled from Linux and also compiled under MinGW
on Windows XP.

Cygwin should build and work, how-ever at the time of updating this
file I could get Cygwin installed and working to test.

Setting the minor device number
===============================

The minor device number (the second number in the mknod command) specifies
the parallel port to which the BDM interface is connected and the type of
the target CPU. The least signficant two bits of the minor device  
number specify the parallel port and the remaining bits specify the target  
CPU type:

  7    6    5    4    3    2    1    0
+----+----+----+----+----+----+----+----+
|    |    |    |    |    |    |    |    |
+----+----+----+----+----+----+----+----+
\                            / \       /
 \                          /   \     /
  \                        /     \   /
   ------------+-----------       -+-
               |                   |
               |                   |
               |                   +-- These two bits select the parallel
               |                       port to which the BDM interface is
               |                       connected:    00 - LPT1
               |                                     01 - LPT2
               |                                     10 - LPT3
               |
               +-- These six bits select the target CPU type:
                   000000 - CPU32+ (PD adaptor)
                   000001 - Coldfire
                   000010 - CPU32+ (ICD adaptor)

Examples
========
1. Target processor is a Motorola MC68360 (CPU32+) connected to LPT1.
   Minor device number is 0.

2. Target processor is a Motorola MC68360 (CPU32+) connected to LPT2.
   Minor device number is 1.

3. Target processor is a Motorola MC5206(e) or MCF5307 (Coldfire) connected 
   to LPT1. Minor device number is 4.

ACKNOWLEDGEMENTS
================

Thanks very much to Motorola for making the parallel port BDM
interface circuit freely available and to M. Schraut and G. Magin
for providing the Linux driver and gdb modifications that got this
all started.

For the Coldfire additions I would like thank Eric for the clean
driver frame work, and David L Jenkins
(David.l.jenkins@btinternet.com) for the orginal post to the Coldfire
mailing list (ColdFire@WildRice.com) with the pin out and functions
for the P&E interface. It is what started me doing this and a really
great help. David Fiddes must be thanked for the testing and 5307
reset bug.  I would also like to thank Dave Morgan of Plessey Asia
Pacific for the use of some test equipment which helped.

Thanks to David McCullough (davidm@stallion.oz.au) for the SCO
support.

ICD fixes from Alexander Aganichev <AAganichev@hypercom.com>.

ICD performace fixed from Keith Outwater <vac4050@cae597.rsc.raytheon.com>.

NT and GiveIO support to Rick Haubenstricker <rickh@perceptron.com>.

Thanks to Sue Cozart and Joe Circello for answering question about
the Coldfire's BDM hardware.

WHERE TO GET HELP
=================

If you've got any questions about any of this, please contact the BDM project
mailing list on the SourceForge web site:

  http://sourceforge.net/projects/bdm/

We like to hear any success stories, as well as suggestions for improvements.

