| 1 | /* |
| 2 | * Copyright (c) 2004-2007 Atheros Communications Inc. |
| 3 | * All rights reserved. |
| 4 | * |
| 5 | * |
| 6 | * This program is free software; you can redistribute it and/or modify |
| 7 | * it under the terms of the GNU General Public License version 2 as |
| 8 | * published by the Free Software Foundation; |
| 9 | * |
| 10 | * Software distributed under the License is distributed on an "AS |
| 11 | * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or |
| 12 | * implied. See the License for the specific language governing |
| 13 | * rights and limitations under the License. |
| 14 | * |
| 15 | * |
| 16 | * |
| 17 | * HIF specific declarations and prototypes |
| 18 | */ |
| 19 | |
| 20 | #ifndef _HIF_H_ |
| 21 | #define _HIF_H_ |
| 22 | |
| 23 | #ifdef __cplusplus |
| 24 | extern "C" { |
| 25 | #endif /* __cplusplus */ |
| 26 | |
| 27 | /* Header files */ |
| 28 | #include "a_config.h" |
| 29 | #include "athdefs.h" |
| 30 | #include "a_types.h" |
| 31 | #include "a_osapi.h" |
| 32 | |
| 33 | typedef struct htc_callbacks HTC_CALLBACKS; |
| 34 | typedef struct hif_device HIF_DEVICE; |
| 35 | |
| 36 | /* |
| 37 | * direction - Direction of transfer (HIF_READ/HIF_WRITE). |
| 38 | */ |
| 39 | #define HIF_READ 0x00000001 |
| 40 | #define HIF_WRITE 0x00000002 |
| 41 | #define HIF_DIR_MASK (HIF_READ | HIF_WRITE) |
| 42 | |
| 43 | /* |
| 44 | * type - An interface may support different kind of read/write commands. |
| 45 | * The command type is divided into a basic and an extended command |
| 46 | * and can be specified using HIF_BASIC_IO/HIF_EXTENDED_IO. |
| 47 | */ |
| 48 | #define HIF_BASIC_IO 0x00000004 |
| 49 | #define HIF_EXTENDED_IO 0x00000008 |
| 50 | #define HIF_TYPE_MASK (HIF_BASIC_IO | HIF_EXTENDED_IO) |
| 51 | |
| 52 | /* |
| 53 | * emode - This indicates the whether the command is to be executed in a |
| 54 | * blocking or non-blocking fashion (HIF_SYNCHRONOUS/ |
| 55 | * HIF_ASYNCHRONOUS). The read/write data paths in HTC have been |
| 56 | * implemented using the asynchronous mode allowing the the bus |
| 57 | * driver to indicate the completion of operation through the |
| 58 | * registered callback routine. The requirement primarily comes |
| 59 | * from the contexts these operations get called from (a driver's |
| 60 | * transmit context or the ISR context in case of receive). |
| 61 | * Support for both of these modes is essential. |
| 62 | */ |
| 63 | #define HIF_SYNCHRONOUS 0x00000010 |
| 64 | #define HIF_ASYNCHRONOUS 0x00000020 |
| 65 | #define HIF_EMODE_MASK (HIF_SYNCHRONOUS | HIF_ASYNCHRONOUS) |
| 66 | |
| 67 | /* |
| 68 | * dmode - An interface may support different kinds of commands based on |
| 69 | * the tradeoff between the amount of data it can carry and the |
| 70 | * setup time. Byte and Block modes are supported (HIF_BYTE_BASIS/ |
| 71 | * HIF_BLOCK_BASIS). In case of latter, the data is rounded off |
| 72 | * to the nearest block size by padding. The size of the block is |
| 73 | * configurable at compile time using the HIF_BLOCK_SIZE and is |
| 74 | * negotiated with the target during initialization after the |
| 75 | * dragon interrupts are enabled. |
| 76 | */ |
| 77 | #define HIF_BYTE_BASIS 0x00000040 |
| 78 | #define HIF_BLOCK_BASIS 0x00000080 |
| 79 | #define HIF_DMODE_MASK (HIF_BYTE_BASIS | HIF_BLOCK_BASIS) |
| 80 | |
| 81 | /* |
| 82 | * amode - This indicates if the address has to be incremented on dragon |
| 83 | * after every read/write operation (HIF?FIXED_ADDRESS/ |
| 84 | * HIF_INCREMENTAL_ADDRESS). |
| 85 | */ |
| 86 | #define HIF_FIXED_ADDRESS 0x00000100 |
| 87 | #define HIF_INCREMENTAL_ADDRESS 0x00000200 |
| 88 | #define HIF_AMODE_MASK (HIF_FIXED_ADDRESS | HIF_INCREMENTAL_ADDRESS) |
| 89 | |
| 90 | #define HIF_WR_ASYNC_BYTE_FIX \ |
| 91 | (HIF_WRITE | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_FIXED_ADDRESS) |
| 92 | #define HIF_WR_ASYNC_BYTE_INC \ |
| 93 | (HIF_WRITE | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 94 | #define HIF_WR_ASYNC_BLOCK_INC \ |
| 95 | (HIF_WRITE | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BLOCK_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 96 | #define HIF_WR_SYNC_BYTE_FIX \ |
| 97 | (HIF_WRITE | HIF_SYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_FIXED_ADDRESS) |
| 98 | #define HIF_WR_SYNC_BYTE_INC \ |
| 99 | (HIF_WRITE | HIF_SYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 100 | #define HIF_WR_SYNC_BLOCK_INC \ |
| 101 | (HIF_WRITE | HIF_SYNCHRONOUS | HIF_EXTENDED_IO | HIF_BLOCK_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 102 | #define HIF_RD_SYNC_BYTE_INC \ |
| 103 | (HIF_READ | HIF_SYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 104 | #define HIF_RD_SYNC_BYTE_FIX \ |
| 105 | (HIF_READ | HIF_SYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_FIXED_ADDRESS) |
| 106 | #define HIF_RD_ASYNC_BYTE_FIX \ |
| 107 | (HIF_READ | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_FIXED_ADDRESS) |
| 108 | #define HIF_RD_ASYNC_BLOCK_FIX \ |
| 109 | (HIF_READ | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BLOCK_BASIS | HIF_FIXED_ADDRESS) |
| 110 | #define HIF_RD_ASYNC_BYTE_INC \ |
| 111 | (HIF_READ | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BYTE_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 112 | #define HIF_RD_ASYNC_BLOCK_INC \ |
| 113 | (HIF_READ | HIF_ASYNCHRONOUS | HIF_EXTENDED_IO | HIF_BLOCK_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 114 | #define HIF_RD_SYNC_BLOCK_INC \ |
| 115 | (HIF_READ | HIF_SYNCHRONOUS | HIF_EXTENDED_IO | HIF_BLOCK_BASIS | HIF_INCREMENTAL_ADDRESS) |
| 116 | |
| 117 | |
| 118 | typedef enum { |
| 119 | HIF_DEVICE_POWER_STATE = 0, |
| 120 | HIF_DEVICE_GET_MBOX_BLOCK_SIZE, |
| 121 | HIF_DEVICE_GET_MBOX_ADDR, |
| 122 | HIF_DEVICE_GET_PENDING_EVENTS_FUNC, |
| 123 | HIF_DEVICE_GET_IRQ_PROC_MODE, |
| 124 | HIF_DEVICE_GET_RECV_EVENT_MASK_UNMASK_FUNC, |
| 125 | } HIF_DEVICE_CONFIG_OPCODE; |
| 126 | |
| 127 | /* |
| 128 | * HIF CONFIGURE definitions: |
| 129 | * |
| 130 | * HIF_DEVICE_GET_MBOX_BLOCK_SIZE |
| 131 | * input : none |
| 132 | * output : array of 4 A_UINT32s |
| 133 | * notes: block size is returned for each mailbox (4) |
| 134 | * |
| 135 | * HIF_DEVICE_GET_MBOX_ADDR |
| 136 | * input : none |
| 137 | * output : array of 4 A_UINT32 |
| 138 | * notes: address is returned for each mailbox (4) in the array |
| 139 | * |
| 140 | * HIF_DEVICE_GET_PENDING_EVENTS_FUNC |
| 141 | * input : none |
| 142 | * output: HIF_PENDING_EVENTS_FUNC function pointer |
| 143 | * notes: this is optional for the HIF layer, if the request is |
| 144 | * not handled then it indicates that the upper layer can use |
| 145 | * the standard device methods to get pending events (IRQs, mailbox messages etc..) |
| 146 | * otherwise it can call the function pointer to check pending events. |
| 147 | * |
| 148 | * HIF_DEVICE_GET_IRQ_PROC_MODE |
| 149 | * input : none |
| 150 | * output : HIF_DEVICE_IRQ_PROCESSING_MODE (interrupt processing mode) |
| 151 | * note: the hif layer interfaces with the underlying OS-specific bus driver. The HIF |
| 152 | * layer can report whether IRQ processing is requires synchronous behavior or |
| 153 | * can be processed using asynchronous bus requests (typically faster). |
| 154 | * |
| 155 | * HIF_DEVICE_GET_RECV_EVENT_MASK_UNMASK_FUNC |
| 156 | * input : |
| 157 | * output : HIF_MASK_UNMASK_RECV_EVENT function pointer |
| 158 | * notes: this is optional for the HIF layer. The HIF layer may require a special mechanism |
| 159 | * to mask receive message events. The upper layer can call this pointer when it needs |
| 160 | * to mask/unmask receive events (in case it runs out of buffers). |
| 161 | * |
| 162 | * |
| 163 | */ |
| 164 | |
| 165 | typedef enum { |
| 166 | HIF_DEVICE_IRQ_SYNC_ONLY, /* for HIF implementations that require the DSR to process all |
| 167 | interrupts before returning */ |
| 168 | HIF_DEVICE_IRQ_ASYNC_SYNC, /* for HIF implementations that allow DSR to process interrupts |
| 169 | using ASYNC I/O (that is HIFAckInterrupt can be called at a |
| 170 | later time */ |
| 171 | } HIF_DEVICE_IRQ_PROCESSING_MODE; |
| 172 | |
| 173 | #define HIF_MAX_DEVICES 1 |
| 174 | |
| 175 | struct htc_callbacks { |
| 176 | A_UCHAR *name; |
| 177 | A_UINT32 id; |
| 178 | A_STATUS (* deviceInsertedHandler)(void *hif_handle); |
| 179 | A_STATUS (* deviceRemovedHandler)(void *htc_handle, A_STATUS status); |
| 180 | A_STATUS (* deviceSuspendHandler)(void *htc_handle); |
| 181 | A_STATUS (* deviceResumeHandler)(void *htc_handle); |
| 182 | A_STATUS (* deviceWakeupHandler)(void *htc_handle); |
| 183 | A_STATUS (* rwCompletionHandler)(void *context, A_STATUS status); |
| 184 | A_STATUS (* dsrHandler)(void *htc_handle); |
| 185 | }; |
| 186 | |
| 187 | |
| 188 | #define HIF_OTHER_EVENTS (1 << 0) /* other interrupts (non-Recv) are pending, host |
| 189 | needs to read the register table to figure out what */ |
| 190 | #define HIF_RECV_MSG_AVAIL (1 << 1) /* pending recv packet */ |
| 191 | |
| 192 | typedef struct _HIF_PENDING_EVENTS_INFO { |
| 193 | A_UINT32 Events; |
| 194 | A_UINT32 LookAhead; |
| 195 | } HIF_PENDING_EVENTS_INFO; |
| 196 | |
| 197 | /* function to get pending events , some HIF modules use special mechanisms |
| 198 | * to detect packet available and other interrupts */ |
| 199 | typedef A_STATUS ( *HIF_PENDING_EVENTS_FUNC)(HIF_DEVICE *device, |
| 200 | HIF_PENDING_EVENTS_INFO *pEvents, |
| 201 | void *AsyncContext); |
| 202 | |
| 203 | #define HIF_MASK_RECV TRUE |
| 204 | #define HIF_UNMASK_RECV FALSE |
| 205 | /* function to mask recv events */ |
| 206 | typedef A_STATUS ( *HIF_MASK_UNMASK_RECV_EVENT)(HIF_DEVICE *device, |
| 207 | A_BOOL Mask, |
| 208 | void *AsyncContext); |
| 209 | |
| 210 | |
| 211 | /* |
| 212 | * This API is used by the HTC layer to initialize the HIF layer and to |
| 213 | * register different callback routines. Support for following events has |
| 214 | * been captured - DSR, Read/Write completion, Device insertion/removal, |
| 215 | * Device suspension/resumption/wakeup. In addition to this, the API is |
| 216 | * also used to register the name and the revision of the chip. The latter |
| 217 | * can be used to verify the revision of the chip read from the device |
| 218 | * before reporting it to HTC. |
| 219 | */ |
| 220 | int HIFInit(HTC_CALLBACKS *callbacks); |
| 221 | |
| 222 | /* |
| 223 | * This API is used to provide the read/write interface over the specific bus |
| 224 | * interface. |
| 225 | * address - Starting address in the dragon's address space. For mailbox |
| 226 | * writes, it refers to the start of the mbox boundary. It should |
| 227 | * be ensured that the last byte falls on the mailbox's EOM. For |
| 228 | * mailbox reads, it refers to the end of the mbox boundary. |
| 229 | * buffer - Pointer to the buffer containg the data to be transmitted or |
| 230 | * received. |
| 231 | * length - Amount of data to be transmitted or received. |
| 232 | * request - Characterizes the attributes of the command. |
| 233 | */ |
| 234 | A_STATUS |
| 235 | HIFReadWrite(HIF_DEVICE *device, |
| 236 | A_UINT32 address, |
| 237 | A_UCHAR *buffer, |
| 238 | A_UINT32 length, |
| 239 | A_UINT32 request, |
| 240 | void *context); |
| 241 | |
| 242 | /* |
| 243 | * This can be initiated from the unload driver context ie when the HTCShutdown |
| 244 | * routine is called. |
| 245 | */ |
| 246 | void HIFShutDownDevice(HIF_DEVICE *device); |
| 247 | |
| 248 | /* |
| 249 | * This should translate to an acknowledgment to the bus driver indicating that |
| 250 | * the previous interrupt request has been serviced and the all the relevant |
| 251 | * sources have been cleared. HTC is ready to process more interrupts. |
| 252 | * This should prevent the bus driver from raising an interrupt unless the |
| 253 | * previous one has been serviced and acknowledged using the previous API. |
| 254 | */ |
| 255 | void HIFAckInterrupt(HIF_DEVICE *device); |
| 256 | |
| 257 | void HIFMaskInterrupt(HIF_DEVICE *device); |
| 258 | |
| 259 | void HIFUnMaskInterrupt(HIF_DEVICE *device); |
| 260 | |
| 261 | /* |
| 262 | * This set of functions are to be used by the bus driver to notify |
| 263 | * the HIF module about various events. |
| 264 | * These are not implemented if the bus driver provides an alternative |
| 265 | * way for this notification though callbacks for instance. |
| 266 | */ |
| 267 | int HIFInsertEventNotify(void); |
| 268 | |
| 269 | int HIFRemoveEventNotify(void); |
| 270 | |
| 271 | int HIFIRQEventNotify(void); |
| 272 | |
| 273 | int HIFRWCompleteEventNotify(void); |
| 274 | |
| 275 | /* |
| 276 | * This function associates a opaque handle with the HIF layer |
| 277 | * to be used in communication with upper layer i.e. HTC. |
| 278 | * This would normaly be a pointer to htc_target data structure. |
| 279 | */ |
| 280 | void HIFSetHandle(void *hif_handle, void *handle); |
| 281 | |
| 282 | A_STATUS |
| 283 | HIFConfigureDevice(HIF_DEVICE *device, HIF_DEVICE_CONFIG_OPCODE opcode, |
| 284 | void *config, A_UINT32 configLen); |
| 285 | |
| 286 | |
| 287 | struct device; |
| 288 | struct device* |
| 289 | HIFGetOSDevice(HIF_DEVICE *device); |
| 290 | |
| 291 | |
| 292 | #ifdef __cplusplus |
| 293 | } |
| 294 | #endif |
| 295 | |
| 296 | #endif /* _HIF_H_ */ |
| 297 | |
