gdb/rdi-share/hostchan.h

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