channels.h

ARM入门的好帮手.包含了从简单到相对较复杂的程序.

/* -*-C-*-
 *
 * $Revision: 1.7.6.3 $
 *   $Author: rivimey $
 *     $Date: 1998/02/11 13:19:07 $
 *
 * Copyright (c) 1996 Advanced RISC Machines Limited.
 * All Rights Reserved.
 *
 *   Project: ANGEL
 *
 *     Title: User interface to the channels layer
 */

#ifndef angel_channels_h
#define angel_channels_h

/*
 * This provides the public interface to the channels layer read and write
 * routines, and buffer management routines.
 */

/* Nested header files, if required */

#include "devices.h"
#include "chandefs.h"
#include "adperr.h"

/* General purpose constants, macros, enums, typedefs */

/* use the default device */
#define CH_DEFAULT_DEV ((DeviceID)-1)

/* return codes */
typedef enum ChanError {
  CE_OKAY,                      /* no error */
  CE_ABANDONED,                 /* abandoned due to device switch */
  CE_DEV_ERROR,                 /* unexpected error from device driver */
  CE_BUSY,                      /* channel in use */
  CE_BUFF_ERROR,                /* unable to get buffer */
  CE_PRIVATE                    /* start of internal error codes */
} ChanError;

/* Publically-accessible globals */

/*
 * The following globals are only valid after angel_InitialiseChannels()
 * has been called.
 */

/* the default size of a channel buffer, for global use */
extern unsigned Angel_ChanBuffSize;

/* the size of a long buffer, for global use */
extern unsigned Angel_ChanLongSize;

/* TRUE if heartbeats should be acked, FALSE otherwise. */
extern unsigned Angel_AckedHeartbeats;

/*
 * Function: angel_InitialiseChannels
 *  Purpose: initialise the channels layer
 *
 *   Params:
 *              Input: -
 *             Output: -
 *             In/Out: -
 *
 *            Returns: -
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

void angel_InitialiseChannels( void );

/*
 * Function: Angel_InitChannels, Angel_ReinitChannels
 *  Purpose: initialise sequence numbers and free anyt leftover buffers. Init
 *           starts from the premise that nothing is kept; reinit just frees
 *           used things (i.e. it is not a total reset). Both reset the sequence
 *           numbers.make
 
 *
 *   Params:
 *              Input: -
 *             Output: -
 *             In/Out: -
 *
 *            Returns: - adp_ok if things went ok else an error code
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

AdpErrs Angel_InitChannels(void);
AdpErrs Angel_ReinitChannels(void);

/*
 * Function: adp_translate_dev_error
 *  Purpose: translate a device error code (e.g. DE_INVAL) into the
 *           equivalent adp error code.
 *
 *   Params:
 *              Input: - dev error
 *             Output: - adp error
 *             In/Out: -
 *
 *            Returns: - 
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

AdpErrs adp_translate_dev_error(DevError dev_err);

/*
 * Function: angel_ChannelAllocBuffer
 *  Purpose: allocate a buffer that is at least req_size bytes long
 *
 *   Params:
 *              Input: req_size        the minimum size required
 *             Output: -
 *             In/Out: -
 *
 *            Returns: pointer to allocated buffer, or
 *                     NULL if unable to allocate suitable buffer
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

p_Buffer angel_ChannelAllocBuffer(unsigned req_size);


/*
 * Function: angel_ChannelReleaseBuffer
 *  Purpose: release a buffer back to the free pool
 *
 *   Params:
 *              Input: buffer   the buffer to release
 *             Output: -
 *             In/Out: -
 *
 *            Returns: -
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

void angel_ChannelReleaseBuffer(p_Buffer buffer);


/*
 * Function: angel_ChannelSend
 *  Purpose: blocking send of a packet via a channel
 *
 *   Params:
 *              Input: devid         Device to use, or CH_DEFAULT_DEV
 *                     chanid        Channel to use for tx 
 *                     buffer        Pointer to data to send
 *                     len           Length of data to send
 *             Output: -
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Transmission completed
 *                     CE_BAD_CHAN   Channel id invalid
 *                     CE_ABANDONED  Tx abandoned due to device switch
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

ChanError angel_ChannelSend(DeviceID devid, ChannelID chanid,
                            const p_Buffer buffer, unsigned len);


/*
 * Function: angel_ChannelSendAsync
 *  Purpose: asynchronous send of a packet via a channel
 *
 *   Params:
 *              Input: devid         Device to use, or CH_DEFAULT_DEV
 *                     chanid        Channel to use for tx 
 *                     buffer        Pointer to data to send
 *                     len           Length of data to send
 *                     callback      Function to call on completion
 *                     callback_data Pointer to pass to callback
 *             Output: -
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Transmission underway
 *                     CE_BAD_CHAN   Channel id invalid
 *                     CE_ABANDONED  Tx abandoned due to device switch
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * register an asynchronous send on the given channel
 * (blocks until send can be commenced)
 */

typedef void (*ChanTx_CB_Fn)(ChannelID  chanid,         /* which channel  */
                             void      *callback_data); /* as supplied... */
                             

ChanError angel_ChannelSendAsync(          DeviceID      devid,
                                           ChannelID     chanid,
                                     const p_Buffer      buffer,
                                           unsigned      len, 
                                           ChanTx_CB_Fn  callback, 
                                           void         *callback_data);


/*
 * Function: angel_ChannelRead
 *  Purpose: blocking read of a packet from a channel
 *
 *   Params:
 *              Input: devid         Device to use, or CH_DEFAULT_DEV
 *                     chanid        Channel to use for rx
 *             Output: buffer        The buffer, supplied and filled
 *                     len           How many bytes there are in the buffer
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Reception successful
 *                     CE_BAD_CHAN   Channel id invalid
 *                     CE_ABANDONED  Tx abandoned due to device switch
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Note that in the present version, if an asynchronous read has been
 * registered, a blocking read will be refused with CE_BUSY.
 */
ChanError angel_ChannelRead(DeviceID      devid,
                            ChannelID     chanid,
                            p_Buffer     *buffer, 
                            unsigned     *len);


/*
 * Function: angel_ChannelReadAsync
 *  Purpose: asynchronous read of a packet via a channel
 *
 *   Params:
 *              Input: devid         Device to use, or CH_DEFAULT_DEV
 *                     chanid        Channel to wait on
 *                     callback      Function to call on completion, or NULL
 *                     callback_data Pointer to pass to callback
 *             Output: -
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Read request registered
 *                     CE_BAD_CHAN   Channel id invalid
 *                     CE_BUSY       Someone else is using the channel
 *                                   (in a single threaded world)
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Register an asynchronous read on the given channel.  There can only be one
 * async. reader per channel, and blocking reads are not permitted whilst
 * an async. reader is registered.
 *
 * Reader can unregister by specifying NULL as the callback function.
 */

typedef void (*ChanRx_CB_Fn)(DeviceID   devID,   /* ID of receiving device  */
                             ChannelID  chanID,  /* ID of receiving channel */
                             p_Buffer   buff,    /* pointer to buffer       */
                             unsigned   len,     /* length of data          */
                             void      *cb_data  /* callback data           */
                             );

ChanError angel_ChannelReadAsync(DeviceID      devid,
                                 ChannelID     chanid,
                                 ChanRx_CB_Fn  callback, 
                                 void         *callback_data);


/*
 * Function: angel_ChannelReadAll
 *  Purpose: register an asynchronous read across all devices
 *
 *   Params:
 *              Input: chanid        Channel to look for (usually HBOOT)
 *                     callback      Function to call on completion
 *                     callback_data Pointer to pass to callback
 *             Output: -
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Read request registered
 *                     CE_BAD_CHAN   Channel id invalid
 *                     CE_BUSY       Someone else is reading all devices
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Register an asynchronous read across all devices.  This is a 'fallback',
 * which will be superseded (temporarily) by a registered reader or blocking 
 * read on a specific device.
 */

ChanError angel_ChannelReadAll(         ChannelID     chanid,
                                        ChanRx_CB_Fn  callback,
                                        void         *callback_data);



/*
 * Function: angel_ChannelSendThenRead
 *  Purpose: blocking write to followed by read from a channel
 *
 *   Params:
 *              Input: devid         Device to use, or CH_DEFAULT_DEV
 *                     chanid        Channel to use for rx
 *             In/Out: buffer        On entry:  the packet to be sent
 *                                   On return: the packet received
 *                     len           On entry:  length of packet to be sent
 *                                   On return: length of packet rx'd
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Tx and Reception successful
 *                     CE_BAD_CHAN   Channel id invalid
 *                     CE_ABANDONED  Tx abandoned due to device switch
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Note that in the present version, if an asynchronous read has been
 * registered, this will be refused with CE_BUSY.
 */
ChanError angel_ChannelSendThenRead(DeviceID      devid,
                                    ChannelID     chanid,
                                    p_Buffer     *buffer, 
                                    unsigned     *len);


/*
 * Function: angel_ChannelSelectDevice
 *  Purpose: select the device to be used for all channel comms
 *
 *   Params:
 *              Input: device        ID of device to use as the default
 *             Output: -
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Default device selected
 *                     CE_BAD_DEV    Invalid device ID
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: Any channel operations in progress are
 *                     abandoned.
 *
 * select the device for all channels comms
 */

ChanError angel_ChannelSelectDevice(DeviceID device);


/*
 * Function: angel_ChannelReadActiveDevice
 *  Purpose: reads the device id of the currently active device
 *
 *   Params:
 *              Input: device        address of a DeviceID variable
 *             Output: *device       ID of device currently being used
 *             In/Out: -
 *
 *            Returns: CE_OKAY       Default device selected
 */

ChanError angel_ChannelReadActiveDevice(DeviceID *device);

/*
 * Function: angel_CanAckHeartbeat
 *  Purpose: To return whether we can or can't acknowledge heartbeat
 *           packets. We set an internal variable TRUE letting us know
 *           that we should do so....
 *
 *   Params:  none.
 *
 *            Returns: - always TRUE
 *
 *      Reads globals: -
 *   Modifies globals: - Angel_AckedHeartbeats; read by code which
 *                       receives hbs to determine what to do.
 *
 * Other side effects: - none
 */

word angel_CanAckHeartbeat(void);

#endif /* ndef angel_channels_h */

/* EOF channels.h */