tm1if.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              : TM1IF.h    1.17
 *
 *  Module type              : SPECIFICATION
 *
 *  Title                    : HostCall server, Host dependent part
 *
 *  Author                   : Juul van der Spek 
 *
 *  Last update              : 12:23:41 - 99/12/10
 *
 *  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).
 *
 *            HostIF is the part of the implementation which runs on the
 *            host, serving all IO requests of the TM-1 application. 
 *            HostIF is one of two modules of this host-resident part, and
 *            defines all host specific issues which are communication
 *            with the target and the ability to start a number of server
 *            tasks. The other part, RPCClient, defines *how* messages 
 *            should be served; RPCClient it still is host independent.
 *
 *            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. Hence TM1IF forms the external interface of the 
 *            server pair.
 *
 *            The interface to this module is as follows: First, it should
 *            be initialised. Second, a number of nodes should be defined, 
 *            specifying node specific information. 
 *            After this, the nodes can be started and a communication
 *            session with these nodes can be started by means of function
 *            TM1IF_start_serving; depending on the implementation, a call
 *            to this function either immediately returns, with a number
 *            of serving tasks created for handling target's IO requests,
 *            or it blocks until function TM1IF_term is called (typically
 *            by the exit handler, when the last node has reported termination).
 *
 *            Having a pool of servers reduces the possibility that serving
 *            is halted due to serving requests which take a longer 
 *            time to complete. For instance, when running pSOS on the 
 *            target with one task requesting keyboard input from the host, 
 *            the current implementation of RPCClient will stop serving 
 *            requests when only one server task is selected: while blocked 
 *            on the keyboard, it will not be able to serve requests from 
 *            other pSOS tasks. 
 *            The current host (with the OS used) might or might not be
 *            able to dispatch multiple tasks, so start_serving returns
 *            one of the following results:
 *                - TM1IF_Serving_Failed
 *                           Initialisation (e.g. setup of target
 *                           communication, or server task creation) 
 *                           failed.
 *                - TM1IF_Serving_Started
 *                           The servers have been created, and
 *                           are now busy serving.
 *                           Serving should be stopped using the
 *                           TM1IF_term function.
 *                - TM1IF_Serving_Completed
 *                           TM1IF was not capable of creating independent 
 *                           serving tasks, so the TM-1 application
 *                           has been entirely served during the call
 *                           to start_serving.
 *           
 *            NB: This interface does not provide for loading and
 *                starting the TM1 appication. 
 */

#ifndef  TM1IF_INCLUDED
#define  TM1IF_INCLUDED


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

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


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

/*
 * Enumeration of possible results of
 * function TM1IF_start_serving (see below):
 */
typedef enum {
    TM1IF_Serving_Failed,
    TM1IF_Serving_Started,
    TM1IF_Serving_Completed
} TM1IF_Served_Status;




/*
 * 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 TM1IF_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         : 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
 *                    data                (I) additional, monitor specific data
 * Function Result  : True iff add succeeded.
 */

Bool TM1IF_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,
           Pointer   data
     );



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

void TM1IF_remove_node_info( UInt32 node_number );



/*
 * Function         : Start serving the (independently started)
 *                    TM-1 application. Serving should use the specified
 *                    IO functions, and use the specified file descriptors
 *                    for stdin, stdout and stderr. It should try to 
 *                    start the requested number of serving tasks and return,
 *                    but when there are no capabilities for starting 
 *                    tasks this function itself can act as server before
 *                    it returns.
 * Function Result  : see module header
 * Precondition     : -
 * Postcondition    : -
 * Sideeffects      : -
 */

TM1IF_Served_Status
        TM1IF_start_serving( );




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

void TM1IF_term();


/*
 * Endian- and address conversion routines between target and hos:
 */
UInt32  TM1IF_endian_swap       ( UInt32 value );
UInt32  TM1IF_endian_swap_short ( UInt32 value );
Address TM1IF_tm2host           ( RPCServ_NodeInfo *ninfo, Address tm_address   );
Address TM1IF_host2tm           ( RPCServ_NodeInfo *ninfo, Address host_address );



/*
 * In case of RPC over a serial line, the following
 * define pointers to the received command data or to the
 * reserved result buffers:
 */

#ifdef SERIAL_RPC
extern Pointer           TM1IF_in_buffer;
extern Pointer           TM1IF_in_buffer2;
extern Pointer           TM1IF_result_buffer;
extern HostCall_command* TM1IF_command_buffer;
#endif




#endif /* TM1IF_INCLUDED */