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