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

                        **************************
                        *                        *
                        *    SDB Release 2.10    *
                        *                        *
                        *        09-02-97        *
                        *                        *
                        *       SDBRPC.TXT       *
                        *                        *
                        **************************

*****************************************************************************
                               Disclaimer
*****************************************************************************
//----------------------------------------------------------------------
// TMS320 DSP Applications
// (c) Copyright 1995-1997
// Texas Instruments Incorporated
//
// This is unsupported freeware code with no implied warranties or
// liabilities.  See the disclaimer document for details

                         GENERAL DISCLAIMER
                         ------------------
  All software and related documentation is provided "AS IS" and without
warranty or support of any kind and Texas Instruments expressly disclaims
all other warranties, express or implied, including, but not limited to, the
implied warranties of merchantability and fitness for a particular purpose.
Under no circumstances shall Texas Instruments be liable for any incidental,
special or consequential damages that result from the use or inability to
use the software or related documentation, even if Texas Instruments has
been advised of the liability.

 

                      FTP AND BBS SOFTWARE
                      --------------------
- The Texas Instruments TMS320BBS and internet FTP site are provided as a
  convenient location for obtaining DSP related materials
  which you are free to download, use or evaluate.

  FTP Site :    ftp://ftp.ti.com/pub/tms320bbs
 
 TMS320BBS:    281-274-2323, No parity, 8 data bits, 1 (or more) stop bits
                Baud rates are supported through 33.6kbs

- Unless otherwise stated, software written and copyrighted by Texas
  Instruments is distributed as freeware.  You may use and modify this
  software without any charge or restriction.  You may distribute to
  others, as long as the original author is acknowledged.

- Third party shareware programs that allow the limited use of a product
  can also be found on the BBS or FTP site.  In these cases  the software
  will be accompanied by a notice from the third party that becomes a
  legaly binding agreement between the user and the third party.  You may
  be required to register or license the use of the software.


*****************************************************************************
                                 Intro
*****************************************************************************
A complete remote-procedure-call (RPC) system has been added to release 2.10
which allows an RPC client (host application) to execute functions on the
server (SDB). For more details, study the RPC samples located in SAMPLES\RPC.

What TI has done is taken the 2.00 library release and wrapped a complete
RPC system around it. The audio, video display, and video capture APIs
are now ported to the host using RPC calls. The APIs are identical to their
C80 counterparts. This is feasible for most of the API function calls,
display calls for instance, but it does not make sense to try to use
some of the real-time function calls via RPC. With this noted, all API
function calls are callable via RPC but some may behave differently
than if called by C8x code. The intent is not to do C8x real-time 
programming from the host via RPC calls. The APIs have been ported
for convience, probably about 90% of the calls are still usefull from
the host.

The biggest and most important feature of the RPC system is the addition
of a new API, "System", which gives a client application a rich set of
data transfer functions. Another big feature is the ability to easily 
add custom functions to the RPC system.

The basics:
- The host application (client) calls an RPC function.
- The RPC function packs the RPC arguments into an array of ULONGS.
- The RPC functions then issues the command to the server (SDB).
- The server retreives the command from the client.
- The server dispatches the command to a registered RPC server callback.
- The server callback function unpacks the arguments and calls the actual
  API function.
- The API function return value is returned to the server.
- The server then returns the return value to the client.
- The client RPC function gets the return value and and interprets it acordingly.

Use of the RPC libraries also simplifies client/server application code by
abstracting all of the library housekeeping work. On the client side,
the libraries are initialized, and the sever is booted, all in one
convenient call. On the C80 server side, the libraries are initialized,
the multitasking executive is initialized, and system registers are
initialized. Below are the bare minimum lines of code to use the RPC
libraries.

client.c (host code)
+---------------------------------------------
|#include <sdbrpc.h>
|
|void main() {
|
|  RpcInit("server.out",1);
|
|  /* can now call any RPC functions */
|
|  RpcQuit();
|
|} 
|


server.c (C80 code)
+---------------------------------------------
|#include <sdbrpc.h>
|
|void main() {
|
|  RpcInit(15);
|
|  /* do your other init stuff here  */
|  /* before starting the RPC server */
|
|  RpcServerStart(1);
|
|}
|

Remember you also have to link in the libraries,
Client: HSDBDRVS.LIB and CRPC.LIB
Server: SDBDRVS.LIB and SRPC.LIB
 
*****************************************************************************
                            The RPC Libraries
*****************************************************************************
You can find all of the the library source code in the RPC\SERVER,
RPC\CLIENT, and RPC\SHARE directories. There are also examples located
in SAMPLES\RPC. The examples should be enough to get started. They
cover all basis. The peripheral API libraries which have been ported
to the RPC system are documented in the 2.00 release (SDB Programmers
Guide). The ony new API functions are the system calls for doing
data transfers and a couple of miscelaneous calls.

*****************************************************************************
                            Server Side (C80)
*****************************************************************************
typedef ULONG(*SRPC_FUNC)(ULONG *Args);

The RPC server operates by responding to an interrupt from the client.
This interrupt signals the server task via semaphore. Once the server
task gets the semaphore, it reads the RPC command arguments which the
client had placed into the PCI FIFO. The first ULONG word is a unique 
32-bit command indentifier. The RPC server task uses this identifier
to look up an RPC callback function from a table of registered RPC
callback functions. If the callback is found in the table, the server
task dispatches control to the callback. The callback then unpacks
its arguments from the Args parameter. All callback functions must
return a ULONG and take a pointer to an array of ULONGs as its only
argument. The type definition above is the type assumed for all RPC
server callback functions.

-----------------------------------------------------------------------------
#define RPC_ERROR_USED  0x00000001 /* Register failed because id is used    */
#define RPC_ERROR_FULL  0x00000002 /* Register failed because table is full */

Before and RPC server callback function can be used, it must be registered
with the RPC server task. This is done by calling RpcServerRegister().
This adds the callback function to the callback table. Two errors can
occur during the registration process, the ID number is already in use or
the table is full. RpcServerGetLastError() returns the condition of the
last registration call.

-----------------------------------------------------------------------------
BOOL  RpcInit(long priority);

This function initializes the entire RPC server system on the C80.
The priority argument is the priority the RPC server task will execute at.

The following things are performed.
- Multitasking executive initialized
- Audio API initialized
- Display API initialized
- Video capture API initialized
- System registers initialized (PTMIN, PTMAX, etc)
- Registers all audio API RPC callback functions
- Registers all display API RPC callback functions
- Registers all video capture API RPC callback functions
- Registers all system API RPC callback functions

Once RpcInit() is called, the RPC system is initialized but can not
receive commands from the host until RpcServerStart() is called.
This is done to allow the application to do its own initialization
before allowing the host to start sending commands.

-----------------------------------------------------------------------------
void  RpcServerStart(BOOL Reply);

This function starts the RPC server. Once called, the host can start
sending commands down to the C80. The reply argument is a flag to indicate
if a start reply should be sent back to the host or not. TRUE means yes,
send a reply.

The reply is sent back in the FIFO mailbox which the host waits on during
its RpcInit() function. The reason for not wanting to send a reply in the
mailbox is if you want to debug your code using the debuggers.

-----------------------------------------------------------------------------
BOOL  RpcServerRegister(ULONG Id, SRPC_FUNC Func);

This function registers an RPC callback function with the RPC server task.
The id argument is a UNIQUE 32-bit indentifier used to look up the
callback function in the callback table. The host uses this id to send
a command down to the sdb. All user registered RPC callback id's should
begin at RPC_USER_START, a constant defined by the library. All id
values below this value are reserved. The callback function must be
of type SRPC_FUNC.

-----------------------------------------------------------------------------
ULONG RpcServerGetLastError();

Call this function to get error status of the last RPC callback registration.

*****************************************************************************
                             Client Side (Host)
*****************************************************************************
CLIENT_STAT RPC_STATUS_WORD;

This is a global variable maintained within the RPC library. It is updated
during any RPC call. Thus, the user application can monitor RPC_STATUS_WORD
to see if everything is still working.

--------------------------------------------------------------------------------
void   RpcInit(char *server, BOOL boot);

This function initializes the client RPC system. Once called, the
user can execute any RPC functions available. The server argument is
a character string for the server coff filename. This is the C80 server
program that gets booted onto the SDB. You can specify just the filename
or a complete path. The function will actually look in two places for
the coff file, in the current directory and in "..\server" directory.


The boot flag argument determines if the coff file is actually booted onto
the board or not. TRUE means yes, boot. The reason for not booting is if
you want to debug using the C8x debuggers.

Bring up the MP debugger, load the server code, then start the host app
debugger. Care must be taken when debugging in this fashion. You must
carefuly step through both sides of the system.

--------------------------------------------------------------------------------
void   RpcQuit();

This shuts down the RPC client system. No more commands can be sent once this
function is called. This function should be called at the end of your
program to close the SDB device.

--------------------------------------------------------------------------------
ULONG  RpcIssueCmnd(ULONG *Cmnd);

Issues a command to the RPC server. This command should only be used from
within custom RPC commands. See the RPC library source code for its usage.

--------------------------------------------------------------------------------
void   ByteSwap(ULONG *wptr);

Handy utility to locally swap the four BYTES of a ULONG.
before: 0x12345678
after:  0x78563412

--------------------------------------------------------------------------------
void   HalfSwap(ULONG *wptr);

Handy utility to locally swap the two USHORTs of a ULONG.
before: 0x12345678
after:  0x56781234

--------------------------------------------------------------------------------
BOOL   System_Alive();

Simple operation check utility. If this function returns true, the RPC
server is alive.

--------------------------------------------------------------------------------
ULONG  System_WriteByte(ULONG SdbAddr, BYTE Val);

This function writes a single BYTE to a location (SdbAddr) on the sdb.
The return value is the sdb address written to.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG System_WriteHalf(ULONG SdbAddr, USHORT Val);

This function writes a single USHORT to a location (SdbAddr) on the sdb.
The return value is the sdb address written to.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_WriteWord(ULONG SdbAddr, ULONG Val);

This function writes a single ULONG to a location (SdbAddr) on the sdb.
The return value is the sdb address written to.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_WriteBlock(ULONG SdbAddr, BYTE *Block, ULONG ByteCt, BYTE Swapping, BOOL SafeMode);

This function writes a block of data from the host to the sdb. The sdb start
address is given in SdbAddr, the host address is a BYTE *Block. ByteCt indicates
the number of bytes to transfer. Swapping determines how the data is swapped
in the FIFO during the transfer. It can be:
CLIENT_NOSWAP
CLIENT_BYTESWAP
CLIENT_WORDSWAP
CLIENT_BYTEWORDSWAP

The safemode argument determines if the transfer should be done in safemode or
not. When in safe mode, the data is transfered in small chunks at a time. These
chunks are smaller than the PCI FIFO size. This allows the client to check
FIFO flag status between each chunk to make sure the server is still alive.
This mode is much slower but good for debugging.

The return value is the address of the ULONG word just beyond the last one
written to during the operation.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
BYTE   System_ReadByte(ULONG SdbAddr);

This function reads a single byte from the sdb at address SdbAddr.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
USHORT System_ReadHalf(ULONG SdbAddr);

This function reads a single USHORT from the sdb at address SdbAddr.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_ReadWord(ULONG SdbAddr);

This function reads a single ULONG from the sdb at address SdbAddr.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_ReadBlock(ULONG SdbAddr, BYTE *Block, ULONG ByteCt, BYTE Swapping, BOOL SafeMode);

This function reads a block of data from the sdb to the host. The sdb start
address is given in SdbAddr, the host address is a BYTE *Block. ByteCt indicates
the number of bytes to transfer. Swapping determines how the data is swapped
in the FIFO during the transfer. It can be:
CLIENT_NOSWAP
CLIENT_BYTESWAP
CLIENT_WORDSWAP
CLIENT_BYTEWORDSWAP

The safemode argument determines if the transfer should be done in safemode or
not. When in safe mode, the data is transfered in small chunks at a time. These
chunks are smaller than the PCI FIFO size. This allows the client to check
FIFO flag status between each chunk to make sure the server is still alive.
This mode is much slower but good for debugging.

The return value is the address of the ULONG word just beyond the last one
read from during the operation.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
BYTE   System_ModifyByte(ULONG SdbAddr, BYTE AndMask, BYTE OrMask);

This function modifies a single BYTE on the SDB. The return value is the
modified value.

val = (val & AndMask) | OrMask;

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
USHORT System_ModifyHalf(ULONG SdbAddr, USHORT AndMAsk, USHORT OrMask);

This function modifies a single USHORT on the SDB. The return value is the
modified value.

val = (val & AndMask) | OrMask;

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_ModifyWord(ULONG SdbAddr, ULONG AndMAsk, ULONG OrMask);

This function modifies a single ULONG on the SDB. The return value is the
modified value.

val = (val & AndMask) | OrMask;

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_FillByte(ULONG SdbAddr, BYTE Val, ULONG ByteCt);

This function fills a ByteCt number of BYTEs on the sdb at address SdbAddr
with a value val.

The return value is the address of the BYTE just beyond the last one
filled during the operation.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_FillHalf(ULONG SdbAddr, USHORT Val, ULONG HalfCt);

This function fills a HalfCt number of USHORTSs on the sdb at address SdbAddr
with a value val.

The return value is the address of the USHORT just beyond the last one
filled during the operation.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_FillWord(ULONG SdbAddr, ULONG Val, ULONG WordCt);

This function fills a WordCt number of ULONGs on the sdb at address SdbAddr
with a value val.

The return value is the address of the ULONG just beyond the last one
filled during the operation.

The C8x MP data cache is bypassed during this operation.

--------------------------------------------------------------------------------
ULONG  System_Malloc(ULONG ByteCt, ULONG Alignment);

This function allocates some memory on the SDB via C80 run-time memalign()
function into its heap. Alignment specifies how to align the allocated block,
4 for a 4-byte alignment, 64 for a 64-byte alignment, ...

The return value is the sdb address of the block.

--------------------------------------------------------------------------------
void   System_Free(ULONG SdbAddr);

Use this function to free up the SDB heap memory allocated from System_Malloc().

--------------------------------------------------------------------------------
void   System_FlushCache(ULONG SdbAddr, ULONG ByteCt);

This function flushes part of the C8x MPs data cache. Specify an sdb address
and a byte count. If any memory in that range is in the MPs data cache, it
is flushed out.

--------------------------------------------------------------------------------
ULONG  System_TaskOpenSema();

This function ends up calling TaskOpenSema(-1,0) on the server side and 
returns the semaphore handle. This does not have much use on the host but
since some of the peripheral library APIs which have been ported to the 
RPC need a semaphore handle for an argument, this function has been added
for completeness.

*****************************************************************************
                            Sample Code
*****************************************************************************
To really get a feel for the use of the RPC libraries, check out the
example code located in SAMPLES\RPC. 

--------------------------------------------------------------------------------
End of SDBRPC.TXT
--------------------------------------------------------------------------------
