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 /* 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 */