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: 1.3 $ 12 * $Date: 2004/12/27 14:00:54 $ 13 * 14 */ 15 #ifndef angsd_hostchan_h 16 #define angsd_hostchan_h 17 18 /* A temporary sop to older compilers */ 19 #if defined (__NetBSD__) || defined (unix) 20 # ifndef __unix /* (good for long-term portability?) */ 21 # define __unix 1 22 # endif 23 #endif 24 25 /* struct timeval */ 26 #if defined(__unix) || defined(__CYGWIN__) 27 # include <sys/time.h> 28 #else 29 # include "winsock.h" 30 # include "time.h" 31 #endif 32 33 #include "chandefs.h" 34 #include "adperr.h" 35 #include "devsw.h" 36 37 /* 38 * asynchronous processing modes 39 */ 40 enum AsyncMode 41 { 42 async_block_on_nothing, 43 async_block_on_read, 44 async_block_on_write 45 }; 46 47 #ifndef __cplusplus 48 typedef enum AsyncMode AsyncMode; 49 #endif 50 51 /* 52 * prototype for channels callback function 53 */ 54 typedef void (*ChannelCallback)(Packet *packet, void *state); 55 56 /* 57 * Function: Adp_initSeq 58 * Purpose: initialise the channel protocol and sequence numbers 59 * 60 * Params: none 61 * 62 * Returns: Nothing 63 */ 64 extern void Adp_initSeq(void); 65 66 /* 67 * Function: Adp_addToQueue 68 * Purpose: chain a Packet to the end of a linked list of such structures 69 * 70 * Params: 71 * In/Out: head Head of the linked list 72 * 73 * newpkt Packet to be chained onto the list 74 * 75 * Returns: Nothing 76 */ 77 extern void Adp_addToQueue(Packet **head, Packet *newpkt); 78 79 /* 80 * Function: removeFromQueue 81 * Purpose: remove a Packet from the head of a linked list of such structures 82 * 83 * Params: 84 * In/Out: head Head of the linked list 85 * 86 * Returns: Old head from the linked list 87 * 88 * Post-conditions: Second element in the list will be the new head. 89 */ 90 91 extern Packet *Adp_removeFromQueue(Packet **head); 92 93 /* 94 * Set log file and Enable/disable logging of ADP packets to file. 95 */ 96 97 void Adp_SetLogfile(const char *filename); 98 void Adp_SetLogEnable(int logEnableFlag); 99 100 /* 101 * Function: Adp_OpenDevice 102 * Purpose: Open a device to use for channels communication. This is a 103 * very thin veneer to the device drivers: what hostchan.c 104 * will do is call DeviceMatch for each device driver until it 105 * finds a driver that will accept name and arg, then call 106 * DeviceOpen for that device. 107 * 108 * Pre-conditions: No previous open is still active 109 * 110 * Params: 111 * Input: name Identifies which device to open. This can either be 112 * a host specific identifier (e.g. "/dev/ttya", 113 * "COM1:"), or a number which is used to refer to 114 * `standard' interfaces, so "1" would be the first host 115 * interface, "2" the second, and so on. 116 * 117 * arg Driver specific arguments. For example, some serial 118 * drivers accept speed and control arguments such as 119 * "9600" or "19200/NO_BREAK". These arguments are 120 * completely free-form: it is the individual drivers 121 * which do the necessary interpretation. 122 * 123 * heartbeat_on Incicates if the heartbeat is configured to be 124 * used or not, true if it is, false otherwise 125 * 126 * Returns: 127 * OK: adp_ok 128 * Error: adp_device_not_known, 129 * adp_device_open_failed 130 * adp_device_already_open 131 */ 132 AdpErrs Adp_OpenDevice(const char *name, const char *arg, 133 unsigned int heartbeat_on); 134 135 /* 136 * Function: Adp_CloseDevice 137 * Purpose: Close the device used for channels communication. 138 * 139 * Params: None 140 * 141 * Returns: 142 * OK: adp_ok 143 * Error: adp_device_not_open 144 */ 145 AdpErrs Adp_CloseDevice(void); 146 147 /* 148 * Function: Adp_Ioctl 149 * Purpose: Perform miscellaneous control operations on 150 * the device used for channels communication. 151 * This is a minimal veneer to DevSW_Ioctl. 152 * 153 * Params: 154 * Input: opcode Reason code indicating the operation to perform. 155 * In/Out: args Pointer to opcode-sensitive arguments/result space. 156 * 157 * 158 * Returns: 159 * OK: adp_ok 160 * Error: adp_device_not_open, adp_failed 161 */ 162 AdpErrs Adp_Ioctl(int opcode, void *args); 163 164 /* 165 * Function: Adp_ChannelRegisterRead 166 * Purpose: Register a callback function for received packets on a given 167 * channel 168 * 169 * Params: 170 * Input: chan The channel the callback function is for. 171 * 172 * cbfunc The callback function. If NULL, then the current 173 * callback is removed. 174 * 175 * cbstate State pointer to pass into the callback function 176 * 177 * Returns: 178 * OK: adp_ok 179 * Error: adp_device_not_open 180 * adp_bad_channel_id 181 * 182 * Post-conditions: The callback function is responsible for freeing the 183 * packet that is passed to it, when that packet is 184 * no longer needed. 185 */ 186 #ifdef __cplusplus 187 extern "C" { 188 #endif 189 190 191 extern AdpErrs Adp_ChannelRegisterRead(const ChannelID chan, 192 const ChannelCallback cbfunc, 193 void *cbstate); 194 195 #ifdef __cplusplus 196 } 197 #endif 198 /* 199 * Function: Adp_ChannelRead 200 * Purpose: Wait until a packet has been read for a given channel, and 201 * then return it. Callbacks for other channels are still 202 * active while this read is blocking. 203 * 204 * Pre-conditions: No callback has been already been registered for 205 * the channel. 206 * 207 * Params: 208 * Input: chan The channel to read. 209 * 210 * Output: packet The received packet. 211 * 212 * Returns: 213 * OK: adp_ok 214 * Error: adp_device_not_open 215 * adp_bad_channel_id 216 * adp_callback_already_registered 217 * 218 * Post-conditions: The calling function is responsible for freeing the 219 * received packet, when that packet is no longer 220 * needed. 221 */ 222 AdpErrs Adp_ChannelRead(const ChannelID chan, Packet **packet); 223 224 /* 225 * Function: Adp_ChannelWrite 226 * Purpose: Write a packet to the given channel 227 * 228 * Pre-conditions: Channel must have been previously opened. 229 * 230 * Params: 231 * Input: chan The channel to write. 232 * 233 * packet The packet to write. 234 * 235 * Returns: 236 * OK: adp_ok 237 * Error: adp_device_not_open 238 * adp_bad_channel_id 239 * 240 * Post-conditions: The packet being written becomes the "property" of 241 * Adp_ChannelWrite, which is responsible for freeing 242 * the packet when it is no longer needed. 243 */ 244 AdpErrs Adp_ChannelWrite(const ChannelID chan, Packet *packet); 245 246 /* 247 * Function: Adp_ChannelWriteAsync 248 * Purpose: Write a packet to the given channel, but don't wait 249 * for the write to complete before returning. 250 * 251 * Pre-conditions: Channel must have been previously opened. 252 * 253 * Params: 254 * Input: chan The channel to write. 255 * 256 * packet The packet to write. 257 * 258 * Returns: 259 * OK: adp_ok 260 * Error: adp_device_not_open 261 * adp_bad_channel_id 262 * 263 * Post-conditions: The packet being written becomes the "property" of 264 * Adp_ChannelWrite, which is responsible for freeing 265 * the packet when it is no longer needed. 266 */ 267 AdpErrs Adp_ChannelWriteAsync(const ChannelID chan, Packet *packet); 268 269 /* 270 * Function: Adp_AsynchronousProcessing 271 * Purpose: This routine should be called from persistent any idle loop 272 * to give the data I/O routines a chance to poll for packet 273 * activity. Depending upon the requested mode, this routine 274 * may, or may not, block. 275 * 276 * Params: 277 * Input: mode Specifies whether to block until a complete packet 278 * has been read, all pending writes have completed, 279 * or not to block at all. 280 * 281 * Returns: Nothing. 282 */ 283 void Adp_AsynchronousProcessing(const AsyncMode mode); 284 285 /* 286 * prototype for DC_APPL packet handler 287 */ 288 typedef void (*DC_Appl_Handler)(const DeviceDescr *device, Packet *packet); 289 290 /* 291 * install a handler for DC_APPL packets (can be NULL), returning old one. 292 */ 293 DC_Appl_Handler Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler); 294 295 /* 296 * prototype for asynchronous processing callback 297 */ 298 typedef void (*Adp_Async_Callback)(const DeviceDescr *device, 299 const struct timeval *const time_now); 300 301 /* 302 * add an asynchronous processing callback to the list 303 * TRUE == okay, FALSE == no more async processing slots 304 */ 305 bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc ); 306 307 /* 308 * delay for a given period (in microseconds) 309 */ 310 void Adp_delay(unsigned int period); 311 312 #endif /* ndef angsd_hostchan_h */ 313 314 /* EOF hostchan.h */ 315