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  * Set log file and Enable/disable logging of ADP packets to file.
  96  */
  97
  98 void Adp_SetLogfile(const char *filename);
  99 void Adp_SetLogEnable(int logEnableFlag);
 100
 101 /*
 102  *  Function: Adp_OpenDevice
 103  *   Purpose: Open a device to use for channels communication.  This is a
 104  *              very thin veneer to the device drivers: what hostchan.c
 105  *              will do is call DeviceMatch for each device driver until it
 106  *              finds a driver that will accept name and arg, then call
 107  *              DeviceOpen for that device.
 108  *
 109  *  Pre-conditions: No previous open is still active
 110  *
 111  *    Params:
 112  *       Input: name    Identifies which device to open.  This can either be
 113  *                      a host specific identifier (e.g. "/dev/ttya",
 114  *                      "COM1:"), or a number which is used to refer to
 115  *                      `standard' interfaces, so "1" would be the first host
 116  *                      interface, "2" the second, and so on.
 117  *
 118  *              arg     Driver specific arguments.  For example, some serial
 119  *                      drivers accept speed and control arguments such as
 120  *                      "9600" or "19200/NO_BREAK".  These arguments are
 121  *                      completely free-form: it is the individual drivers
 122  *                      which do the necessary interpretation.
 123  *
 124  *              heartbeat_on  Incicates if the heartbeat is configured to be
 125  *                      used or not, true if it is, false otherwise
 126  *
 127  *   Returns:
 128  *          OK: adp_ok
 129  *       Error: adp_device_not_known,
 130  *              adp_device_open_failed
 131  *              adp_device_already_open
 132  */
 133 AdpErrs Adp_OpenDevice(const char *name, const char *arg,
 134                        unsigned int heartbeat_on);
 135
 136 /*
 137  *  Function: Adp_CloseDevice
 138  *   Purpose: Close the device used for channels communication.
 139  *
 140  *    Params: None
 141  *
 142  *   Returns:
 143  *          OK: adp_ok
 144  *       Error: adp_device_not_open
 145  */
 146 AdpErrs Adp_CloseDevice(void);
 147
 148 /*
 149  *  Function: Adp_Ioctl
 150  *   Purpose: Perform miscellaneous control operations on
 151  *              the device used for channels communication.
 152  *              This is a minimal veneer to DevSW_Ioctl.
 153  *
 154  *    Params:
 155  *       Input: opcode  Reason code indicating the operation to perform.
 156  *      In/Out: args    Pointer to opcode-sensitive arguments/result space.
 157  *
 158  *
 159  *   Returns:
 160  *          OK: adp_ok
 161  *       Error: adp_device_not_open, adp_failed
 162  */
 163 AdpErrs Adp_Ioctl(int opcode, void *args);
 164
 165 /*
 166  *  Function: Adp_ChannelRegisterRead
 167  *   Purpose: Register a callback function for received packets on a given
 168  *              channel
 169  *
 170  *    Params:
 171  *       Input: chan    The channel the callback function is for.
 172  *
 173  *              cbfunc  The callback function.  If NULL, then the current
 174  *                      callback is removed.
 175  *
 176  *              cbstate State pointer to pass into the callback function
 177  *
 178  *   Returns:
 179  *          OK: adp_ok
 180  *       Error: adp_device_not_open
 181  *              adp_bad_channel_id
 182  *
 183  * Post-conditions: The callback function is responsible for freeing the
 184  *                      packet that is passed to it, when that packet is
 185  *                      no longer needed.
 186  */
 187 #ifdef __cplusplus
 188     extern "C" {
 189 #endif
 190
 191
 192 extern AdpErrs Adp_ChannelRegisterRead(const ChannelID chan,
 193                                const ChannelCallback cbfunc,
 194                                 void *cbstate);
 195
 196 #ifdef __cplusplus
 197     }
 198 #endif
 199 /*
 200  *  Function: Adp_ChannelRead
 201  *   Purpose: Wait until a packet has been read for a given channel, and
 202  *              then return it.  Callbacks for other channels are still
 203  *              active while this read is blocking.
 204  *
 205  *  Pre-conditions: No callback has been already been registered for
 206  *                      the channel.
 207  *
 208  *    Params:
 209  *       Input: chan    The channel to read.
 210  *
 211  *      Output: packet  The received packet.
 212  *
 213  *   Returns:
 214  *          OK: adp_ok
 215  *       Error: adp_device_not_open
 216  *              adp_bad_channel_id
 217  *              adp_callback_already_registered
 218  *
 219  * Post-conditions: The calling function is responsible for freeing the
 220  *                      received packet, when that packet is no longer
 221  *                      needed.
 222  */
 223 AdpErrs Adp_ChannelRead(const ChannelID chan, Packet **packet);
 224
 225 /*
 226  *  Function: Adp_ChannelWrite
 227  *   Purpose: Write a packet to the given channel
 228  *
 229  *  Pre-conditions: Channel must have been previously opened.
 230  *
 231  *    Params:
 232  *       Input: chan    The channel to write.
 233  *
 234  *              packet  The packet to write.
 235  *
 236  *   Returns:
 237  *          OK: adp_ok
 238  *       Error: adp_device_not_open
 239  *              adp_bad_channel_id
 240  *
 241  * Post-conditions: The packet being written becomes the "property" of
 242  *                      Adp_ChannelWrite, which is responsible for freeing
 243  *                      the packet when it is no longer needed.
 244  */
 245 AdpErrs Adp_ChannelWrite(const ChannelID chan, Packet *packet);
 246
 247 /*
 248  *  Function: Adp_ChannelWriteAsync
 249  *   Purpose: Write a packet to the given channel, but don't wait
 250  *            for the write to complete before returning.
 251  *
 252  *  Pre-conditions: Channel must have been previously opened.
 253  *
 254  *    Params:
 255  *       Input: chan    The channel to write.
 256  *
 257  *              packet  The packet to write.
 258  *
 259  *   Returns:
 260  *          OK: adp_ok
 261  *       Error: adp_device_not_open
 262  *              adp_bad_channel_id
 263  *
 264  * Post-conditions: The packet being written becomes the "property" of
 265  *                      Adp_ChannelWrite, which is responsible for freeing
 266  *                      the packet when it is no longer needed.
 267  */
 268 AdpErrs Adp_ChannelWriteAsync(const ChannelID chan, Packet *packet);
 269
 270 /*
 271  *  Function: Adp_AsynchronousProcessing
 272  *   Purpose: This routine should be called from persistent any idle loop
 273  *              to give the data I/O routines a chance to poll for packet
 274  *              activity.  Depending upon the requested mode, this routine
 275  *              may, or may not, block.
 276  *
 277  *    Params:
 278  *       Input: mode    Specifies whether to block until a complete packet
 279  *                      has been read, all pending writes have completed,
 280  *                      or not to block at all.
 281  *
 282  *   Returns: Nothing.
 283  */
 284 void Adp_AsynchronousProcessing(const AsyncMode mode);
 285
 286 /*
 287  * prototype for DC_APPL packet handler
 288  */
 289 typedef void (*DC_Appl_Handler)(const DeviceDescr *device, Packet *packet);
 290
 291 /*
 292  * install a handler for DC_APPL packets (can be NULL), returning old one.
 293  */
 294 DC_Appl_Handler Adp_Install_DC_Appl_Handler(const DC_Appl_Handler handler);
 295
 296 /*
 297  * prototype for asynchronous processing callback
 298  */
 299 typedef void (*Adp_Async_Callback)(const DeviceDescr *device,
 300                                    const struct timeval *const time_now);
 301
 302 /*
 303  * add an asynchronous processing callback to the list
 304  * TRUE == okay, FALSE == no more async processing slots
 305  */
 306 bool Adp_Install_Async_Callback( const Adp_Async_Callback callback_proc );
 307
 308 /*
 309  * delay for a given period (in microseconds)
 310  */
 311 void Adp_delay(unsigned int period);
 312
 313 #endif /* ndef angsd_hostchan_h */
 314
 315 /* EOF hostchan.h */