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 | /* -*-C-*- | |
10 | * | |
11 | * $Revision$ | |
12 | * $Date$ | |
13 | * | |
14 | * | |
15 | * Project: ANGEL | |
16 | * | |
17 | * Title: Public client interface to devices | |
18 | */ | |
19 | ||
20 | #ifndef angel_devclnt_h | |
21 | #define angel_devclnt_h | |
22 | ||
23 | /* | |
24 | * This header exports the public interface to Angel-compliant device | |
25 | * drivers. | |
26 | * | |
27 | * They are intended to be used solely by Angel, not by the User | |
28 | * Application. See devappl.h for the User Application interface to | |
29 | * the device drivers. | |
30 | */ | |
31 | ||
32 | #include "devices.h" | |
33 | ||
34 | /* General purpose constants, macros, enums, typedefs */ | |
35 | ||
36 | /* | |
37 | * possible channels at device level | |
38 | * | |
39 | * XXX | |
40 | * | |
41 | * these are used as array indices, so be specific about their values | |
42 | */ | |
43 | typedef enum DevChanID { | |
44 | DC_DBUG = 0, /* reliable debug packets | |
45 | * containing SDBG, CLIB,UDBG, etc.) */ | |
46 | DC_APPL = 1, /* application packets */ | |
47 | DC_NUM_CHANNELS | |
48 | } DevChanID; | |
49 | ||
50 | /* Publically-accessible globals */ | |
51 | /* none */ | |
52 | ||
53 | /* Public functions */ | |
54 | ||
55 | /* | |
56 | * Function: angel_DeviceWrite | |
57 | * Purpose: The main entry point for asynchronous writes to a device. | |
58 | * | |
59 | * Params: | |
60 | * Input: devID index of the device to write to | |
61 | * buff data to write | |
62 | * length how much data to write | |
63 | * callback callback here when write finished | |
64 | * or error | |
65 | * cb_data data to be passed to callback | |
66 | * chanID device channel to use | |
67 | * Output: - | |
68 | * In/Out: - | |
69 | * | |
70 | * Returns: DE_OKAY write request is underway | |
71 | * DE_NO_DEV no such device | |
72 | * DE_BAD_DEV device does not support angel writes | |
73 | * DE_BAD_CHAN no such device channel | |
74 | * DE_BUSY device busy with another write | |
75 | * DE_INVAL silly length | |
76 | * | |
77 | * Reads globals: - | |
78 | * Modifies globals: - | |
79 | * | |
80 | * Other side effects: - | |
81 | * | |
82 | * Commence asynchronous transmission of a buffer on a device. The | |
83 | * callback will occur when the write completes or if there is an | |
84 | * error. | |
85 | * | |
86 | * This must be called for each packet to be sent. | |
87 | */ | |
88 | ||
89 | DevError angel_DeviceWrite(DeviceID devID, p_Buffer buff, | |
90 | unsigned length, DevWrite_CB_Fn callback, | |
91 | void *cb_data, DevChanID chanID); | |
92 | ||
93 | ||
94 | /* | |
95 | * Function: angel_DeviceRegisterRead | |
96 | * Purpose: The main entry point for asynchronous reads from a device. | |
97 | * | |
98 | * Params: | |
99 | * Input: devID index of the device to read from | |
100 | * callback callback here when read finished | |
101 | * or error | |
102 | * cb_data data to be passed to callback | |
103 | * get_buff callback to be used to acquire buffer | |
104 | * for incoming packets | |
105 | * getb_data data to be passed to get_buff | |
106 | * chanID device channel to use | |
107 | * Output: - | |
108 | * In/Out: - | |
109 | * | |
110 | * Returns: DE_OKAY read request is underway | |
111 | * DE_NO_DEV no such device | |
112 | * DE_BAD_DEV device does not support angel reads | |
113 | * DE_BAD_CHAN no such device channel | |
114 | * DE_BUSY device busy with another read | |
115 | * DE_INVAL silly length | |
116 | * | |
117 | * Reads globals: - | |
118 | * Modifies globals: - | |
119 | * | |
120 | * Other side effects: - | |
121 | * | |
122 | * Register asynchronous packet read from a device. The callback will | |
123 | * occur when the read completes or if there is an error. | |
124 | * | |
125 | * This is persistent: the read remains registered for all incoming | |
126 | * packets on the device channel. | |
127 | */ | |
128 | ||
129 | DevError angel_DeviceRegisterRead(DeviceID devID, | |
130 | DevRead_CB_Fn callback, void *cb_data, | |
131 | DevGetBuff_Fn get_buff, void *getb_data, | |
132 | DevChanID chanID); | |
133 | ||
134 | ||
135 | /* | |
136 | * Function: angel_DeviceControl | |
137 | * Purpose: Call a control function for a device | |
138 | * | |
139 | * Params: | |
140 | * Input: devID index of the device to control to | |
141 | * op operation to perform | |
142 | * arg parameter depending on op | |
143 | * | |
144 | * Returns: DE_OKAY control request is underway | |
145 | * DE_NO_DEV no such device | |
146 | * DE_BAD_OP device does not support operation | |
147 | * | |
148 | * Reads globals: - | |
149 | * Modifies globals: - | |
150 | * | |
151 | * Other side effects: - | |
152 | * | |
153 | * Have a device perform a control operation. Extra parameters vary | |
154 | * according to the operation requested. | |
155 | */ | |
156 | ||
157 | DevError angel_DeviceControl(DeviceID devID, DeviceControl op, void *arg); | |
158 | ||
159 | ||
160 | /* | |
161 | * Function: angel_ReceiveMode | |
162 | * Purpose: enable or disable reception across all devices | |
163 | * | |
164 | * Params: | |
165 | * Input: mode choose enable or disable | |
166 | * | |
167 | * Pass the mode parameter to the receive_mode control method of each device | |
168 | */ | |
169 | ||
170 | void angel_ReceiveMode(DevRecvMode mode); | |
171 | ||
172 | ||
173 | /* | |
174 | * Function: angel_ResetDevices | |
175 | * Purpose: reset all devices | |
176 | * | |
177 | * Params: none | |
178 | * | |
179 | * Call the reset control method for each device | |
180 | */ | |
181 | ||
182 | void angel_ResetDevices(void); | |
183 | ||
184 | ||
185 | /* | |
186 | * Function: angel_InitialiseDevices | |
187 | * Purpose: initialise the device driver layer | |
188 | * | |
189 | * Params: none | |
190 | * | |
191 | * Set up the device driver layer and call the init method for each device | |
192 | */ | |
193 | ||
194 | void angel_InitialiseDevices(void); | |
195 | ||
196 | ||
197 | /* | |
198 | * Function: angel_IsAngelDevice | |
199 | * Purpose: Find out if a device supports Angel packets | |
200 | * | |
201 | * Params: | |
202 | * Input: devID index of the device to control to | |
203 | * | |
204 | * Returns: TRUE supports Angel packets | |
205 | * FALSE raw device | |
206 | * | |
207 | * Reads globals: - | |
208 | * Modifies globals: - | |
209 | * | |
210 | * Other side effects: - | |
211 | */ | |
212 | ||
213 | bool angel_IsAngelDevice(DeviceID devID); | |
214 | ||
215 | ||
216 | #if !defined(MINIMAL_ANGEL) || MINIMAL_ANGEL == 0 | |
217 | ||
218 | /* | |
219 | * Function: angel_ApplDeviceHandler | |
220 | * Purpose: The entry point for User Application Device Driver requests | |
221 | * in a full functiionality version of Angel. | |
222 | * It will never be called directly by the User Application, | |
223 | * but gets called indirectly, via the SWI handler. | |
224 | * | |
225 | * Params: | |
226 | * Input: swi_r0 Argument to SWI indicating that | |
227 | * angel_ApplDeviceHandler was to be called. This | |
228 | * will not be used in this function, but is needed | |
229 | * by the SWI handler. | |
230 | * arg_blk pointer to block of arguments | |
231 | * arg_blk[0] is one of | |
232 | * angel_SWIreason_ApplDevice_{Read,Write,Yield} | |
233 | * which indicates which angel_Device* fn is to | |
234 | * be called. arg_blk[1] - arg_blk[n] are the | |
235 | * arguments to the corresponding | |
236 | * angel_ApplDevice* function. | |
237 | * Output: - | |
238 | * In/Out: - | |
239 | * | |
240 | * Returns: whatever the specified angel_Device* function | |
241 | * returns. | |
242 | * | |
243 | * Reads globals: - | |
244 | * Modifies globals: - | |
245 | * | |
246 | * Other side effects: - | |
247 | * | |
248 | * This has the side effects of angel_Device{Read,Write,Yield} | |
249 | * depending upon which is operation is specified as described above. | |
250 | */ | |
251 | ||
252 | DevError angel_ApplDeviceHandler( | |
253 | unsigned swi_r0, unsigned *arg_blk | |
254 | ); | |
255 | ||
256 | #endif /* ndef MINIMAL_ANGEL */ | |
257 | ||
258 | #endif /* ndef angel_devclnt_h */ | |
259 | ||
260 | /* EOF devclnt.h */ |