Commit | Line | Data |
---|---|---|
c906108c SS |
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 |