| 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 | |