rpcserv.h

PNX系列设备驱动 PNX系列设备驱动

/*
 *  COPYRIGHT (c) 1995 by Philips Semiconductors
 *
 *   +-----------------------------------------------------------------+
 *   | THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY ONLY BE USED |
 *   | AND COPIED IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF SUCH  |
 *   | A LICENSE AND WITH THE INCLUSION OF THE THIS COPY RIGHT NOTICE. |
 *   | THIS SOFTWARE OR ANY OTHER COPIES OF THIS SOFTWARE MAY NOT BE   |
 *   | PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON. THE   |
 *   | OWNERSHIP AND TITLE OF THIS SOFTWARE IS NOT TRANSFERRED.        |
 *   +-----------------------------------------------------------------+
 *
 *  Module name              : RPCServ.h    1.19
 *
 *  Module type              : SPECIFICATION
 *
 *  Title                    : HostCall server, serving part
 *
 *  Author                   : Juul van der Spek 
 *
 *  Last update              : 17:14:33 - 98/05/08
 *
 *  Reviewed                 : 
 *
 *  Revision history         : 
 *
 *  Description              :  
 *
 *            This module is part of an implementation of the server part  
 *            for a HostCall interface. HostCall is the software component 
 *            which is required by the TCS toolset to adapt the programs 
 *            generated by this toolset to a specific host (see file 
 *            HostCall.h in the TCS include dir).
 *
 *            RPCServ is the part of the implementation which runs on the
 *            host, serving all IO requests of the TM-1 application. 
 *            RPCServ is one of two modules of this host-resident part, and
 *            defines *how* messages should be served; it still is host
 *            independent. The other part of this implementation, TM1IF,
 *            contains all host specific issues which are communication
 *            with the target and the ability to start a number of server
 *            tasks.
 *
 *            RPCServ is the counterpart of RPCClient on the target, and
 *            TM1IF is the counterpart of HostIF on the target. However,
 *            contrary to the target situation, where RPCClient is built
 *            on top of HostIF, on the host side TM1IF is built on top of
 *            RPCServ.
 *
 *            The interface to this module is as follows: 
 *
 *             1) An initialisation function is provided which takes 
 *                a number of IO functions as input.
 *                By these IO functions, the actual host can control the IO
 *                while serving target IO requests.
 *                For instance, certain IO channels (typically standard 
 *                in/out) can be redirected. This initialisation function
 *                must be called once before any other use.
 *
 *             2) A termination function is provided for cleanup. 
 *
 *             3) A function for adding information on a new node is
 *                provided. Information consists of a node number,
 *                command line arguments, and values for the standard
 *                file descriptors. This function must be used before
 *                a command is passed to the serve routine (see next).
 *                A node is automatically removed from the internal 
 *                administration when its 'exit' message is received.
 *                In this case, the client of this module is notified
 *                via the 'exit' I/O function.
 *
 *             4) A serve routine is provided for serving commands
 *                obtained from any of the previously `added` nodes.
 *                serving might call one of the IO functions provided
 *                with 1), and/or it might require specific node information
 *                provided with 3). Serving takes care of endian conversion,
 *                host/target address translation, and further interpretation 
 *                of the provided command.
 *
 *
 *            NB: This interface does not provide for loading and
 *                starting the TM1 appication. 
 */

#ifndef  RPCServ_INCLUDED
#define  RPCServ_INCLUDED


/*----------------------------includes---------------------------------------*/

#include "tmtypes.h"
#include "HostCall.h"

#if	defined(__cplusplus)
extern	"C"	{
#endif	/* defined(__cplusplus) */


/*----------------------------definitions-------------------------------------*/


/*
 * Function types of IO functions:
 */

typedef Int32    (*RPCServ_OpenFunc  )
                         (  String	     path,
	                    Int32   	     oflag,
	                    Int32   	     mode
                         );

typedef Int32    (*RPCServ_OpenDllFunc  )
                         (  String	     path
                         );

typedef Int32    (*RPCServ_CloseFunc )
                         (  Int32            file
                         );

typedef Int32    (*RPCServ_ReadFunc  )
                         (  Int32            file,
	                    Address          buf,
	    		    Int32   	     nbyte
                         );

typedef Int32    (*RPCServ_WriteFunc )
                         (  Int32            file,
	                    Address          buf,
	                    Int32   	     nbyte 
                         );

typedef Int32    (*RPCServ_SeekFunc )
                         (  Int32            file,
                            Int32            offset,
                            Int32            whence
                         );

typedef Int32    (*RPCServ_IsattyFunc )
                         (  Int32            file
                         );

typedef Int32    (*RPCServ_FstatFunc )
                         (  Int32            file,
                            struct stat     *buff
                         );

typedef Int32    (*RPCServ_FcntlFunc )
                         (  Int32            file,
                            Int32            cmd,
                            Int32            arg
                         );

typedef Int32    (*RPCServ_StatFunc )
                         (  String	     path,
                            struct stat     *buff
                         );

typedef Int32    (*RPCServ_ExitFunc)( UInt32 node_id, Int32 status );





/*
 * Node information structure:
 */

typedef void (*RPCServ_Node_Terminator) ( Pointer data );



typedef struct {
           UInt32    node_number;
           UInt32    argc;
           String   *argv;
           UInt32    Stdin;
           UInt32    Stdout;
           UInt32    Stderr;
           UInt32    address_shift;
           UInt32    sdram_base;
           UInt32    sdram_limit;

           RPCServ_Node_Terminator  terminate;
           Pointer                  data;
} RPCServ_NodeInfo;





/*----------------------------functions---------------------------------------*/



/*
 * Function         : Initialise this module, and make the
 *                    I/O callback functions known to it.
 * Parameters       : open .. exit        (I) IO functions.
 *                    endian              (I) node's endianness
 * Function Result  : True iff initialisation succeeded
 */

Bool RPCServ_init(
	RPCServ_OpenFunc    open,
	RPCServ_OpenDllFunc open_dll,
	RPCServ_CloseFunc   close,
	RPCServ_ReadFunc    read,
	RPCServ_WriteFunc   write,
	RPCServ_SeekFunc    seek,
	RPCServ_IsattyFunc  isatty,
	RPCServ_FstatFunc   fstat,
	RPCServ_FcntlFunc   fcntl,
	RPCServ_StatFunc    stat,
	RPCServ_ExitFunc    exit,
        Endian              endian                
     );



/*
 * Function         : Serve a command, using the node specific information
 *                    provided with RPCServ_add_node_info, and the I/O functions
 *                    provided with RPCServ_init.
 * Parameters       : raw_command   (I) Raw pointer to command, as obtained
 *                                      from target. The command still has to
 *                                      be address translated and endian 
 *                                      converted.
 * Function Result  : True iff serving succeeded.
 */

Bool RPCServ_serve( Pointer raw_command );




/*
 * Function         : Add information on new node 
 * Parameters       : node_number         (I) Node number assigned to executable
 *                                            via TMDownLoader interface.
 *                    argc, argv          (I) Command line arguments
 *                    Stdin,Stdout,Stderr (I) file descriptors to be used as
 *                                            standard file descriptors.
 *                                            NB: these must be legal parameter
 *                                                values for the IO functions
 *                    address_shift       (I) the difference between the virtual
 *                                            and physical address of the each location
 *                                            in the node's SDRAM, as seen from the host
 *                    sdram_base          (I) physical address of the node's SDRAM start
 *                    sdram_limit         (I) physical address of the node's SDRAM limit
 *                    terminate           (I) node termination handler, called with
 *                                            the next data argument when node terminates
 *                                            or is killed.
 *                    data                (I) additional, monitor specific data
 * Function Result  : True iff node addition succeeded. Reasons for failing are
 *                    node already added and not exited, and node number out of
 *                    reasonable range (assuming that nodes are numbered in
 *                    the range 0 .. number_of_nodes-1).
 */

Bool RPCServ_add_node_info( 
           UInt32    node_number,
           UInt32    argc,
           String   *argv,
           UInt32    Stdin,
           UInt32    Stdout,
           UInt32    Stderr,
           UInt32    address_shift,
           UInt32    sdram_base,
           UInt32    sdram_limit,

           RPCServ_Node_Terminator  terminate,
           Pointer                  data
     );





/*
 * Function         : Remove information on node, when present. 
 * Parameters       : node_number         (I) Node number assigned to executable
 *                                            via TMDownLoader interface.
 * Function Result  : -
 */

void RPCServ_remove_node_info( UInt32 node_number );



/*
 * Function         : Get added information on node 
 * Parameters       : node_number   (I) Node number which was previously used
 *                                      in call to RPCServ_add_node_info
 * Function Result  : A pointer to the node information record, or
 *                    Null when the node_number (currently) has no information
 *                    associated.
 */

RPCServ_NodeInfo*
    RPCServ_get_node_info( UInt32 node_number );





/*
 * Function         : Convert a pointer from one of the DSP's SDRAM to host address 
 * Parameters       : p  (I) pointer representation in DSP terms (possibly endian swapped,
 *                           and physical)
 * Function Result  : A decent pointer in host terms.
 */

Pointer
    RPCServ_raw_to_host( Pointer p );





/*
 * Function         : Convert a pointer from one of the DSP's SDRAM to 
 *                    node information. 
 * Parameters       : p  (I) pointer representation in DSP terms (possibly endian swapped,
 *                           and physical)
 * Function Result  : A decent pointer in host terms.
 */

RPCServ_NodeInfo*
    RPCServ_raw_to_info( Pointer p );





/*
 * Function         : Terminate this module
 * Parameters       : -
 */

void RPCServ_term();





#if	defined(__cplusplus)
}
#endif	/* defined(__cplusplus) */

#endif /* RPCServ_INCLUDED */