gdb/rdi-share/channels.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  *   Project: ANGEL
  16  *
  17  *     Title: User interface to the channels layer
  18  */
  19
  20 #ifndef angel_channels_h
  21 #define angel_channels_h
  22
  23 /*
  24  * This provides the public interface to the channels layer read and write
  25  * routines, and buffer management routines.
  26  */
  27
  28 /* Nested header files, if required */
  29
  30 #include "devices.h"
  31 #include "chandefs.h"
  32 #include "adperr.h"
  33
  34 /* General purpose constants, macros, enums, typedefs */
  35
  36 /* use the default device */
  37 #define CH_DEFAULT_DEV ((DeviceID)-1)
  38
  39 /* return codes */
  40 typedef enum ChanError {
  41   CE_OKAY,                      /* no error */
  42   CE_ABANDONED,                 /* abandoned due to device switch */
  43   CE_DEV_ERROR,                 /* unexpected error from device driver */
  44   CE_BUSY,                      /* channel in use */
  45   CE_BUFF_ERROR,                /* unable to get buffer */
  46   CE_PRIVATE                    /* start of internal error codes */
  47 } ChanError;
  48
  49
  50 /* Publically-accessible globals */
  51
  52 /*
  53  * The following two globals are only valid after angel_InitialiseChannels()
  54  * has been called.
  55  */
  56
  57 /* the default size of a channel buffer, for global use */
  58 extern unsigned Angel_ChanBuffSize;
  59
  60 /* the size of a long buffer, for global use */
  61 extern unsigned Angel_ChanLongSize;
  62
  63 #ifdef TARGET
  64 AdpErrs send_resend_msg(DeviceID devid);
  65 #endif
  66
  67 /*
  68  * Function: angel_InitialiseChannels
  69  *  Purpose: initialise the channels layer
  70  *
  71  *   Params:
  72  *              Input: -
  73  *             Output: -
  74  *             In/Out: -
  75  *
  76  *            Returns: -
  77  *
  78  *      Reads globals: -
  79  *   Modifies globals: -
  80  *
  81  * Other side effects: -
  82  */
  83
  84 void angel_InitialiseChannels( void );
  85
  86 /*
  87  * Function: adp_init_seq
  88  *  Purpose: initialise sequence numbers and free anyt leftover buffers
  89  *
  90  *   Params:
  91  *              Input: -
  92  *             Output: -
  93  *             In/Out: -
  94  *
  95  *            Returns: - adp_ok if things went ok else an error code
  96  *
  97  *      Reads globals: -
  98  *   Modifies globals: -
  99  *
 100  * Other side effects: -
 101  */
 102
 103 AdpErrs adp_init_seq(void);
 104
 105 /*
 106  * Function: angel_ChannelAllocBuffer
 107  *  Purpose: allocate a buffer that is at least req_size bytes long
 108  *
 109  *   Params:
 110  *              Input: req_size        the minimum size required
 111  *             Output: -
 112  *             In/Out: -
 113  *
 114  *            Returns: pointer to allocated buffer, or
 115  *                     NULL if unable to allocate suitable buffer
 116  *
 117  *      Reads globals: -
 118  *   Modifies globals: -
 119  *
 120  * Other side effects: -
 121  */
 122
 123 p_Buffer angel_ChannelAllocBuffer(unsigned req_size);
 124
 125
 126 /*
 127  * Function: angel_ChannelReleaseBuffer
 128  *  Purpose: release a buffer back to the free pool
 129  *
 130  *   Params:
 131  *              Input: buffer   the buffer to release
 132  *             Output: -
 133  *             In/Out: -
 134  *
 135  *            Returns: -
 136  *
 137  *      Reads globals: -
 138  *   Modifies globals: -
 139  *
 140  * Other side effects: -
 141  */
 142
 143 void angel_ChannelReleaseBuffer(p_Buffer buffer);
 144
 145
 146 /*
 147  * Function: angel_ChannelSend
 148  *  Purpose: blocking send of a packet via a channel
 149  *
 150  *   Params:
 151  *              Input: devid         Device to use, or CH_DEFAULT_DEV
 152  *                     chanid        Channel to use for tx
 153  *                     buffer        Pointer to data to send
 154  *                     len           Length of data to send
 155  *             Output: -
 156  *             In/Out: -
 157  *
 158  *            Returns: CE_OKAY       Transmission completed
 159  *                     CE_BAD_CHAN   Channel id invalid
 160  *                     CE_ABANDONED  Tx abandoned due to device switch
 161  *
 162  *      Reads globals: -
 163  *   Modifies globals: -
 164  *
 165  * Other side effects: -
 166  */
 167
 168 ChanError angel_ChannelSend(DeviceID devid, ChannelID chanid,
 169                             const p_Buffer buffer, unsigned len);
 170
 171
 172 /*
 173  * Function: angel_ChannelSendAsync
 174  *  Purpose: asynchronous send of a packet via a channel
 175  *
 176  *   Params:
 177  *              Input: devid         Device to use, or CH_DEFAULT_DEV
 178  *                     chanid        Channel to use for tx
 179  *                     buffer        Pointer to data to send
 180  *                     len           Length of data to send
 181  *                     callback      Function to call on completion
 182  *                     callback_data Pointer to pass to callback
 183  *             Output: -
 184  *             In/Out: -
 185  *
 186  *            Returns: CE_OKAY       Transmission underway
 187  *                     CE_BAD_CHAN   Channel id invalid
 188  *                     CE_ABANDONED  Tx abandoned due to device switch
 189  *
 190  *      Reads globals: -
 191  *   Modifies globals: -
 192  *
 193  * Other side effects: -
 194  *
 195  * register an asynchronous send on the given channel
 196  * (blocks until send can be commenced)
 197  */
 198
 199 typedef void (*ChanTx_CB_Fn)(ChannelID  chanid,         /* which channel  */
 200                              void      *callback_data); /* as supplied... */
 201
 202
 203 ChanError angel_ChannelSendAsync(          DeviceID      devid,
 204                                            ChannelID     chanid,
 205                                      const p_Buffer      buffer,
 206                                            unsigned      len,
 207                                            ChanTx_CB_Fn  callback,
 208                                            void         *callback_data);
 209
 210
 211 /*
 212  * Function: angel_ChannelRead
 213  *  Purpose: blocking read of a packet from a channel
 214  *
 215  *   Params:
 216  *              Input: devid         Device to use, or CH_DEFAULT_DEV
 217  *                     chanid        Channel to use for rx
 218  *             Output: buffer        The buffer, supplied and filled
 219  *                     len           How many bytes there are in the buffer
 220  *             In/Out: -
 221  *
 222  *            Returns: CE_OKAY       Reception successful
 223  *                     CE_BAD_CHAN   Channel id invalid
 224  *                     CE_ABANDONED  Tx abandoned due to device switch
 225  *
 226  *      Reads globals: -
 227  *   Modifies globals: -
 228  *
 229  * Other side effects: -
 230  *
 231  * Note that in the present version, if an asynchronous read has been
 232  * registered, a blocking read will be refused with CE_BUSY.
 233  */
 234 ChanError angel_ChannelRead(DeviceID      devid,
 235                             ChannelID     chanid,
 236                             p_Buffer     *buffer,
 237                             unsigned     *len);
 238
 239
 240 /*
 241  * Function: angel_ChannelReadAsync
 242  *  Purpose: asynchronous read of a packet via a channel
 243  *
 244  *   Params:
 245  *              Input: devid         Device to use, or CH_DEFAULT_DEV
 246  *                     chanid        Channel to wait on
 247  *                     callback      Function to call on completion, or NULL
 248  *                     callback_data Pointer to pass to callback
 249  *             Output: -
 250  *             In/Out: -
 251  *
 252  *            Returns: CE_OKAY       Read request registered
 253  *                     CE_BAD_CHAN   Channel id invalid
 254  *                     CE_BUSY       Someone else is using the channel
 255  *                                   (in a single threaded world)
 256  *
 257  *      Reads globals: -
 258  *   Modifies globals: -
 259  *
 260  * Other side effects: -
 261  *
 262  * Register an asynchronous read on the given channel.  There can only be one
 263  * async. reader per channel, and blocking reads are not permitted whilst
 264  * an async. reader is registered.
 265  *
 266  * Reader can unregister by specifying NULL as the callback function.
 267  */
 268
 269 typedef void (*ChanRx_CB_Fn)(DeviceID   devID,   /* ID of receiving device  */
 270                              ChannelID  chanID,  /* ID of receiving channel */
 271                              p_Buffer   buff,    /* pointer to buffer       */
 272                              unsigned   len,     /* length of data          */
 273                              void      *cb_data  /* callback data           */
 274                              );
 275
 276 ChanError angel_ChannelReadAsync(DeviceID      devid,
 277                                  ChannelID     chanid,
 278                                  ChanRx_CB_Fn  callback,
 279                                  void         *callback_data);
 280
 281
 282 /*
 283  * Function: angel_ChannelReadAll
 284  *  Purpose: register an asynchronous read across all devices
 285  *
 286  *   Params:
 287  *              Input: chanid        Channel to look for (usually HBOOT)
 288  *                     callback      Function to call on completion
 289  *                     callback_data Pointer to pass to callback
 290  *             Output: -
 291  *             In/Out: -
 292  *
 293  *            Returns: CE_OKAY       Read request registered
 294  *                     CE_BAD_CHAN   Channel id invalid
 295  *                     CE_BUSY       Someone else is reading all devices
 296  *
 297  *      Reads globals: -
 298  *   Modifies globals: -
 299  *
 300  * Other side effects: -
 301  *
 302  * Register an asynchronous read across all devices.  This is a 'fallback',
 303  * which will be superseded (temporarily) by a registered reader or blocking
 304  * read on a specific device.
 305  */
 306
 307 ChanError angel_ChannelReadAll(         ChannelID     chanid,
 308                                         ChanRx_CB_Fn  callback,
 309                                         void         *callback_data);
 310
 311
 312
 313 /*
 314  * Function: angel_ChannelSendThenRead
 315  *  Purpose: blocking write to followed by read from a channel
 316  *
 317  *   Params:
 318  *              Input: devid         Device to use, or CH_DEFAULT_DEV
 319  *                     chanid        Channel to use for rx
 320  *             In/Out: buffer        On entry:  the packet to be sent
 321  *                                   On return: the packet received
 322  *                     len           On entry:  length of packet to be sent
 323  *                                   On return: length of packet rx'd
 324  *             In/Out: -
 325  *
 326  *            Returns: CE_OKAY       Tx and Reception successful
 327  *                     CE_BAD_CHAN   Channel id invalid
 328  *                     CE_ABANDONED  Tx abandoned due to device switch
 329  *
 330  *      Reads globals: -
 331  *   Modifies globals: -
 332  *
 333  * Other side effects: -
 334  *
 335  * Note that in the present version, if an asynchronous read has been
 336  * registered, this will be refused with CE_BUSY.
 337  */
 338 ChanError angel_ChannelSendThenRead(DeviceID      devid,
 339                                     ChannelID     chanid,
 340                                     p_Buffer     *buffer,
 341                                     unsigned     *len);
 342
 343
 344 /*
 345  * Function: angel_ChannelSelectDevice
 346  *  Purpose: select the device to be used for all channel comms
 347  *
 348  *   Params:
 349  *              Input: device        ID of device to use as the default
 350  *             Output: -
 351  *             In/Out: -
 352  *
 353  *            Returns: CE_OKAY       Default device selected
 354  *                     CE_BAD_DEV    Invalid device ID
 355  *
 356  *      Reads globals: -
 357  *   Modifies globals: -
 358  *
 359  * Other side effects: Any channel operations in progress are
 360  *                     abandoned.
 361  *
 362  * select the device for all channels comms
 363  */
 364
 365 ChanError angel_ChannelSelectDevice(DeviceID device);
 366
 367
 368 /*
 369  * Function: angel_ChannelReadActiveDevice
 370  *  Purpose: reads the device id of the currently active device
 371  *
 372  *   Params:
 373  *              Input: device        address of a DeviceID variable
 374  *             Output: *device       ID of device currently being used
 375  *             In/Out: -
 376  *
 377  *            Returns: CE_OKAY       Default device selected
 378  */
 379
 380 ChanError angel_ChannelReadActiveDevice(DeviceID *device);
 381
 382 #endif /* ndef angel_channels_h */
 383
 384 /* EOF channels.h */