gdb/rdi-share/sys.h

   1 /*
   2  * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
   3  *
   4  * This software may be freely used, copied, modified, and distributed
   5  * provided that the above copyright notice is preserved in all copies of the
   6  * software.
   7  */
   8
   9 /* sys.h
  10  ***********************************************************************
  11  * Angel C Libary support channel protocol definitions
  12  *
  13  * $Revision$
  14  *     $Date$
  15  *
  16  *
  17  *
  18  *
  19  * MESSAGE FORMAT
  20  * --------------
  21  * Format of the "data" section of C Lib Support Channel Messages.
  22  * You will notice that the format is much the same as the format
  23  * of ADP messages - this is so that multi-threaded C Libraries can
  24  * be supported.
  25  *
  26  *  unsigned32 reason     - Main C Library reason code.
  27  *  unsigned32 debugID    - Info. describing host debug world;
  28  *                          private to host and used in any target
  29  *                          initiated messages.
  30  *  unsigned32 OSinfo1    \ Target OS information to identify process/thread
  31  *  unsigned32 OSinfo2    / world, etc. These two fields are target defined.
  32  *  byte       args[n]    - Data for message "reason" code.
  33  *
  34  * The "debugID" is defined by the host-end of the protocol, and is used
  35  * by the host to ensure that messages are routed to the correct handler
  36  * program/veneer (eg. imagine several threads having opened stdout and
  37  * each writing to a different window in a windowed debugger).
  38  *
  39  * NOTE: The reason that there is no "size" information, is that the
  40  * message IDs themselves encode the format of any arguments.
  41  *
  42  * For further discussion of the format see adp.h
  43  *
  44  * N.B. All streams are little endian.
  45  *
  46  * CLIB REASON CODE
  47  * ----------------
  48  * The message reason codes contain some information that ties them to
  49  * the channel and direction that the message will be used with. This
  50  * will ensure that even if the message "#define name" is not
  51  * completely descriptive, the message reason code is.
  52  *
  53  *      b31    = direction. 0=Host-to-Target; 1=Target-to-Host;
  54  *      b30-16 = reserved. should be zero
  55  *      b15-0  = message reason code.
  56  *
  57  * Note that typically a request will be initiated by the target side, and
  58  * that the host will then respond with either an acknowledgement or some
  59  * data.  In either case the same reason code will be used, but the direction
  60  * bit will be reveresed.
  61  */
  62
  63 #ifndef __sys_h
  64 #define __sys_h
  65
  66 #ifndef HtoT
  67 #define HtoT    ((unsigned)0 << 31)     /* Host-to-Target message */
  68 #define TtoH    ((unsigned)1 << 31)     /* Target-to-Host message */
  69 #endif
  70
  71 /*
  72  * The following are error codes used in the status field returned on
  73  * sending a message. 0 represents no error having occurred, non-zero
  74  * represents a general error.  More codes should be added as required.
  75  */
  76
  77 #ifndef ErrCode
  78 #define NoError  0x0
  79 #endif
  80
  81 /*************************************************************************/
  82 /* The following are direct conversions of the DeMon SWI's               */
  83 /* NB: nbytes is the number of bytes INCLUDING THE NULL character where  */
  84 /*     applicable.                                                       */
  85
  86 /* This message is used as a  response to a packet whose message
  87  * was not understood.  The return parameter, code is the reason
  88  * code which was not understood. Although intended for use as a
  89  * default case on a received message switch it can also be used
  90  * as a  proper message*/
  91 #define CL_Unrecognised          0x00
  92     /* Unrecognised()
  93      * return(word code)
  94      */
  95
  96 /* Write a character to the terminal.
  97  */
  98 #define CL_WriteC       0x01
  99    /* WriteC(byte data)
 100     * return(word status)
 101     */
 102
 103 /* Write a NULL terminated string of characters to the terminal.  The length
 104  * of the string excluding the NULL terminating character is passed in
 105  * 'nbytes'.
 106  */
 107 #define CL_Write0       0x02
 108    /* Write0(word nbytes, bytes data)
 109     * return(word status)
 110     */
 111
 112 /* Read a character from the terminal - probably the keyboard.
 113  */
 114 #define CL_ReadC        0x04
 115    /* ReadC(void)
 116     * return(word status, byte data)
 117     */
 118
 119 /* Perform system call, pass NULL terminated string to host's command
 120  * line interpreter(NOT AVAILABLE IN PC/DOS RELEASE).  The data byte
 121  * returned holds the return code from the system call.
 122  */
 123 #define CL_System       0x05
 124    /* CLI(word nbytes, bytes data)
 125     * return(word status, word data)
 126     */
 127
 128 /* It returns the address of the null terminated command line string used to
 129  * invoke the program. status will be set to NoError if the command line
 130  * can be returned. Other status values will be treated as error conditions.
 131  */
 132 #define CL_GetCmdLine   0x10
 133    /* GetCmdLine(void)
 134     * return(word status, word nbytes, bytes argline)
 135     */
 136
 137 /* Return the number of centi-seconds since the support code began
 138  * execution.  Only the difference between successive calls can be
 139  * meaningful.
 140  */
 141 #define CL_Clock        0x61
 142    /* Clock(void)
 143     * return(word status, word clks)
 144     */
 145
 146 /* Return the number of seconds since the beginning of 1970.
 147  */
 148 #define CL_Time         0x63
 149    /* Time(void)
 150     * return(word status, word time)
 151     */
 152
 153 /* Delete(remove, un-link, wipe, destroy) the file named by the
 154  * NULL-terminated string 'name'.
 155  */
 156 #define CL_Remove       0x64
 157    /* Remove(word nbytes, bytes name)
 158     * return(word status)
 159     */
 160
 161 /* Rename the file specified by the NULL-terminated string 'oname'
 162  * to 'nname'.
 163  */
 164 #define CL_Rename       0x65
 165    /* Rename(word nbytes, bytes oname, word nbytes, bytes nname)
 166     * return(word status)
 167     */
 168
 169 /* 'name' specifies a NULL-terminated string containing a file name or a
 170  * device name.  Opens the file/device and returns a non-zero handle on
 171  * success that can be quoted to CL_Close, CL_Read, CL_Write, CL_Seek,
 172  * CL_Flen or CL_IsTTY.  The mode is an integer in the range 0-11:-
 173  *
 174  * Mode:              0   1   2   3   4   5   6   7   8   9   10   11
 175  * ANSI C fopen mode: r   rb  r+  r+b w   wb  w+  w+b a   ab  a+   a+b
 176  *
 177  * Values 12-15 are illegal.  If 'name' is ":tt" the stdin/stdout is
 178  * opened depending on whether 'mode' is read or write.
 179  */
 180 #define CL_Open         0x66
 181    /* Open(word nbytes, bytes name, word mode)
 182     * return(word handle)
 183     */
 184
 185 /* 'handle' is a file handle previously returned by CL_Open.  CL_Close
 186  * closes the file.
 187  */
 188 #define CL_Close        0x68
 189    /* Close(word handle)
 190     * return(word status)
 191     */
 192
 193 /* Writes data of length nbytes to the file/device specified by
 194  * handle.  nbtotal represents the total number of bytes to be
 195  * written, whereas nbytes is the number of bytes in this packet
 196  *
 197  * If nbtotal is <= DATASIZE - CL_Write message header size in the
 198  * packet then nbytes = nbtotal and the number of bytes not written
 199  * is returned.  If nbtotal is > the packet size then the CL_Write
 200  * must be followed by a number of CL_WriteX's to complete the write,
 201  * the nbytes returned by CL_Write can be ignored
 202  * If the status word returned is non zero, an error has occurred and
 203  * the write request has been aborted.
 204  *
 205  */
 206 #define CL_Write        0x69
 207    /* Write(word handle, word nbtotal, word nbytes, bytes data)
 208     * return(word status, word nbytes)
 209     */
 210
 211 /* Write Extension is a reads a continuation of data from a CL_Write
 212  * which was too big to fit in a single packet.
 213  * nbytes is the number of bytes of data in this packet, the
 214  * returned value of nbytes can be ignored except if it is the
 215  * last packet, in which case it is the number of bytes that were NOT
 216  * written
 217  */
 218 #define CL_WriteX       0x6A
 219    /* WriteX(word nbytes, bytes data)
 220     * return(word status, word nbytes)
 221     */
 222
 223 /* Reads 'nbytes' from the file/device specified by 'handle'.
 224  *
 225  * If nbytes <= DATASIZE then the read will occur in a single packet
 226  * and the returned value of nbytes will be the number of bytes actually
 227  * read and nbmore will be 0. If nbytes> DATASIZE then multiple packets
 228  * will have to be used ie CL_Read followed by 1 or more CL_ReadX
 229  * packets. In this case CL_Read will return nbytes read in the current
 230  * packet and nbmore representing how many more bytes are expected to be
 231  * read
 232  * If the status word is non zero then the request has completed with an
 233  * error. If the status word is 0xFFFFFFFF (-1) then an EOF condition
 234  * has been reached.
 235  */
 236 #define CL_Read         0x6B
 237    /* Read(word handle, word nbytes)
 238     * return(word status, word nbytes, word nbmore, bytes data)
 239     */
 240
 241 /* Read eXtension returns a continuation of the data that was opened for
 242  * read in the earlier CL_Read. The return value nbytes is the number of
 243  * data bytes in the packet, nbmore is the number of bytes more that are
 244  * expected to be read in subsequent packets.
 245  */
 246 #define CL_ReadX        0x6C
 247   /* ReadX()
 248    * return(word status, word nbytes, word nbmore, bytes data)
 249    */
 250
 251 /* Seeks to byte position 'posn' in the file/device specified by 'handle'.
 252  */
 253 #define CL_Seek         0x6D
 254    /* Seek(word handle, word posn)
 255     * return(word status)
 256     */
 257
 258 /* Returns the current length of the file specified by 'handle' in 'len'.
 259  * If an error occurs 'len' is set to -1.
 260  */
 261 #define CL_Flen         0x6E
 262    /* Flen(word handle)
 263     * return(word len)
 264     */
 265
 266 /* Returns NoError if 'handle' specifies an interactive device, otherwise
 267  * returns GenError
 268  */
 269 #define CL_IsTTY        0x6F
 270    /* IsTTY(word handle)
 271     * return(word status)
 272     */
 273
 274 /* Returns a temporary host file name. The maximum length of a file name
 275  * is passed to the host. The TargetID is some identifier from the target
 276  * for this particular temporary filename. This value is could be used
 277  * directly in the generation of the filename.
 278  *
 279  * If the host cannot create a suitable name or the generated name is too
 280  * long then status is non zero. status will be NoError if the host can create
 281  * a name.
 282  */
 283 #define CL_TmpNam       0x70
 284    /* TmpNam(word maxlength, word TargetID)
 285     * return(word status, word nbytes, bytes fname)
 286     */
 287
 288 /* Note there is no message for Exit, EnterOS, InstallHandler or
 289  * GenerateError as these will be supported entirely at the host end,
 290  * or by the underlying Operating system.
 291  */
 292
 293 #define CL_UnknownReason (-1)
 294
 295 extern unsigned int GetRaiseHandler( void );
 296 extern unsigned int SysLibraryHandler(unsigned int sysCode, unsigned int *args);
 297 extern void angel_SysLibraryInit(void);
 298
 299 /*
 300  * Function: Angel_IsSysHandlerRunning
 301  *  Purpose: return whether or not SysLibraryHandler is running
 302  *
 303  *   No paramaters
 304  *
 305  *   Returns 1 if SysLibraryHandler is running
 306  *           0 otherwise
 307  */
 308 extern int Angel_IsSysHandlerRunning(void);
 309
 310 #ifdef ICEMAN2
 311 /* This function exists in an ICEman2 system only, and can be called by
 312  * debug support code when the debugger tells it how much memory the
 313  * target has.  This will then be used to deal with the HEAPINFO SWI
 314  */
 315 extern void angel_SetTopMem(unsigned addr);
 316 #endif
 317
 318 #endif
 319