***************************************************************************
*									  *
*		     (c) HUNT ENGINEERING 10/5/1993			  *
*									  *
*	A Programming Example: Booting your 'C40 and communicating        *
*				     with your application                *
*                                                       		  *
*   Release 2.4                                         		  *
*   Updated 13-Nov-1996                                 		  *
*                                                       		  *
*   HUNT ENGINEERING Driver Api Test Program
*									  *
***************************************************************************

                              THIS PACKAGE
                              ============

The sources you have received contains an example program which will
demonstrate the use of the TEXAS INSTRUMENTS TMS320C40 Assembler with the
HUNT ENGINEERING Api Drivers

This package deals with both the issues of writing an application in 'C40
assembly to run on a TIM processing module, and of booting this application
to your 'C40. The program is supported by the API and the compilers
supported by that environment. 

Please note that the example program, which we have explained fully
in the rest of this file is a FREE and UNSUPPORTED software package and
hence should only be used to help you develop your own applications to your
own standards whilst ensuring you are dealing with the TMS320C40 correctly.


                              CONTENTS
                              ========

There are two C source modules with the corresponding header file that
make up the 'PC' end, and, a 'C40 assembly program and its assembled COFF
'C40 code, and a batch file and command file.


                                 CHANGES
                                 =======

Release 2.4
===========

Migrated to new API interface. Demonstrates use of HeOpen1() instead of
HeOpen().

Release 2.3
===========
Maintenance Update only. Supports different Motherboard types and
Comports as parameters.

Release 2.2
===========
Ported the HUNT ENGINEERING Api environment, uses platform safe type
definitions and will compile clean on 16 and 32 bit platforms.

Release 2.1
===========
Since the original release of this example it has been modified from
doing single Word (32 bits) writes of the program to the C40 to buffering
it and then doing a Write(). For large programs this will significantly
speed up the download time. See the function HeWriteZ(), this just adds a
word to WriteBuffer[] which is flushed after it is filled and/or when
download is complete. The buffer is WriteBufferSize 32 bit words long.

RUNNING THE EXAMPLE PROGRAM
===========================

To run this example on your PC, you will need to set up the motherboard
with a TIM module IN SLOT 1. 

You will need to setup the Motherboard in accordance with its
documentation and the API files and supporting libraries and drivers.

When you run the C executeable, e.g.

example hep3b a identify.out

The program will boot 'C40 code obtained from identify.out onto the
module you have placed in SLOT 1. It will select the board and comport
specified to do the load. After the 'C40 has booted, the program will
display information about your TIM module.

	The code that is booted, must be from a 'C40 executeable file, such
as identify.out. This code when running may wish to send data back to the
PC which can then be used by the C program which booted it. To do this it
is important that the communication protocol at both ends is the same. To
further illustrate this point, our example program has a function
identify(); which understands the ID ROM data that is being returned to it
from the 'C40 code that was previously booted. When another 'C40 program is
booted, then this new program will require a function running on the PC
that understands the protocol it has adopted.

It is hoped that by following the example program and referring to the
.asm and C source files, you will be able to develop a more detailed
understanding of the requirements of communicating with your 'C40, and of
downloading your applications to the 'C40.


IMPORTANT PROGRAMMING POINTS
============================

The example programs have been written in a manner that will enable their
use as templates on which to develop your own applications. When doing so,
although it may be necessary to adapt the programs to meet your own
requirements, there are certain operations that are extremely important in
insuring your programs execute successfully. The important points that must
be followed are discussed below (along with program comments in the
relevant sections of the accompanying files):-

1. Setting up the 'C40 according to information in the ID ROM:
	Before a 'C40 program begins execution, information must be
	obtained from the modules ID ROM, to enable the 'C40 to be set up
	to execute your code. If you fail to set up control and timer
	registers, the program will not execute. (Refer to identify.asm)
2. Booting the 'C40 according to the required structure:
	When you have program blocks to load onto your 'C40, it needs to be
	sent to the 'C40 in a format that the 'C40 recognises. This format
	is further illustrated later in this text, in the section entitled
	Boot Loader Description. (Refer to function boot();)
3. Resetting the 'C40:
	The actual reset is carried out by an library routine
4. Reading Config:
	Reading the Config bit bit is done using an library routine

5. Using the IO interface - the nature of the interface is hidden by the
   drivers.

	a) Reading from the IO interface:
                The device driver isolates the application from the byte
                wide interface and all communication is in 32 words,
                while there are words to read. (Refer to the manual)
	b) Writing to the IO interface:
                The device driver isolates the application from the byte
                wide interface and all communication is in 32 words.
                while there is space to write to. (Refer to the manual)


PROGRAM STRUCTURE
=================

The example program has been developed as two seperate source modules,
with each module handling some of the points illustrated above. The only
point not covered is that of setting up the 'C40 (see point 1 above), which
is dealt with in the file identify.asm.

HUNT ENGINEERING Api
	This module is responsible for ALL direct communication with the
        PC interface. It contains all of the direct calls to the device
        driver for reading and writing 32 bit words, resetting the 'C40,
        and reading config bit. Where the program needs to read from the
        PC interface, or reset the 'C40 then a function within this
        module is called. 

        This driver supports the common Hunt Calls which are independent
        of Operating System and Interface type and should be used in
        preference to direct access to the kernel Mode Driver to aid in
        portability to other interfaces or operating systems.

Load_out.c:
	This module deals with point 2 above, in that it is responsible for
	stripping all of the required data from a '.out' file, and booting
	the 'C40 according to the requirements of the Boot Loader
	Description.

Example.c:

	This module contains the function main(); and deals with the issues
	covered in points 2 - 6. This module is the example program that
	uses the functions of level0.c, and boots via load_out.c, and
	finally communicates with the process running on the 'C40 according
	to the protocol that has been adopted by the assembly program
	identify.asm.


REBUILDING EXAMPLE.EXE

It will be necessary to create either a Visual C++ V1.5 "Project" or a
V4.2 Workspace. In either case you will need to add the files

        example.c
        load_out.c

to the project PLUS the appropriate file(s) from the API package and
rebuild. Where appropriate the LARGE memory model should be used        

==========================================================================
BOOT LOADER DESCRIPTION (As on page 13-13 of the TMS320C4x User's Guide):


32 Bit Wide Configuration:

 Word	    Address	   Value	    Comments
  1	   0300000h	 00000020h     Memory width = 32 bits
  2	   0300001h	 1D7BC9F0h     Global memory bus control word

  3	   0300002h	 1D739250h     Local memory bus control word
  4	   0300003h	 00000126h     1st program block size = 126h
  5	   0300004h	 002ff840h     1st program block starting address
	   0300005h		       1st program block starts here
							    (first word)

    6
to 299

							     (last word)
	   030012Ah		       1st program block ends here

 300	   030012Bh	 00000040h     2nd program block size = 40h
 301	   030012Ch	 002FF800h     2nd program block starting address
	   030012Dh		       2nd program block starts here
							    (first word)

   302
to 365
							     (last word)
	   030016Ch		       2nd program block ends here

 366	   030016Dh	 00000000h     Value 0 to terminate the block load
 367	   030016Eh	 002FF800h     IVTP = 002FF800h
 368	   030016Fh	 002FF800h     TVTP = 002FF800h
 369	   0300170h	 00300000h     Address location for IACK
					    instruction

==========================================================================
