readme   6/20/00

Table of Contents:
Part 1: Introduction
Part 2: using config_decoder
Part 3: building config_decoder
Part 4: Testing on the pc

Part 1: Introduction
	This program builds and runs on a host UNIX or PC platform.  It
is not intended to be downloaded or run on an evaluation board.

	This program will accept configuration register values for the
MPC106, MPC107, MPC8240 Host mode, and MPC8240 Agent mode.
	The only difference between MPC8240 host and agent mode is that
the program will point out if Reg04 is set for the wrong mode.
	It will display all the bit fields, a description of the field,
and interpretation as well as pointing out any errors.

Part 2: using config_decoder
	The program is invoked either by the long command, config_decoder.elf
or the short command a.elf.  Both commands invoke the same code.
	The user is presented with a splash line showing the version and date:
Configuration Register Decoder Version 0.1 June 13, 2000  
	Then the user may type in some descriptive comment.
	Then the user is presented with four choices:
Please chose one of the following by number 1,2,3, or 4:     Decode
 1. MPC106
    Decode
 2. MPC107
    Decode
 3. MPC8240 Host
    Decode
 4. MPC8240 Agent  
	The user may select 1,2,3, or 4.
	Then the user must choose a printing order, Big Endian, print from bit
0 to bit 32, or Little Endian, verse order.
Choose printing order:
    1. Big    endian order
    2. Little endian order  
	Then the user may interactively supply register numbers followed
by the value, as in:  reg:value.  e.g.  e0:12345678.
	The program is concluded by typing in an EOF, e.g. ^D (control D).

	The program can also be invoked in batch mode by redirecting the
input file.
	a.elf < input.file
	The results can be saved by redirecting the output file.
	a.elf > output.file

	There are two sets of four examples, mpc106.in, mpc107.in, mpc8240h.in 
and mpc8240a.in.  The expected output is contained in the files mpc106.out,  
mpc107.out, mpc8240h.out and mpc8240a.out.  
The first set is for the Big endian order testing and is described here.

	This procedure is for unix only.  See Part 4 for information on using
test.it on the pc. There is a test procedure called, test.it, which when invoked
with run a.elf with all input files and compare the generated output
with the expected output.  It invokes a.elf four times as in:

echo "Big endian order test"
echo "a.elf < mpc107.in > d7.out"
a.elf < mpc107.in > d7.out
echo "diff d7.out mpc107.out"
diff d7.out mpc107.out
echo "a.elf < mpc106.in > d6.out"
a.elf < mpc106.in > d6.out
echo "diff d6.out mpc106.out"
diff d6.out mpc106.out
echo "a.elf < mpc8240h.in > d8h.out"
a.elf < mpc8240h.in > d8h.out
echo "diff d8h.out mpc8240h.out"
diff d8h.out mpc8240h.out
echo "a.elf < mpc8240a.in > d8a.out"
a.elf < mpc8240a.in > d8a.out
echo "diff d8a.out mpc8240a.out"
diff d8a.out mpc8240a.out
echo "All done"

The other set is for the Little endian order and the names are the same except
that 'l' is appended in front of each file name.  The procedure for little
endian testing is testl.it.

Part 3: building config_decoder

	Build the config_decoder with the correct makefile.  The default
target will build the executables, config_decoder.elf and a.elf.

	The code consists of 6 C files:

config_decoder.c	Main entry point.  Introduces the program and 
			accepts the first set of input.  Eventually
	   		loops on an input request, calling the specific
	    		configuration register decoders.
config_messages.c       All the interpretation messages reside here.
config_regs.c		All the main register decoder routines reside here.
config_regs1.c		Extra register decoder routines for mpc106.
config_utils.c		Helper routines.

	One H file:
config_decoder.h	Contains all the defines and the prototypes for
			all functions and message names.
	Two makefiles:
makefile		Unix makefile using the GNU GCC tool chain and
	  		either the GNU make or UNIX make facility.
makefile_pc		PC makefile using the microsoft C++ cl batch
			compiler and the mks tools make facility.

	Four input test and output test files:

mpc106.in
mpc106.out
mpc107.in
mpc107.out
mpc8240h.in
mpc8240h.out
mpc8240a.in
mpc8240a.out

	Two test procedures:

test.it			Invokes the configuration decoder with all *.in files
	                and compares the results with the *.out files for 
			big endian order.

testl.it		Invokes the configuration decoder with all *.in files
	                and compares the results with the *.out files for 
			little endian order.


Part 4: Testing on the pc
	The pc will not honor executing the procedure, test.it, therefore,
it is necessary to copy test.it to test.bat, creating a pc batch file.
Then, one may invoke test.bat.

copy test.it  test.bat
test.bat

	The pc will not honor executing the procedure, testl.it, therefore,
it is necessary to copy testl.it to testl.bat, creating a pc batch file.
Then, one may invoke test.bat.

copy testl.it  testl.bat
testl.bat