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: 1.3 $ 14 * $Date: 2004/12/27 14:00:54 $ 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 320