--------------------------------------------------------------------------------
            Copyright (C) 1997 Texas Instruments Incorporated.
                         All Rights Reserved
--------------------------------------------------------------------------------

                        **************************
                        *                        *
                        *    SDB Release 2.11    *
                        *                        *
                        *        10-03-97        *
                        *                        *
                        *       README.TXT       *
                        *                        *
                        **************************

*****************************************************************************
                                 Intro
*****************************************************************************

This file contains details regarding the TMS320C8x SDB 2.11 release. Read
this file to find information about:

 - software directory structure
 - whats in the BIN directory
 - the peripheral library components
 - 'C' code naming convention used in the peripheral libraries
 - rebuilding the peripheral libraries
 - building your own code using the libraries
 - environment variables needed by the tools

Please read:
 - #DISCLAI.TXT
 - README.TXT
 - RELEASE.TXT
 - ERRATA.TXT
 - RPC\SDBRPC.TXT

*****************************************************************************
NEW IN RELEASE 2.10
*****************************************************************************
A complete remote-procedure-call (RPC) system has been added which allows
an RPC client (host application) to execute functions on the server (SDB).
For more details, see RPC\SDBRPC.TXT and also study the RPC samples located
in SAMPLES\RPC.

*****************************************************************************
INSTALL NOTES
*****************************************************************************
If the SDB software has been obtained from the FTP site, then remember
to use the '-d' option when executing the self extracting zip file.
All of the files will expand into their releative directories.
For example, if you want to install the software into c:\sdb then copy the
downloaded file into that directory and execute it there.

The command "C:\SDB>sdbxxx.exe -d" will unzip all of the files into
C:\sdb and will create all necessary subdirectories where sdbxxx.exe is
the latest release (sdb210.exe, sdb211.exe, etc...).

You need to install the device driver for Windows NT. This driver is 
located in the BIN\NT directory. This installation process will
also automatically copy certain files to the Windows system32
directory.

WINDOWS NT 4.0
1) Open up the "Control Panel"
2) Open up the "Multimedia" applet
3) Select "Devices"
4) Click "Add"
5) Highlight "Unlisted or Updated Driver"
6) Click on "OK"
7) Browse to the "BIN\NT" directory of the new sdb software
8) Click on "OK"
9) Click on "OK"
10) If you get the "Driver Exists" dialog box, click on "New"

WINDOWS NT 3.51
1) Open up "Control Panel"
2) Open up the "Devices" applet
3) Click on "Add"
4) Highlight "Unlisted or Updated Driver"
5) Click on "OK"
6) Browse to the "BIN\NT" directory of the new sdb software
7) Click on "OK"
8) Click on "OK"
9) If you get the "Driver Exists" dialog box, click on "New"

The BIN directory needs to be in your path variable.

*****************************************************************************
                             Directory Structure
*****************************************************************************

The following is the directory structure of release 2.11. Assuming the
software was unzipped into C:\C8XSDB.

C:.
+---C8XSDB
|   +---BIN
|   |   \---NT
|   +---HOST
.   |   +---INC
.   |   +---LIB
.   |   \---SRC
    +---HOSTAPI
    +---INC
    +---LIB
    +---RPC
    |   +---CLIENT
    |   +---SERVER
    |   \---SHARE
    +---SAMPLES
    |   +---AUDIO
    |   |   +---AUDCAPT
    |   |   +---AUDPLAY
    |   |   +---AUDTEST
    |   |   \---PIOTEST
    |   +---HOST
    |   |   +---CMNDSERV
    |   |   |   +---CLIENT
    |   |   |   \---SERVER
    |   |   +---DATAXFR
    |   |   |   +---CLIENT
    |   |   |   +---SERVER
    |   |   |   \---SHARE
    |   |   +---SDBRESET
    |   |   \---SDBRUN
    |   +---RPC
    |   |   +---CMNDSERV
    |   |   |   +---CLIENT
    |   |   |   +---SERVER
    |   |   |   \---SHARE
    |   |   +---DATAXFR
    |   |   |   +---CLIENT
    |   |   |   +---SERVER
    |   |   |   \---SHARE
    |   |   +---FRAMEGRB
    |   |   |   +---CLIENT
    |   |   |   |   +---RES
    |   |   |   |   \---WINDEBUG
    |   |   |   +---SERVER
    |   |   |   \---SHARE
    |   |   +---TEST
    |   |   |   +---CLIENT
    |   |   |   +---SERVER
    |   |   |   \---SHARE
    |   |   \---USER
    |   |       +---CLIENT
    |   |       +---SERVER
    |   |       \---SHARE
    |   +---SDB130
    |   |   +---AUDDEMO
    |   |   +---GRAFIX
    |   |   |   +---DOC
    |   |   |   \---FUNCS
    |   |   +---HOSTDEMO
    |   |   +---SERVER
    |   |   \---VIDDEMO
    |   \---VIDEO
    |       +---CAPTTEST
    |       +---DISPTEST
    |       +---OVERLAY
    |       +---PIOVID
    |       \---VIDEO
    \---SRC

*****************************************************************************
                              BIN Directory
*****************************************************************************

The BIN directory contains host executable files which make up the tools
for the SDB. Below is a breif description of the key files in the
BIN directory.

  MPSDB.EXE  - C Source Debugger for the master processor (MP)
               Use this tool to debug code on the MP, remember to 
               specify a processor name.

               C:\>mpsdb -n mvp1_mp

  PPSDB.EXE  - C Source Debugger for the parallel processors (PP)
               Use this tool to debug code on a PP, remember to 
               specify a processor name.

               C:\>ppsdb -n mvp1_pp0

  PDM.EXE    - Parallel Debug Manager
               This tool allows parallel debugging of the MP and the PPs.
               
               C:\>pdm

  SDBRST.EXE - SDB board reset utility
               This tool resets the board to a known state. This tool
               should be used frequently between debugging sessions. The
               source for this tool can be found in the SAMPLES\HOST\SDBRESET
               directory.

               C:\>sdbrst

  SDBRUN.EXE - SDB COFF file loader
               This command line utility is used to load a COFF file onto
               the SDB and execute it. This gives a way to quickly load 
               and run a C80 program without bringing up the debuggers. The
               source for this tool can be found in the SAMPLES\HOST\SDBRUN
               directory. The COFF file must be a linked .out file. If no
               filename extension is given, the tool assumes .out. The 
               SDBRUN.EXE program requires that the SDBBOOT.OUT file be
               in the Windows\system32 directory.

               C:\>sdbrun myprog.out

                 or

               C:\>sdbrun myprog

  SDBDIAGS.EXE - This is a GUI application which tests the major components
  SDBAV.OUT    of the SDB. The SDBAV.OUT file is the C80 portion of the
               diagnostics program which is automatically loaded when
               SDBDIAGS.EXE is executed. You must execute SDBDIAGS.EXE
               from within the BIN directory so it can find the SDBAV.OUT
               file. Its a good idea to execute SDBRST.EXE first.

               C:\C8XSDB\BIN>sdbrst
               C:\C8XSDB\BIN>sdbdiags

  SDBSHELL   - SDB command line shell (included from release 1.30)


  NT         - Directory which holds the device driver for Windows NT. Also
               has certain .out and .bin files used by the tools.

*****************************************************************************
                     Peripheral Library Components
*****************************************************************************

Included with the SDB is a set of peripheral libraries written in C which
supply a user interface (API) to the SDB hardware. 

  LIB directory - SDBDRVS.LIB   C80 peripheral library (C80)
                  HSDBDRVS.LIB  Host API library (host)
                  SRPC.LIB      RPC server library (C80)
                  CRPC.LIB      Client RPC library (host)
                  SDBEMBED.LIB  Legacy peripheral libray (1.30) (C80)
                  SDBAPI.LIB    Legacy host library (1.30) (host)
                  SDBAPI.DLL    Counterpart to SDBAPI.LIB (1.30) (host)
  
  INC directory - SDBDRVS.H     Peripheral API library header file (C80)
                  HSDBDRVS.H    Host API library header file (host)
                  SDBRPC.H      Header file for RPC libraries (C80 + host)
                  SDBAPI.H      Legacy host library header file (1.30)
                  SDBEMBED.H    Legacy peripheral header file (1.30)

                  AUDIO.H       Audio API header file (C80)
                  DISPLAY.H     Display API header file (C80)
                  CAPTURE.H     Video Capture API header file (C80)
                  SSERVER.H     Server API header file (C80)
                  HCLIENT.H     Client API header file (host) 
                  AUDRPC.H      Audio RPC header file (C80 + host)
                  CAPTRPC.H     Video Capture RPC header file (C80 + host)
                  DISPRPC.H     Display RPC header file (C80 + host)
                  SERVRPC.H     Server RPC header file (C80 + host)
                  SYSRPC.H      

  SRC directory - SDBDRVS.H     Header file for the C80 peripheral library

                  AUDIO.C       Audio API module
                  AUDIO.H   
                  AD1848.C      Audio CODEC module
                  AD1848.H  
                  IDT72520.C    Audio FIFO module
                  IDT72520.H

                  DISPLAY.C     Video display API module
                  DISPLAY.H 
                  C80FTC.C      C80 frame timer module
                  C80FTC.H  
                  ICS1574.C     Pixel clock module
                  ICS1574.H 
                  TVP3020.C     RAMDAC module
                  TVP3020.H 

                  CAPTURE.C     Video capture API module
                  CAPTURE.H 
                  PCF8584.C     I2C controller module
                  PCF8584.H 
                  SAA7196.C     Video capture front end module
                  SAA7196.H 

                  SSERVER.C     Server API module
                  SSERVER.H 

                  EVENTS.C      Shared events module
                  EVENTS.H 
                  
                  SDBBOOT.ASM   SDB boot loader program, used by SDBRUN.EXE
                  SDBBOOT.LNK
   
  HOST\LIB dir  - HSDBDRVS.LIB  Client library
                  CRPC.LIB      Client RPC library (host)
                  SDBAPI.LIB    Legacy host library (1.30) (host)
                  SDBAPI.DLL    Counterpart to SDBAPI.LIB (1.30) (host)

  HOST\INC dir  - HSDBDRVS.H    Header file for the client library
                  HCLIENT.H     Host client API header file
                  AUDRPC.H      Audio RPC header file (C80 + host)
                  CAPTRPC.H     Video Capture RPC header file (C80 + host)
                  DISPRPC.H     Display RPC header file (C80 + host)
                  SERVRPC.H     Server RPC header file (C80 + host)
                  SYSRPC.H      System RPC header file (C80 + host)
                  SDBRPC.H      Header file for RPC libraries (C80 + host)
                  SDBAPI.H      Legacy host library header file (1.30)
  
  HOST\SRC dir  - HSDBDRVS.H    Header file for the client library
  
                  HCLIENT.C     Host client API module
                  HCLIENT.H  

                  PCI.C         PCI interface module
                  PCI.H      

                  COFF.C        COFF loader module
                  COFF.H     


Each API (audio, video display, video capture, server, and client) is
structured in a modular fashion with a main API module and one or more
sub-modules. Each sub-module performs a specific hardware task to support
the API module. Below is the modular structure of each API.




Audio API (C80)                +---------+
                               | audio   |
                               +----+----+
                                    |
                                    |
                       +------------+------------+
                       |            |            |
                       |            |            |
                  +----+----+  +----+----+  +----+----+
                  | ad1848  |  | idt72520|  | events* |
                  +---------+  +---------+  +---------+




Video Display API (C80)        +---------+
                               | display |
                               +----+----+
                                    |
                                    |
                 +------------+-----+------+------------+
                 |            |            |            |
                 |            |            |            |
            +----+----+  +----+----+  +----+----+  +----+----+
            | c80ftc  |  | tvp3020 |  | ics1574 |  | events* |
            +---------+  +---------+  +---------+  +---------+




Video Capture API (C80)        +---------+
                               | capture |
                               +----+----+
                                    |
                                    |
                             +------+------+      
                             |             |      
                             |             |      
                        +----+----+   +----+----+ 
                        | saa7196 |   | events* | 
                        +----+----+   +---------+ 
                             |      
                             |      
                        +----+----+ 
                        | pcf8584 | 
                        +---------+ 




                               +---------+
Server API (C80)               | sserver |
                               +---------+




                               +---------+
Client API (host)              | hclient |
                               +----+----+
                                    |
                                    |
                            +-------+-------+
                            |               |
                            |               |
                       +----+----+     +----+----+
                       |   pci   |     |  coff   |
                       +---------+     +---------+



* - indicates shared module


*****************************************************************************
                        C Source Naming Convention
*****************************************************************************
Each module uses a standard (to this software) naming convention. All
function names and data names (constants, macros, and data-types) are prefixed
with the module name in all caps followed by an underscore. This lets one know
exactly which module something is defined in just by looking at its' name.
The API modules however, use a first letter capital for function names since
it looks nicer to the application code.

examples:

Audio_Init()   is an audio API module function
AUDIO_ENABLE   is an audio API module macro

TVP3020_RegIn(...) is a function in the tvp3020 sub-module
TVP3020_MET        is a data-type in the tvp3020 sub-module

It should be noted that the above naming convention is only used for functions
and data items which are exported, that is, scope is given to external
modules. All module items with external scope are defined in that modules'
header file. All other functions and data items are local to that module and
use no prefixes for naming. For example, the SAA7196 module has an internal
function, 'SetFieldAddresses()' which is only visible from within that module,
hence no naming prefixes. This adds to the overall structure of things because
if one sees an indentifier with no prefix, it is immediately known that this
item is local to the module it is in. By the same token, if one sees an
identifier in a module and it has a prefix of that modules name, it is known
that this identifier is visible to any parent modules.

For those who want to customize the library code, the modular structure and
naming convention used here should make the job much easier. Just by name,
one knows exactly which module a particular function or macro is in, knows
if the item is static or external, knows exactly what that module does, and
knows that it is the only module which does what it does.


*****************************************************************************
                         Rebuilding the Libraries
*****************************************************************************
The two libraries LIB\SDBDRVS.LIB and LIB\HSDBDRVS.LIB must be treated
differently when rebuilding since one is built from C8x code using C8x tools
and the other is built from host code using a host compiler. The C8x code
generation tools (compilers, assemblers, linker, etc...) are not included
with the SDB and must be purchased separately. These tools are needed if you
want to rebuild these libraries. Also see the section below about environment
variables.

NOTE: Make sure you have a backup of your original files before rebuilding.

Rebuilding C80 library, SDBDRVS.LIB
-----------------------------------
The first step is to be in the SRC directory. In this directory is a BUILD.BAT
file and a MAKEFILE. They both do the same thing but the BUILD.BAT always
rebuilds everything regardless if needed. The MAKEFILE file is a standard
text makefile readable by most make utilities. Odds are if you have a C
compiler on your machine, you have a make utility. Microsoft Visual C++ comes
with a make utility, NMAKE.EXE. When you build the project, the source
modules are compiled then archived into the library file.

C:\C8XSDB\SRC>build

or

C:\C8XSDB\SRC>make



Rebuilding host library, HSDBDRVS.LIB
-------------------------------------
The first step is to be in the HOST\SRC directory. In this directory is the
MAKEFILE file which is a standard text project makefile. The HSDBDRVS.LIB
library was built using the Microsoft Visual C++ compiler and linker. The
makefile uses the command line compiler and linker. All modules are compiled
in this directory then archived into the library file.

C:\C8XSDB\HOST\SRC>nmake
 

*****************************************************************************
                               Building Code
*****************************************************************************
Building code using the libraries is fairly simple, you must include the
library header file, then link in the library. The C8x code and host code 
must be treated separately. Also see the section below about environment
variables.

Building C8x Code
-----------------
Include the header file into your C source file. Notice that
#include <sdbdrvs.h> is used instead of #include "sdbdrvs.h". This is because
the INC directory is in the compilers include search path.

   myprog.c
   +-------------------------
   | /* my C8x program */
   |
   | #include <sdbdrvs.h>
   |


Link in the library

   myprog.lnk
   +----------------------------
   |-c                
   |-x                
   |-heap  0x00400000 
   |-stack 0x00010000 
   |-l mp_rts.lib     
   |-l mp_task.lib    
   |-l mp_int.lib     
   |-l mp_ptreq.lib   
   |
==>|-l sdbdrvs.lib    
   |


Building Host Code
-----------------
Include the header file into your C source file. Notice that
#include <hsdbdrvs.h> is used instead of #include "hsdbdrvs.h". This is
because the INC directory is in the compilers include search path.

   myprog.c
   +-------------------------
   | /* my host program */
   |
   | #include <hsdbdrvs.h>
   |


Link in the library. There are several ways to do this. Using Microsoft
Visual C++, you can either add the LIB\HSDBDRVS.LIB file to the list of
project files or you can list the library file in the Project - Settings -
Link - General dialog. It is also suggested that you add the INC
directory path to the Tools - Options - Directories - Include files list.
Then add the LIB directory to the Tools - Options - Directories -
Library files list.


*****************************************************************************
                           Environment Variables
*****************************************************************************
To use the libraries, certain environment variables must be set up correctly
to let the compilers and linkers know where to find files. The C8x tools
and the host tools need their own special setup. 

C8x Code Generation Tools Environment Variables
-----------------------------------------------
A_DIR=C:\C8XSDB\LIB;C:\C8XSDB\INC;%A_DIR%;
C_DIR=C:\C8XSDB\LIB;C:\C8XSDB\INC;%C_DIR%;
D_DIR=C:\C8XSDB\BIN;%D_DIR%;
D_SRC=C:\C8XSDB\SRC;%D_SRC%;

Microsoft Visual C++ Environment Variables
------------------------------------------
include=C:\C8XSDB\INC;%include%
lib=C:\C8XSDB\LIB;%lib%

Note: The %varname% just means expand that variable.

*****************************************************************************
                             End of README.TXT
*****************************************************************************
 


