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

This package contains everything you need to be able to run GDB on
Linux and control a Motorola CPU32+ (68360) or Coldfire (5206) target
through a standard PC parallel port.  The subdirectories contain:

driver
	Source for a Linux BDM device driver module.

gdbPatches
	Contains patches to add BDM support to gdb-4.18.

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.

Schematics
	Schematic drawings for a PC parallel port to CPU32 BDM interface.  
        This directory also contains printed-circuit board drawings and
	assembly drawings for the interface.

test
	Programs to test the BDM library and driver routines.

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

The Makefiles in all the subdirectories are set up to install their
results in /usr/{bin,lib,.....}.  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

	Support for more than Linux has been added. You must
	enter the OS specific directory then ente 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 you can enable PST use by uncommenting 
	the line #USE_PST=-DUSE_PST. 

	cd driver/linux
	make install

	Make the special file for the device:

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

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

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

		/sbin/insmod bdm

	to your /etc/rc.d/rc.local startup script, or have the module
        loaded by kerneld by adding to /etc/conf.modules

               alias char-major-34 bdm
		
Step 2 -- Compile and install the BDM library

	cd lib
	make install

Step 3 -- (Optional) Testing the driver.

	It a good idea if you are a first user to build and run the
	test program called `chk'. 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.

        cd test
        make
        ./chk /dev/bdm0

Step 4 -- Patch your GDB distribution

	cd /where/you/keep/gdb-4.18
	patch -p1 </where/you/unpacked/this/BDM/gdbPatches/gdb-4.18-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 5 -- 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 
	works just fine with COFF executables as well.
   
        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-4.18-bdm/configure --target=m68k-bdm-elf --prefix=???

        where ??? is your local prefix path.

Step 6 -- (Optional) Install the GDB scripts

	cd gdbScripts
	make install

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

Step 6 -- 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.....

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 download interface.

The driver interface is all but the download functions. The download
functions allow you to write a loader which accepts file formats for
which the BFD library was compiled for. You can check which file
formats are supported by running the m68k version of objdump without
any command line arguments.

The library is built using a local copy of the BFD header file
`bfd.h'. This version is taken from the gdb-4.18 sources so should not
cause any problems when building gdb-4.18.

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+
                   000001 - Coldfire

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

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

If you've got any questions about any of this, please feel free to
e-mail me at `eric@skatter.usask.ca'.

For the Coldfire work and any general questions please send me a mail
to `ccj@acm.org'.

I'd like to hear any success stories, too.  Suggestions for improvements
are also welcome.

NEXTSTEP versions of this code are also available.
