sys/dev/ath/ath_hal/ah_desc.h

   1 /*
   2  * Copyright (c) 2002-2008 Sam Leffler, Errno Consulting
   3  * Copyright (c) 2002-2008 Atheros Communications, Inc.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16  *
  17  * $FreeBSD$
  18  */
  19
  20 #ifndef _DEV_ATH_DESC_H
  21 #define _DEV_ATH_DESC_H
  22
  23 #include "opt_ah.h"             /* NB: required for AH_SUPPORT_AR5416 */
  24
  25 /*
  26  * Transmit descriptor status.  This structure is filled
  27  * in only after the tx descriptor process method finds a
  28  * ``done'' descriptor; at which point it returns something
  29  * other than HAL_EINPROGRESS.
  30  *
  31  * Note that ts_antenna may not be valid for all h/w.  It
  32  * should be used only if non-zero.
  33  */
  34 struct ath_tx_status {
  35         uint16_t        ts_seqnum;      /* h/w assigned sequence number */
  36         uint16_t        ts_tstamp;      /* h/w assigned timestamp */
  37         uint8_t         ts_status;      /* frame status, 0 => xmit ok */
  38         uint8_t         ts_rate;        /* h/w transmit rate index */
  39         int8_t          ts_rssi;        /* tx ack RSSI */
  40         uint8_t         ts_shortretry;  /* # short retries */
  41         uint8_t         ts_longretry;   /* # long retries */
  42         uint8_t         ts_virtcol;     /* virtual collision count */
  43         uint8_t         ts_antenna;     /* antenna information */
  44         uint8_t         ts_finaltsi;    /* final transmit series index */
  45 #ifdef AH_SUPPORT_AR5416
  46                                         /* 802.11n status */
  47         uint8_t         ts_flags;       /* misc flags */
  48         int8_t          ts_rssi_ctl[3]; /* tx ack RSSI [ctl, chain 0-2] */
  49         int8_t          ts_rssi_ext[3]; /* tx ack RSSI [ext, chain 0-2] */
  50 /* #define ts_rssi ts_rssi_combined */
  51         uint32_t        ts_ba_low;      /* blockack bitmap low */
  52         uint32_t        ts_ba_high;     /* blockack bitmap high */
  53         uint32_t        ts_evm0;        /* evm bytes */
  54         uint32_t        ts_evm1;
  55         uint32_t        ts_evm2;
  56 #endif /* AH_SUPPORT_AR5416 */
  57 };
  58
  59 /* bits found in ts_status */
  60 #define HAL_TXERR_XRETRY        0x01    /* excessive retries */
  61 #define HAL_TXERR_FILT          0x02    /* blocked by tx filtering */
  62 #define HAL_TXERR_FIFO          0x04    /* fifo underrun */
  63 #define HAL_TXERR_XTXOP         0x08    /* txop exceeded */
  64 #define HAL_TXERR_TIMER_EXPIRED 0x10    /* Tx timer expired */
  65
  66 /* bits found in ts_flags */
  67 #define HAL_TX_BA               0x01    /* Block Ack seen */
  68 #define HAL_TX_AGGR             0x02    /* Aggregate */
  69 #define HAL_TX_DESC_CFG_ERR     0x10    /* Error in 20/40 desc config */
  70 #define HAL_TX_DATA_UNDERRUN    0x20    /* Tx buffer underrun */
  71 #define HAL_TX_DELIM_UNDERRUN   0x40    /* Tx delimiter underrun */
  72
  73 /*
  74  * Receive descriptor status.  This structure is filled
  75  * in only after the rx descriptor process method finds a
  76  * ``done'' descriptor; at which point it returns something
  77  * other than HAL_EINPROGRESS.
  78  *
  79  * If rx_status is zero, then the frame was received ok;
  80  * otherwise the error information is indicated and rs_phyerr
  81  * contains a phy error code if HAL_RXERR_PHY is set.  In general
  82  * the frame contents is undefined when an error occurred thought
  83  * for some errors (e.g. a decryption error), it may be meaningful.
  84  *
  85  * Note that the receive timestamp is expanded using the TSF to
  86  * at least 15 bits (regardless of what the h/w provides directly).
  87  * Newer hardware supports a full 32-bits; use HAL_CAP_32TSTAMP to
  88  * find out if the hardware is capable.
  89  *
  90  * rx_rssi is in units of dbm above the noise floor.  This value
  91  * is measured during the preamble and PLCP; i.e. with the initial
  92  * 4us of detection.  The noise floor is typically a consistent
  93  * -96dBm absolute power in a 20MHz channel.
  94  */
  95 struct ath_rx_status {
  96         uint16_t        rs_datalen;     /* rx frame length */
  97         uint8_t         rs_status;      /* rx status, 0 => recv ok */
  98         uint8_t         rs_phyerr;      /* phy error code */
  99         int8_t          rs_rssi;        /* rx frame RSSI (combined for 11n) */
 100         uint8_t         rs_keyix;       /* key cache index */
 101         uint8_t         rs_rate;        /* h/w receive rate index */
 102         uint8_t         rs_more;        /* more descriptors follow */
 103         uint32_t        rs_tstamp;      /* h/w assigned timestamp */
 104         uint32_t        rs_antenna;     /* antenna information */
 105 #ifdef AH_SUPPORT_AR5416
 106                                         /* 802.11n status */
 107         int8_t          rs_rssi_ctl[3]; /* rx frame RSSI [ctl, chain 0-2] */
 108         int8_t          rs_rssi_ext[3]; /* rx frame RSSI [ext, chain 0-2] */
 109         uint8_t         rs_isaggr;      /* is part of the aggregate */
 110         uint8_t         rs_moreaggr;    /* more frames in aggr to follow */
 111         uint8_t         rs_num_delims;  /* number of delims in aggr */
 112         uint8_t         rs_flags;       /* misc flags */
 113         uint32_t        rs_evm0;        /* evm bytes */
 114         uint32_t        rs_evm1;
 115         uint32_t        rs_evm2;
 116         uint32_t        rs_evm3;        /* needed for ar9300 and later */
 117         uint32_t        rs_evm4;        /* needed for ar9300 and later */
 118 #endif /* AH_SUPPORT_AR5416 */
 119 };
 120
 121 /* bits found in rs_status */
 122 #define HAL_RXERR_CRC           0x01    /* CRC error on frame */
 123 #define HAL_RXERR_PHY           0x02    /* PHY error, rs_phyerr is valid */
 124 #define HAL_RXERR_FIFO          0x04    /* fifo overrun */
 125 #define HAL_RXERR_DECRYPT       0x08    /* non-Michael decrypt error */
 126 #define HAL_RXERR_MIC           0x10    /* Michael MIC decrypt error */
 127
 128 /* bits found in rs_flags */
 129 #define HAL_RX_MORE             0x01    /* more descriptors follow */
 130 #define HAL_RX_MORE_AGGR        0x02    /* more frames in aggr */
 131 #define HAL_RX_GI               0x04    /* full gi */
 132 #define HAL_RX_2040             0x08    /* 40 Mhz */
 133 #define HAL_RX_DELIM_CRC_PRE    0x10    /* crc error in delimiter pre */
 134 #define HAL_RX_DELIM_CRC_POST   0x20    /* crc error in delim after */
 135 #define HAL_RX_DECRYPT_BUSY     0x40    /* decrypt was too slow */
 136 #define HAL_RX_HI_RX_CHAIN      0x80    /* SM power save: hi Rx chain control */
 137
 138 enum {
 139         HAL_PHYERR_UNDERRUN             = 0,    /* Transmit underrun */
 140         HAL_PHYERR_TIMING               = 1,    /* Timing error */
 141         HAL_PHYERR_PARITY               = 2,    /* Illegal parity */
 142         HAL_PHYERR_RATE                 = 3,    /* Illegal rate */
 143         HAL_PHYERR_LENGTH               = 4,    /* Illegal length */
 144         HAL_PHYERR_RADAR                = 5,    /* Radar detect */
 145         HAL_PHYERR_SERVICE              = 6,    /* Illegal service */
 146         HAL_PHYERR_TOR                  = 7,    /* Transmit override receive */
 147         /* NB: these are specific to the 5212 and later */
 148         HAL_PHYERR_OFDM_TIMING          = 17,   /* */
 149         HAL_PHYERR_OFDM_SIGNAL_PARITY   = 18,   /* */
 150         HAL_PHYERR_OFDM_RATE_ILLEGAL    = 19,   /* */
 151         HAL_PHYERR_OFDM_LENGTH_ILLEGAL  = 20,   /* */
 152         HAL_PHYERR_OFDM_POWER_DROP      = 21,   /* */
 153         HAL_PHYERR_OFDM_SERVICE         = 22,   /* */
 154         HAL_PHYERR_OFDM_RESTART         = 23,   /* */
 155         HAL_PHYERR_FALSE_RADAR_EXT      = 24,   /* */
 156         HAL_PHYERR_CCK_TIMING           = 25,   /* */
 157         HAL_PHYERR_CCK_HEADER_CRC       = 26,   /* */
 158         HAL_PHYERR_CCK_RATE_ILLEGAL     = 27,   /* */
 159         HAL_PHYERR_CCK_SERVICE          = 30,   /* */
 160         HAL_PHYERR_CCK_RESTART          = 31,   /* */
 161         HAL_PHYERR_CCK_LENGTH_ILLEGAL   = 32,   /* */
 162         HAL_PHYERR_CCK_POWER_DROP       = 33,   /* */
 163         /* AR5416 and later */
 164         HAL_PHYERR_HT_CRC_ERROR         = 34,   /* */
 165         HAL_PHYERR_HT_LENGTH_ILLEGAL    = 35,   /* */
 166         HAL_PHYERR_HT_RATE_ILLEGAL      = 36,   /* */
 167 };
 168
 169 /* value found in rs_keyix to mark invalid entries */
 170 #define HAL_RXKEYIX_INVALID     ((uint8_t) -1)
 171 /* value used to specify no encryption key for xmit */
 172 #define HAL_TXKEYIX_INVALID     ((u_int) -1)
 173
 174 /* XXX rs_antenna definitions */
 175
 176 /*
 177  * Definitions for the software frame/packet descriptors used by
 178  * the Atheros HAL.  This definition obscures hardware-specific
 179  * details from the driver.  Drivers are expected to fillin the
 180  * portions of a descriptor that are not opaque then use HAL calls
 181  * to complete the work.  Status for completed frames is returned
 182  * in a device-independent format.
 183  */
 184 #ifdef AH_SUPPORT_AR5416
 185 #define HAL_DESC_HW_SIZE        20
 186 #else
 187 #define HAL_DESC_HW_SIZE        4
 188 #endif /* AH_SUPPORT_AR5416 */
 189
 190 struct ath_desc {
 191         /*
 192          * The following definitions are passed directly
 193          * the hardware and managed by the HAL.  Drivers
 194          * should not touch those elements marked opaque.
 195          */
 196         uint32_t        ds_link;        /* phys address of next descriptor */
 197         uint32_t        ds_data;        /* phys address of data buffer */
 198         uint32_t        ds_ctl0;        /* opaque DMA control 0 */
 199         uint32_t        ds_ctl1;        /* opaque DMA control 1 */
 200         uint32_t        ds_hw[HAL_DESC_HW_SIZE];        /* opaque h/w region */
 201 };
 202
 203 struct ath_desc_status {
 204         union {
 205                 struct ath_tx_status tx;/* xmit status */
 206                 struct ath_rx_status rx;/* recv status */
 207         } ds_us;
 208 };
 209
 210 #define ds_txstat       ds_us.tx
 211 #define ds_rxstat       ds_us.rx
 212
 213 /* flags passed to tx descriptor setup methods */
 214 #define HAL_TXDESC_CLRDMASK     0x0001  /* clear destination filter mask */
 215 #define HAL_TXDESC_NOACK        0x0002  /* don't wait for ACK */
 216 #define HAL_TXDESC_RTSENA       0x0004  /* enable RTS */
 217 #define HAL_TXDESC_CTSENA       0x0008  /* enable CTS */
 218 #define HAL_TXDESC_INTREQ       0x0010  /* enable per-descriptor interrupt */
 219 #define HAL_TXDESC_VEOL         0x0020  /* mark virtual EOL */
 220 /* NB: this only affects frame, not any RTS/CTS */
 221 #define HAL_TXDESC_DURENA       0x0040  /* enable h/w write of duration field */
 222 #define HAL_TXDESC_EXT_ONLY     0x0080  /* send on ext channel only (11n) */
 223 #define HAL_TXDESC_EXT_AND_CTL  0x0100  /* send on ext + ctl channels (11n) */
 224 #define HAL_TXDESC_VMF          0x0200  /* virtual more frag */
 225
 226 /* flags passed to rx descriptor setup methods */
 227 #define HAL_RXDESC_INTREQ       0x0020  /* enable per-descriptor interrupt */
 228 #endif /* _DEV_ATH_DESC_H */