target/linux/s3c24xx/files-2.6.30/drivers/ar6000/include/hif.h

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