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