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 */ 40enum AsyncMode 41{ 42 async_block_on_nothing, 43 async_block_on_read, 44 async_block_on_write 45}; 46 47#ifndef __cplusplus 48typedef enum AsyncMode AsyncMode; 49#endif 50 51/* 52 * prototype for channels callback function 53 */ 54typedef 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 */ 64extern 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 */ 77extern 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 91extern Packet *Adp_removeFromQueue(Packet **head); 92 93/* 94 * Set log file and Enable/disable logging of ADP packets to file. 95 */ 96 97void Adp_SetLogfile(const char *filename); 98void 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 */ 132AdpErrs 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 */ 145AdpErrs 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 */ 162AdpErrs 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 191extern 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 */ 222AdpErrs 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 */ 244AdpErrs 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 */ 267AdpErrs 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 */ 283void Adp_AsynchronousProcessing(const AsyncMode mode); 284 285/* 286 * prototype for DC_APPL packet handler 287 */ 288typedef 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 */ 293DC_Appl_Handler Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler); 294 295/* 296 * prototype for asynchronous processing callback 297 */ 298typedef 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 */ 305bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc ); 306 307/* 308 * delay for a given period (in microseconds) 309 */ 310void Adp_delay(unsigned int period); 311 312#endif /* ndef angsd_hostchan_h */ 313 314/* EOF hostchan.h */ 315