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