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