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: 1.2 $ 12 * $Date: 1998/01/08 11:11:55 $ 13 * 14 * 15 * Project: ANGEL 16 * 17 * Title: Public client interface to devices 18 */ 19 20#ifndef angel_devclnt_h 21#define angel_devclnt_h 22 23/* 24 * This header exports the public interface to Angel-compliant device 25 * drivers. 26 * 27 * They are intended to be used solely by Angel, not by the User 28 * Application. See devappl.h for the User Application interface to 29 * the device drivers. 30 */ 31 32#include "devices.h" 33 34/* General purpose constants, macros, enums, typedefs */ 35 36/* 37 * possible channels at device level 38 * 39 * XXX 40 * 41 * these are used as array indices, so be specific about their values 42 */ 43typedef enum DevChanID { 44 DC_DBUG = 0, /* reliable debug packets 45 * containing SDBG, CLIB,UDBG, etc.) */ 46 DC_APPL = 1, /* application packets */ 47 DC_NUM_CHANNELS 48} DevChanID; 49 50/* Publically-accessible globals */ 51/* none */ 52 53/* Public functions */ 54 55/* 56 * Function: angel_DeviceWrite 57 * Purpose: The main entry point for asynchronous writes to a device. 58 * 59 * Params: 60 * Input: devID index of the device to write to 61 * buff data to write 62 * length how much data to write 63 * callback callback here when write finished 64 * or error 65 * cb_data data to be passed to callback 66 * chanID device channel to use 67 * Output: - 68 * In/Out: - 69 * 70 * Returns: DE_OKAY write request is underway 71 * DE_NO_DEV no such device 72 * DE_BAD_DEV device does not support angel writes 73 * DE_BAD_CHAN no such device channel 74 * DE_BUSY device busy with another write 75 * DE_INVAL silly length 76 * 77 * Reads globals: - 78 * Modifies globals: - 79 * 80 * Other side effects: - 81 * 82 * Commence asynchronous transmission of a buffer on a device. The 83 * callback will occur when the write completes or if there is an 84 * error. 85 * 86 * This must be called for each packet to be sent. 87 */ 88 89DevError angel_DeviceWrite(DeviceID devID, p_Buffer buff, 90 unsigned length, DevWrite_CB_Fn callback, 91 void *cb_data, DevChanID chanID); 92 93 94/* 95 * Function: angel_DeviceRegisterRead 96 * Purpose: The main entry point for asynchronous reads from a device. 97 * 98 * Params: 99 * Input: devID index of the device to read from 100 * callback callback here when read finished 101 * or error 102 * cb_data data to be passed to callback 103 * get_buff callback to be used to acquire buffer 104 * for incoming packets 105 * getb_data data to be passed to get_buff 106 * chanID device channel to use 107 * Output: - 108 * In/Out: - 109 * 110 * Returns: DE_OKAY read request is underway 111 * DE_NO_DEV no such device 112 * DE_BAD_DEV device does not support angel reads 113 * DE_BAD_CHAN no such device channel 114 * DE_BUSY device busy with another read 115 * DE_INVAL silly length 116 * 117 * Reads globals: - 118 * Modifies globals: - 119 * 120 * Other side effects: - 121 * 122 * Register asynchronous packet read from a device. The callback will 123 * occur when the read completes or if there is an error. 124 * 125 * This is persistent: the read remains registered for all incoming 126 * packets on the device channel. 127 */ 128 129DevError angel_DeviceRegisterRead(DeviceID devID, 130 DevRead_CB_Fn callback, void *cb_data, 131 DevGetBuff_Fn get_buff, void *getb_data, 132 DevChanID chanID); 133 134 135/* 136 * Function: angel_DeviceControl 137 * Purpose: Call a control function for a device 138 * 139 * Params: 140 * Input: devID index of the device to control to 141 * op operation to perform 142 * arg parameter depending on op 143 * 144 * Returns: DE_OKAY control request is underway 145 * DE_NO_DEV no such device 146 * DE_BAD_OP device does not support operation 147 * 148 * Reads globals: - 149 * Modifies globals: - 150 * 151 * Other side effects: - 152 * 153 * Have a device perform a control operation. Extra parameters vary 154 * according to the operation requested. 155 */ 156 157DevError angel_DeviceControl(DeviceID devID, DeviceControl op, void *arg); 158 159 160/* 161 * Function: angel_ReceiveMode 162 * Purpose: enable or disable reception across all devices 163 * 164 * Params: 165 * Input: mode choose enable or disable 166 * 167 * Pass the mode parameter to the receive_mode control method of each device 168 */ 169 170void angel_ReceiveMode(DevRecvMode mode); 171 172 173/* 174 * Function: angel_ResetDevices 175 * Purpose: reset all devices 176 * 177 * Params: none 178 * 179 * Call the reset control method for each device 180 */ 181 182void angel_ResetDevices(void); 183 184 185/* 186 * Function: angel_InitialiseDevices 187 * Purpose: initialise the device driver layer 188 * 189 * Params: none 190 * 191 * Set up the device driver layer and call the init method for each device 192 */ 193 194void angel_InitialiseDevices(void); 195 196 197/* 198 * Function: angel_IsAngelDevice 199 * Purpose: Find out if a device supports Angel packets 200 * 201 * Params: 202 * Input: devID index of the device to control to 203 * 204 * Returns: TRUE supports Angel packets 205 * FALSE raw device 206 * 207 * Reads globals: - 208 * Modifies globals: - 209 * 210 * Other side effects: - 211 */ 212 213bool angel_IsAngelDevice(DeviceID devID); 214 215 216#if !defined(MINIMAL_ANGEL) || MINIMAL_ANGEL == 0 217 218/* 219 * Function: angel_ApplDeviceHandler 220 * Purpose: The entry point for User Application Device Driver requests 221 * in a full functiionality version of Angel. 222 * It will never be called directly by the User Application, 223 * but gets called indirectly, via the SWI handler. 224 * 225 * Params: 226 * Input: swi_r0 Argument to SWI indicating that 227 * angel_ApplDeviceHandler was to be called. This 228 * will not be used in this function, but is needed 229 * by the SWI handler. 230 * arg_blk pointer to block of arguments 231 * arg_blk[0] is one of 232 * angel_SWIreason_ApplDevice_{Read,Write,Yield} 233 * which indicates which angel_Device* fn is to 234 * be called. arg_blk[1] - arg_blk[n] are the 235 * arguments to the corresponding 236 * angel_ApplDevice* function. 237 * Output: - 238 * In/Out: - 239 * 240 * Returns: whatever the specified angel_Device* function 241 * returns. 242 * 243 * Reads globals: - 244 * Modifies globals: - 245 * 246 * Other side effects: - 247 * 248 * This has the side effects of angel_Device{Read,Write,Yield} 249 * depending upon which is operation is specified as described above. 250 */ 251 252DevError angel_ApplDeviceHandler( 253 unsigned swi_r0, unsigned *arg_blk 254); 255 256#endif /* ndef MINIMAL_ANGEL */ 257 258#endif /* ndef angel_devclnt_h */ 259 260/* EOF devclnt.h */ 261