1 /**************************************************************************** 2 **+-----------------------------------------------------------------------+** 3 **| |** 4 **| Copyright(c) 1998 - 2008 Texas Instruments. All rights reserved. |** 5 **| All rights reserved. |** 6 **| |** 7 **| Redistribution and use in source and binary forms, with or without |** 8 **| modification, are permitted provided that the following conditions |** 9 **| are met: |** 10 **| |** 11 **| * Redistributions of source code must retain the above copyright |** 12 **| notice, this list of conditions and the following disclaimer. |** 13 **| * Redistributions in binary form must reproduce the above copyright |** 14 **| notice, this list of conditions and the following disclaimer in |** 15 **| the documentation and/or other materials provided with the |** 16 **| distribution. |** 17 **| * Neither the name Texas Instruments nor the names of its |** 18 **| contributors may be used to endorse or promote products derived |** 19 **| from this software without specific prior written permission. |** 20 **| |** 21 **| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |** 22 **| "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |** 23 **| LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |** 24 **| A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |** 25 **| OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |** 26 **| SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |** 27 **| LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |** 28 **| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |** 29 **| THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |** 30 **| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |** 31 **| OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |** 32 **| |** 33 **+-----------------------------------------------------------------------+** 34 ****************************************************************************/ 35 36 #ifndef PUBLIC_DESCRIPTORS_H 37 #define PUBLIC_DESCRIPTORS_H 38 39 40 #include "public_types.h" 41 42 43 /****************************************************************************** 44 45 TX PATH 46 47 The Tx path uses a double buffer and a TxControl structure, each located at a 48 fixed address in the device's memory. On startup, the host retrieves the pointers 49 to these addresses. A double buffer allows for continuous data flow towards the 50 device. The host keeps track of which buffer is available and alternates between 51 these two buffers on a per packet basis. 52 The size of each of the two buffers is large enough to hold the longest 802.3 53 packet - maximum size Ethernet packet + header + descriptor. 54 TX complete indication will be received a-synchronously in a TX done cyclic buffer 55 (txDoneRing) which is composed of 16 Tx Result Descriptors structures 56 and is used in a cyclic manner. refer to TxResultDescriptor_t structure. 57 58 The TX (HOST) procedure is as follows: 59 1. Read the Tx path status (DataOutCount in TxPathStatus). 60 2. goto 1, if not possible. 61 i.e. if DataInCount - DataOutCount >= HwBuffer size (2 for double buffer)). 62 3. Copy the packet (preceded by TxDescriptor), if possible. 63 i.e. if DataInCount - DataOutCount < HwBuffer size (2 for double buffer). 64 4. increment DataInCount. 65 5. Inform the firmware by generating a firmware internal interrupt. 66 6. FW will increment DataOutCount after it reads the buffer. 67 68 The TX Complete procedure: 69 1. To get a TX complete indication the host enables the Tx Complete flag in the 70 TX Descriptor Structure (Refer to the Ctrl field in TxDescriptor_t). 71 2. For each packet with a Tx Complete field set, the firmware adds the transmit 72 results to the cyclic buffer (txDoneRing) and sets both done1and done2 to 1 to 73 indicate driver ownership. 74 3. The firmware sends a Tx Complete interrupt to the host to trigger the host to 75 process the new data. Note: interrupt will be send per packet if TX complete 76 indication was requested in TxDescriptor_t (see 1.) or per crossing Aggregation 77 threashold. 78 4. After receiving the Tx Complete interrupt, the host reads the TxDescriptorDone 79 information in a cyclic manner and clears both done1 and done2 fields. 80 81 ******************************************************************************/ 82 83 /****************************************************************************** 84 85 TxDescriptor_t 86 87 the structure of the transmit Tx descriptor passed from the host, ahead of 88 the transmitted packet. 89 90 ******************************************************************************/ 91 92 93 /* Because we are using a bit map, It is safer to enable the exact bits instead of field assignment */ 94 /* It is IMPORTENT to check that the bit defenitions are alligned to the bit map struct */ 95 #define TX_COMPLETE_REQUIRED_BIT 0x80 96 97 /* TX attribute fields (txAttr of TxDesriptor structure)*/ 98 /* ******************************************************/ 99 typedef struct 100 { 101 unsigned ratePolicy :3; /* Rate Policy (class) index */ 102 unsigned ackPolicy :1; /* When set, no ack policy is expected*/ 103 unsigned pktType :2; /* packet type: */ 104 /* 0 - 802.11, */ 105 /* 1 - 802.3,*/ 106 /* 2 - IP, */ 107 /* 3 - raw codec */ 108 unsigned qosFrame :1; /* If set, this is QoS-Null or QoS-Data*/ 109 unsigned txCmpltRequired :1; /* If set, the FW should trigger the TxComplete*/ 110 /* interrupt for this packet*/ 111 unsigned xferPadding :1; /* If set, there is 2 bytes padding before */ 112 /* packet header*/ 113 unsigned reserved :7; /* padding*/ 114 } TxDescCtrl_t; 115 116 117 #ifdef HOST_COMPILE 118 typedef uint16 TxAttr_t; 119 #else 120 typedef TxDescCtrl_t TxAttr_t; 121 #endif 122 123 /**************************************/ 124 /* Double Buffer Descriptor Fields */ 125 /**************************************/ 126 127 128 129 #define DoubleBufferDesc uint16 length; /* Length of payload, including headers. */ \ 130 TxdRateSet_t rate; /* A bit mask that specifies the initial rate to be */ \ 131 /* used. Possible values are: */ \ 132 /* 0x0001 - 1Mbits */ \ 133 /* 0x0002 - 2Mbits */ \ 134 /* 0x0004 - 5.5Mbits */ \ 135 /* 0x0008 - 6Mbits */ \ 136 /* 0x0010 - 9Mbits */ \ 137 /* 0x0020 - 11Mbits */ \ 138 /* 0x0040 - 12Mbits */ \ 139 /* 0x0080 - 18Mbits */ \ 140 /* 0x0100 - 22Mbits */ \ 141 /* 0x0200 - 24Mbits */ \ 142 /* 0x0400 - 36Mbits */ \ 143 /* 0x0800 - 48Mbits */ \ 144 /* 0x1000 - 54Mbits */ \ 145 uint32 expiryTime; /* Time (in us) the packet can stay in the device */ \ 146 /* before the packet expires. */ \ 147 uint8 xmitQueue; /* The index of the Tx queue used for this packet. */ \ 148 uint8 descID; /* Identifier of the packet. This ID is used by the */ \ 149 /* host for identifying the Tx Result of packet. */ \ 150 TxAttr_t txAttr; /* Bitwise fields - see TxDescCtrl_tdefinition above */ \ 151 uint16 fragThreshold; /* The FW should cut the packet to fragments by */ \ 152 /* this size. */ \ 153 uint8 numMemBlks; /* Number of HW queue blocks to allocate for this */ \ 154 /* packet. */ \ 155 uint8 reserved; /* for padding to 32 bits boundry. */ \ 156 157 158 159 160 typedef struct 161 { 162 DoubleBufferDesc 163 }DbTescriptor; 164 165 /****************************************************************************** 166 167 TxResultDescriptor_t 168 169 the structure of the Tx result retrieved from FW upon TX completion. 170 171 ******************************************************************************/ 172 173 typedef enum 174 { 175 TX_SUCCESS = 0, 176 TX_DMA_ERROR = BIT_7, 177 TX_DISABLED = BIT_6, 178 TX_RETRY_EXCEEDED = BIT_5, 179 TX_TIMEOUT = BIT_4, 180 TX_KEY_NOT_FOUND = BIT_3, 181 TX_ENCRYPT_FAIL = BIT_2, 182 TX_UNAVAILABLE_PRIORITY = BIT_1 183 } TxDescStatus_enum; 184 185 #ifdef HOST_COMPILE 186 typedef uint8 TxDescStatus_e; 187 #else 188 typedef TxDescStatus_enum TxDescStatus_e; 189 #endif 190 191 typedef struct 192 { 193 uint8 done1; /* Ownership synchronization between the host and */ 194 /* the firmware. If done1 and done2 are cleared, */ 195 /* owned by the FW (no info ready). */ 196 197 uint8 descID; /* Packet Identifier - same value used in the Tx */ 198 /* descriptor.*/ 199 200 uint16 mediumUsage; /* Total air access duration consumed by this */ 201 /* packet, including all retrys and overheads.*/ 202 203 uint32 mediumDelay; /* Total media delay (from 1st EDCA AIFS counter until TX Complete). */ 204 205 uint32 fwHandlingTime; /* The time passed from host xfer to Tx-complete.*/ 206 207 uint8 lsbSecuritySequenceNumber; /* The LS-byte of the last TKIP sequence number. */ 208 /* Saved per queue for recovery.*/ 209 210 uint8 ackFailures; /* Retry count - The number of transmissions */ 211 /* without successful ACK reception.*/ 212 213 TxdRateSet_t actualRate; /* The rate that succeeded getting ACK - */ 214 /* Valid only if status=TX_SUCCESS.*/ 215 216 uint16 reserved; 217 218 TxDescStatus_e status; /* The status of the transmission, indicating */ 219 /* success or one of several possible reasons for */ 220 /* failure. Refer to TxDescStatus_enum, above.*/ 221 222 uint8 done2; /* Refer to done1.*/ 223 } TxResultDescriptor_t; 224 225 226 227 /****************************************************************************** 228 229 RX PATH 230 231 The Rx path uses a double buffer and an RxControl structure, each located at 232 a fixed address in the device memory. On startup, the host retrieves the 233 pointers to these addresses. A double buffer allows for continuous data flow 234 towards the device. The host keeps track of which buffer is available and 235 alternates between them on a per packet basis. 236 The size of each of the two buffers is large enough to hold the longest 802.3 237 packet. 238 A dedicated control block is used to manage the flow control between the host 239 and the device. The procedure is interrupt driven. 240 241 The RX procedure is as follows: 242 1. The device generates an interrupt each time a new packet is received and 243 the corresponding interrupt is enabled in the host. There are two different 244 interrupt sources, one for each buffer. It is possible that both interrupt 245 sources are set when both buffers in the double buffer are pending with Rx 246 data. 247 2. Depending on flow control conditions, the host reads a packet from the 248 appropriate buffer in the double buffer. 249 3. The host triggers an interrupt in the device (using the HW mechanism of EOT), 250 indicating the address of the buffer which has been read. 251 4. The device services the complete interrupt and prepares the next Rx packet, 252 if available. In addition, the device updates the control block and issues 253 an interrupt to the host. 254 255 ******************************************************************************/ 256 257 /****************************************************************************** 258 259 RxPathStatusReg_t 260 261 The structure of the Rx Path Status register. This status register 262 represents both the status of the double-buffer (xfer protocol) and the 263 number of the pending packet in receive queue. 264 265 ******************************************************************************/ 266 267 #ifdef HOST_COMPILE 268 #define RX_DESC_VALID_FCS 0x0001 269 #define RX_DESC_MATCH_RXADDR1 0x0002 270 #define RX_DESC_MCAST 0x0004 271 #define RX_DESC_STAINTIM 0x0008 272 #define RX_DESC_VIRTUAL_BM 0x0010 273 #define RX_DESC_BCAST 0x0020 274 #define RX_DESC_MATCH_SSID 0x0040 275 #define RX_DESC_MATCH_BSSID 0x0080 276 #define RX_DESC_ENCRYPTION_MASK 0x0300 277 #define RX_DESC_MEASURMENT 0x0400 278 #define RX_DESC_SEQNUM_MASK 0x1800 279 #define RX_DESC_MIC_FAIL 0x2000 280 #define RX_DESC_DECRYPT_FAIL 0x4000 281 typedef uint16 RxFlags_t; 282 #else 283 typedef struct 284 { 285 unsigned validFcs : 1; /* Indicates whether a received frame had a valid FCS*/ 286 287 unsigned matchRxAddr1 : 1; /* Indicates whether a received frame contained a */ 288 /* matching receive address in Address 1.*/ 289 290 unsigned mcast : 1; /* Indicates whether a received frame contains a */ 291 /* unicast/directed or group receive address, bit 40*/ 292 /* of Addr1 (0 = individual, 1 = group).*/ 293 294 unsigned StaInTIM : 1; /* Indicates that the TIM in a Beacon frame contained*/ 295 /* a 1 in the bit position representing this STA */ 296 /* (i.e. the AP contains one or more buffered frame(s)*/ 297 /* for this STA).*/ 298 299 unsigned virtualBM : 1; /* If asserted, the VBM in a Beacon frame contained */ 300 /* more than 1 asserted bit*/ 301 302 unsigned bcast : 1; /* Indicates whether the received frame’s address 1 */ 303 /* is a broadcast address.*/ 304 305 unsigned matchSSID : 1; /* Indicates whether the received frame containing */ 306 /* a matching SSID (either broadcast or specific).*/ 307 308 unsigned matchBSSID : 1; /* Indicates whether the received frame containing */ 309 /* a matching BSSID (either broadcast or specific).*/ 310 311 unsigned encryption : 2; /* This field indicates the encryption type of the */ 312 /* packet: 00 - None, 01 - WEP, 10 - TKIP, 11 - AES*/ 313 314 unsigned measurement : 1; /* Indicates whether the packet was received during */ 315 /* measurement process or not*/ 316 317 unsigned seqnum : 2; /* Sequence number of the current frame*/ 318 319 unsigned micFail : 1; /* MIC Fail indication */ 320 321 unsigned decryptFail : 1; /* DECRYPT Fail indication */ 322 323 unsigned reserved2 : 1; 324 } RxFlags_t; 325 #endif 326 327 /****************************************************************************** 328 329 RxIfDescriptor_t 330 331 the structure of the Rx Descriptor recieved by HOST. 332 333 ******************************************************************************/ 334 335 typedef struct 336 { 337 uint32 timestamp; /* Timestamp in microseconds, */ 338 339 uint16 length; /* Length of payload (including headers)*/ 340 341 RxFlags_t flags; /* See RxFlags_t for details. */ 342 343 uint8 type; /* Protocol type: */ 344 /* 0 - 802.11*/ 345 /* 1 - 802.3*/ 346 /* 2 - IP*/ 347 /* 3 - Raw Codec*/ 348 349 uint8 rate; /* Recevied Rate:*/ 350 /* 0x0A - 1MBPS*/ 351 /* 0x14 - 2MBPS */ 352 /* 0x37 - 5_5MBPS */ 353 /* 0x0B - 6MBPS */ 354 /* 0x0F - 9MBPS */ 355 /* 0x6E - 11MBPS */ 356 /* 0x0A - 12MBPS */ 357 /* 0x0E - 18MBPS */ 358 /* 0xDC - 22MBPS */ 359 /* 0x09 - 24MBPS */ 360 /* 0x0D - 36MBPS */ 361 /* 0x08 - 48MBPS */ 362 /* 0x0C - 54MBPS */ 363 364 uint8 modPre; /* Modulation and Preamble of received packet*/ 365 366 uint8 chanNum; /* The received channel*/ 367 368 uint8 band; /* 0 - 2.4Ghz*/ 369 /* 1 - 5Ghz*/ 370 371 int8 rssi; /* RSSI value in db */ 372 373 uint8 rcpi; /* RCPI value in db */ 374 375 uint8 snr; /* SNR in db*/ 376 377 } RxIfDescriptor_t; 378 379 380 381 #endif /* PUBLIC_DESCRIPTORS_H*/ 382 383 384 385