/* 
 * Copyright (C) 1995 Advanced RISC Machines Limited. All rights reserved.
 * 
 * This software may be freely used, copied, modified, and distributed
 * provided that the above copyright notice is preserved in all copies of the
 * software.
 */

/* -*-C-*-
 *
 * $Revision$
 *     $Date$
 *
 *
 *   Project: ANGEL
 *
 *     Title: Public client interface to devices
 */

#ifndef angel_devclnt_h
#define angel_devclnt_h

/*
 * This header exports the public interface to Angel-compliant device
 * drivers.
 *
 * They are intended to be used solely by Angel, not by the User
 * Application.  See devappl.h for the User Application interface to
 * the device drivers.
 */

#include "devices.h"

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

/*
 * possible channels at device level
 *
 * XXX
 *
 * these are used as array indices, so be specific about their values
 */
typedef enum DevChanID {
  DC_DBUG = 0,                  /* reliable debug packets
                                 * containing SDBG, CLIB,UDBG, etc.) */
  DC_APPL = 1,                  /* application packets */
  DC_NUM_CHANNELS
} DevChanID;

/* Publically-accessible globals */
/* none */

/* Public functions */

/*
 * Function: angel_DeviceWrite
 *  Purpose: The main entry point for asynchronous writes to a device.
 *
 *   Params:
 *              Input: devID     index of the device to write to
 *                     buff      data to write
 *                     length    how much data to write
 *                     callback  callback here when write finished
 *                                or error
 *                     cb_data   data to be passed to callback
 *                     chanID    device channel to use
 *             Output: -
 *             In/Out: -
 *
 *            Returns: DE_OKAY     write request is underway           
 *                     DE_NO_DEV   no such device                      
 *                     DE_BAD_DEV  device does not support angel writes
 *                     DE_BAD_CHAN no such device channel              
 *                     DE_BUSY     device busy with another write      
 *                     DE_INVAL    silly length                        
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Commence asynchronous transmission of a buffer on a device.  The
 * callback will occur when the write completes or if there is an
 * error.
 *
 * This must be called for each packet to be sent.
 */

DevError angel_DeviceWrite(DeviceID devID, p_Buffer buff,
                           unsigned length, DevWrite_CB_Fn callback,
                           void *cb_data, DevChanID chanID);


/*
 * Function: angel_DeviceRegisterRead
 *  Purpose: The main entry point for asynchronous reads from a device.
 *
 *   Params:
 *              Input: devID     index of the device to read from
 *                     callback  callback here when read finished
 *                                or error
 *                     cb_data   data to be passed to callback
 *                     get_buff  callback to be used to acquire buffer
 *                                for incoming packets
 *                     getb_data data to be passed to get_buff
 *                     chanID    device channel to use
 *             Output: -
 *             In/Out: -
 *
 *            Returns: DE_OKAY     read request is underway           
 *                     DE_NO_DEV   no such device                      
 *                     DE_BAD_DEV  device does not support angel reads
 *                     DE_BAD_CHAN no such device channel              
 *                     DE_BUSY     device busy with another read      
 *                     DE_INVAL    silly length                        
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Register asynchronous packet read from a device.  The callback will
 * occur when the read completes or if there is an error.
 *
 * This is persistent: the read remains registered for all incoming
 * packets on the device channel.
 */

DevError angel_DeviceRegisterRead(DeviceID devID,
                                  DevRead_CB_Fn callback, void *cb_data,
                                  DevGetBuff_Fn get_buff, void *getb_data,
                                  DevChanID chanID);


/*
 * Function: angel_DeviceControl
 *  Purpose: Call a control function for a device
 *
 *   Params:
 *              Input: devID     index of the device to control to
 *                     op        operation to perform
 *                     arg       parameter depending on op
 *
 *            Returns: DE_OKAY     control request is underway           
 *                     DE_NO_DEV   no such device                      
 *                     DE_BAD_OP   device does not support operation
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * Have a device perform a control operation.  Extra parameters vary 
 * according to the operation requested.
 */

DevError angel_DeviceControl(DeviceID devID, DeviceControl op, void *arg);


/*
 * Function: angel_ReceiveMode
 *  Purpose: enable or disable reception across all devices
 *
 *   Params:
 *              Input: mode   choose enable or disable
 *
 * Pass the mode parameter to the receive_mode control method of each device
 */

void angel_ReceiveMode(DevRecvMode mode);


/*
 * Function: angel_ResetDevices
 *  Purpose: reset all devices
 *
 *   Params: none
 *
 * Call the reset control method for each device
 */

void angel_ResetDevices(void);


/*
 * Function: angel_InitialiseDevices
 *  Purpose: initialise the device driver layer
 *
 *   Params: none
 *
 * Set up the device driver layer and call the init method for each device
 */

void angel_InitialiseDevices(void);


/*
 * Function: angel_IsAngelDevice
 *  Purpose: Find out if a device supports Angel packets
 *
 *   Params:
 *              Input: devID     index of the device to control to
 *
 *            Returns: TRUE      supports Angel packets
 *                     FALSE     raw device
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 */

bool angel_IsAngelDevice(DeviceID devID);


#if !defined(MINIMAL_ANGEL) || MINIMAL_ANGEL == 0

/*
 * Function: angel_ApplDeviceHandler
 *  Purpose: The entry point for User Application Device Driver requests
 *           in a full functiionality version of Angel.
 *           It will never be called directly by the User Application,
 *           but gets called indirectly, via the SWI handler.
 *
 *  Params:
 *      Input: swi_r0    Argument to SWI indicating that 
 *                       angel_ApplDeviceHandler was to be called.  This
 *                       will not be used in this function, but is needed
 *                       by the SWI handler.
 *             arg_blk   pointer to block of arguments
 *                       arg_blk[0] is one of
 *                       angel_SWIreason_ApplDevice_{Read,Write,Yield}
 *                       which indicates which angel_Device* fn is to
 *                       be called.  arg_blk[1] - arg_blk[n] are the
 *                       arguments to the corresponding
 *                       angel_ApplDevice* function.
 *             Output: -
 *             In/Out: -
 *
 *            Returns:   whatever the specified angel_Device* function
 *                       returns.
 *
 *      Reads globals: -
 *   Modifies globals: -
 *
 * Other side effects: -
 *
 * This has the side effects of angel_Device{Read,Write,Yield}
 * depending upon which is operation is specified as described above.
 */

DevError angel_ApplDeviceHandler(
  unsigned swi_r0, unsigned *arg_blk
);

#endif /* ndef MINIMAL_ANGEL */

#endif /* ndef angel_devclnt_h */

/* EOF devclnt.h */