d924941f20f0b5ed6cc6f6540ca423d8695618b2
[people/andreif/gpxe.git] / src / include / gpxe / net80211.h
1 #ifndef _GPXE_NET80211_H
2 #define _GPXE_NET80211_H
3
4 #include <gpxe/process.h>
5 #include <gpxe/ieee80211.h>
6 #include <gpxe/iobuf.h>
7 #include <gpxe/netdevice.h>
8 #include <gpxe/rc80211.h>
9
10 /** @file
11  *
12  * The gPXE 802.11 MAC layer.
13  */
14
15 /*
16  * Major things NOT YET supported:
17  * - any type of security
18  * - 802.11n
19  *
20  * Major things that probably will NEVER be supported, barring a
21  * compelling use case and/or corporate sponsorship:
22  * - QoS
23  * - 802.1X authentication ("WPA Enterprise")
24  * - Contention-free periods
25  * - "ad-hoc" networks (IBSS), monitor mode, host AP mode
26  * - hidden networks on the 5GHz band due to regulatory issues
27  * - spectrum management on the 5GHz band (TPC and DFS), as required
28  *   in some non-US regulatory domains
29  * - Clause 14 PHYs (Frequency-Hopping Spread Spectrum on 2.4GHz)
30  *   and Clause 16 PHYs (infrared) - I'm not aware of any real-world
31  *   use of these.
32  */
33
34 FILE_LICENCE ( GPL2_OR_LATER );
35
36 /* All 802.11 devices are handled using a generic "802.11 device"
37    net_device, with a link in its `priv' field to a net80211_device
38    which we use to handle 802.11-specific details. */
39
40
41 /** @defgroup net80211_band RF bands on which an 802.11 device can transmit */
42 /** @{ */
43
44 /** The 2.4 GHz ISM band, unlicensed in most countries */
45 #define NET80211_BAND_2GHZ      0
46 /** The band from 4.9 GHz to 5.7 GHz, which tends to be more restricted */
47 #define NET80211_BAND_5GHZ      1
48 /** Number of RF bands */
49 #define NET80211_NR_BANDS       2
50
51 /** Bitmask for the 2GHz band */
52 #define NET80211_BAND_BIT_2GHZ  (1 << 0)
53 /** Bitmask for the 5GHz band */
54 #define NET80211_BAND_BIT_5GHZ  (1 << 1)
55
56 /** @} */
57
58
59 /** @defgroup net80211_mode 802.11 operation modes supported by hardware */
60 /** @{ */
61
62 /** 802.11a: 54 Mbps operation using OFDM signaling on the 5GHz band */
63 #define NET80211_MODE_A         (1 << 0)
64
65 /** 802.11b: 1-11 Mbps operation using DSSS/CCK signaling on the 2.4GHz band */
66 #define NET80211_MODE_B         (1 << 1)
67
68 /** 802.11g: 54 Mbps operation using ERP/OFDM signaling on the 2.4GHz band */
69 #define NET80211_MODE_G         (1 << 2)
70
71 /** 802.11n: High-rate operation using MIMO technology on 2.4GHz or 5GHz */
72 #define NET80211_MODE_N         (1 << 3)
73
74 /** @} */
75
76
77 /** @defgroup net80211_cfg Constants for the net80211 config callback */
78 /** @{ */
79
80 /** Channel choice (@c dev->channel) or regulatory parameters have changed */
81 #define NET80211_CFG_CHANNEL    (1 << 0)
82
83 /** Requested transmission rate (@c dev->rate) has changed */
84 #define NET80211_CFG_RATE       (1 << 1)
85
86 /** Association has been established with a new BSS (@c dev->bssid) */
87 #define NET80211_CFG_ASSOC      (1 << 2)
88
89 /** Low-level link parameters (short preamble, protection, etc) have changed */
90 #define NET80211_CFG_PHY_PARAMS (1 << 3)
91
92 /** @} */
93
94
95 /** An 802.11 security handshaking protocol */
96 enum net80211_security_proto {
97         /** No security handshaking
98          *
99          * This might be used with an open network or with WEP, as
100          * WEP does not have a cryptographic handshaking phase.
101          */
102         NET80211_SECPROT_NONE = 0,
103
104         /** Pre-shared key handshaking
105          *
106          * This implements the "WPA Personal" handshake. 802.1X
107          * authentication is not performed -- the user supplies a
108          * pre-shared key directly -- but there is a 4-way handshake
109          * between client and AP to verify that both have the same key
110          * without revealing the contents of that key.
111          */
112         NET80211_SECPROT_PSK = 1,
113
114         /** Full EAP 802.1X handshaking
115          *
116          * This implements the "WPA Enterprise" handshake, connecting
117          * to an 802.1X authentication server to provide credentials
118          * and receive a pairwise master key (PMK), which is then used
119          * in the same 4-way handshake as the PSK method.
120          */
121         NET80211_SECPROT_EAP = 2,
122 };
123
124
125 /** An 802.11 data encryption algorithm */
126 enum net80211_crypto_alg {
127         /** No security, an "Open" network */
128         NET80211_CRYPT_NONE = 0,
129
130         /** Network protected with WEP (awful RC4-based system)
131          *
132          * WEP uses a naive application of RC4, with a monotonically
133          * increasing initialization vector that is prepended to the
134          * key to initialize the RC4 keystream. It is highly insecure
135          * and can be completely cracked or subverted using automated,
136          * robust, freely available tools (aircrack-ng) in minutes.
137          *
138          * 40-bit and 104-bit WEP are differentiated only by the size
139          * of the key. They may be advertised as 64-bit and 128-bit,
140          * counting the non-random IV as part of the key bits.
141          */
142         NET80211_CRYPT_WEP = 1,
143
144         /** Network protected with TKIP (better RC4-based system)
145          *
146          * Usually known by its trade name of WPA (Wi-Fi Protected
147          * Access), TKIP implements a message integrity code (MIC)
148          * called Michael, a timestamp counter for replay prevention,
149          * and a key mixing function that together remove almost all
150          * the security problems with WEP. Countermeasures are
151          * implemented to prevent high data-rate attacks.
152          *
153          * There exists one known attack on TKIP, that allows one to
154          * send between 7 and 15 arbitrary short data packets on a
155          * QoS-enabled network given about an hour of data
156          * gathering. Since gPXE does not support QoS for 802.11
157          * networks, this is not a threat to us. The only other method
158          * is a brute-force passphrase attack.
159          */
160         NET80211_CRYPT_TKIP = 2,
161
162         /** Network protected with CCMP (AES-based system)
163          *
164          * Often called WPA2 in commerce, or RSNA (Robust Security
165          * Network Architecture) in the 802.11 standard, CCMP is
166          * highly secure and does not have any known attack vectors.
167          * Since it is based on a block cipher, the statistical
168          * correlation and "chopchop" attacks used with great success
169          * against WEP and minor success against TKIP fail.
170          */
171         NET80211_CRYPT_CCMP = 3,
172 };
173
174
175 /** @defgroup net80211_state Bits for the 802.11 association state field */
176 /** @{ */
177
178 /** An error code indicating the failure mode, or 0 if successful */
179 #define NET80211_STATUS_MASK    0x7F
180
181 /** Whether the error code provided is a "reason" code, not a "status" code */
182 #define NET80211_IS_REASON      0x80
183
184 /** Whether we have found the network we will be associating with */
185 #define NET80211_PROBED         (1 << 8)
186
187 /** Whether we have successfully authenticated with the network
188  *
189  * This usually has nothing to do with actual security; it is a
190  * holdover from older 802.11 implementation ideas.
191  */
192 #define NET80211_AUTHENTICATED  (1 << 9)
193
194 /** Whether we have successfully associated with the network */
195 #define NET80211_ASSOCIATED     (1 << 10)
196
197 /** Whether we have completed security handshaking with the network
198  *
199  * Once this is set, we can send data packets. For that reason this
200  * bit is set even in cases where no security handshaking is
201  * required.
202  */
203 #define NET80211_CRYPTO_SYNCED  (1 << 11)
204
205 /** Whether the auto-association task is running */
206 #define NET80211_WORKING        (1 << 12)
207
208 /** Whether the auto-association task is waiting for a reply from the AP */
209 #define NET80211_WAITING        (1 << 13)
210
211 /** Whether the auto-association task should be suppressed
212  *
213  * This is set by the `iwlist' command so that it can open the device
214  * without starting another probe process that will interfere with its
215  * own.
216  */
217 #define NET80211_NO_ASSOC       (1 << 14)
218
219 /** Whether this association was performed using a broadcast SSID
220  *
221  * If the user opened this device without netX/ssid set, the device's
222  * SSID will be set to that of the network it chooses to associate
223  * with, but the netX/ssid setting will remain blank. If we don't
224  * remember that we started from no specified SSID, it will appear
225  * every time settings are updated (e.g. after DHCP) that we need to
226  * reassociate due to the difference between the set SSID and our own.
227  */
228 #define NET80211_AUTO_SSID      (1 << 15)
229
230
231 /** @} */
232
233
234 /** @defgroup net80211_phy 802.11 physical layer flags */
235 /** @{ */
236
237 /** Whether to use RTS/CTS or CTS-to-self protection for transmissions
238  *
239  * Since the RTS or CTS is transmitted using 802.11b signaling, and
240  * includes a field indicating the amount of time that will be used by
241  * transmission of the following packet, this serves as an effective
242  * protection mechanism to avoid 802.11b clients interfering with
243  * 802.11g clients on mixed networks.
244  */
245 #define NET80211_PHY_USE_PROTECTION      (1 << 1)
246
247 /** Whether to use 802.11b short preamble operation
248  *
249  * Short-preamble operation can moderately increase throughput on
250  * 802.11b networks operating between 2Mbps and 11Mbps. It is
251  * irrelevant for 802.11g data rates, since they use a different
252  * modulation scheme.
253  */
254 #define NET80211_PHY_USE_SHORT_PREAMBLE  (1 << 2)
255
256 /** Whether to use 802.11g short slot operation
257  *
258  * This affects a low-level timing parameter of 802.11g transmissions.
259  */
260 #define NET80211_PHY_USE_SHORT_SLOT      (1 << 3)
261
262 /** @} */
263
264
265 /** The maximum number of TX rates we allow to be configured simultaneously */
266 #define NET80211_MAX_RATES      16
267
268 /** The maximum number of channels we allow to be configured simultaneously */
269 #define NET80211_MAX_CHANNELS   32
270
271 /** Seconds we'll wait to get all fragments of a packet */
272 #define NET80211_FRAG_TIMEOUT   2
273
274 /** The number of fragments we can receive at once
275  *
276  * The 802.11 standard requires that this be at least 3.
277  */
278 #define NET80211_NR_CONCURRENT_FRAGS 3
279
280 /** Maximum TX power to allow (dBm), if we don't get a regulatory hint */
281 #define NET80211_REG_TXPOWER    20
282
283
284 struct net80211_device;
285
286 /** Operations that must be implemented by an 802.11 driver */
287 struct net80211_device_operations {
288         /** Open 802.11 device
289          *
290          * @v dev       802.11 device
291          * @ret rc      Return status code
292          *
293          * This method should allocate RX I/O buffers and enable the
294          * hardware to start transmitting and receiving packets on the
295          * channels its net80211_register() call indicated it could
296          * handle. It does not need to tune the antenna to receive
297          * packets on any particular channel.
298          */
299         int ( * open ) ( struct net80211_device *dev );
300
301         /** Close 802.11 network device
302          *
303          * @v dev       802.11 device
304          *
305          * This method should stop the flow of packets, and call
306          * net80211_tx_complete() for any packets remaining in the
307          * device's TX queue.
308          */
309         void ( * close ) ( struct net80211_device *dev );
310
311         /** Transmit packet on 802.11 network device
312          *
313          * @v dev       802.11 device
314          * @v iobuf     I/O buffer
315          * @ret rc      Return status code
316          *
317          * This method should cause the hardware to initiate
318          * transmission of the I/O buffer, using the channel and rate
319          * most recently indicated by an appropriate call to the
320          * @c config callback. The 802.11 layer guarantees that said
321          * channel and rate will be the same as those currently
322          * reflected in the fields of @a dev.
323          *
324          * If this method returns success, the I/O buffer remains
325          * owned by the network layer's TX queue, and the driver must
326          * eventually call net80211_tx_complete() to free the buffer
327          * whether transmission succeeded or not. If this method
328          * returns failure, it will be interpreted as "failure to
329          * enqueue buffer" and the I/O buffer will be immediately
330          * released.
331          *
332          * This method is guaranteed to be called only when the device
333          * is open.
334          */
335         int ( * transmit ) ( struct net80211_device *dev,
336                              struct io_buffer *iobuf );
337
338         /** Poll for completed and received packets
339          *
340          * @v dev       802.11 device
341          *
342          * This method should cause the hardware to check for
343          * completed transmissions and received packets. Any received
344          * packets should be delivered via net80211_rx(), and
345          * completed transmissions should be indicated using
346          * net80211_tx_complete().
347          *
348          * This method is guaranteed to be called only when the device
349          * is open.
350          */
351         void ( * poll ) ( struct net80211_device *dev );
352
353         /** Enable or disable interrupts
354          *
355          * @v dev       802.11 device
356          * @v enable    If TRUE, interrupts should be enabled
357          */
358         void ( * irq ) ( struct net80211_device *dev, int enable );
359
360         /** Update hardware state to match 802.11 layer state
361          *
362          * @v dev       802.11 device
363          * @v changed   Set of flags indicating what may have changed
364          * @ret rc      Return status code
365          *
366          * This method should cause the hardware state to be
367          * reinitialized from the state indicated in fields of
368          * net80211_device, in the areas indicated by bits set in
369          * @a changed. If the hardware is unable to do so, this method
370          * may return an appropriate error indication.
371          *
372          * This method is guaranteed to be called only when the device
373          * is open.
374          */
375         int ( * config ) ( struct net80211_device *dev, int changed );
376 };
377
378 /** An 802.11 RF channel. */
379 struct net80211_channel
380 {
381         /** The band with which this channel is associated */
382         u8 band;
383
384         /** A channel number interpreted according to the band
385          *
386          * The 2.4GHz band uses channel numbers from 1-13 at 5MHz
387          * intervals such that channel 1 is 2407 MHz; channel 14,
388          * legal for use only in Japan, is defined separately as 2484
389          * MHz. Adjacent channels will overlap, since 802.11
390          * transmissions use a 20 MHz (4-channel) bandwidth. Most
391          * commonly, channels 1, 6, and 11 are used.
392          *
393          * The 5GHz band uses channel numbers derived directly from
394          * the frequency; channel 0 is 5000 MHz, and channels are
395          * always spaced 5 MHz apart. Channel numbers over 180 are
396          * relative to 4GHz instead of 5GHz, but these are rarely
397          * seen. Most channels are not legal for use.
398          */
399         u8 channel_nr;
400
401         /** The center frequency for this channel
402          *
403          * Currently a bandwidth of 20 MHz is assumed.
404          */
405         u16 center_freq;
406
407         /** Hardware channel value */
408         u16 hw_value;
409
410         /** Maximum allowable transmit power, in dBm
411          *
412          * This should be interpreted as EIRP, the power supplied to
413          * an ideal isotropic antenna in order to achieve the same
414          * average signal intensity as the real hardware at a
415          * particular distance.
416          *
417          * Currently no provision is made for directional antennas.
418          */
419         u8 maxpower;
420 };
421
422 /** Information on the capabilities of an 802.11 hardware device
423  *
424  * In its probe callback, an 802.11 driver must read hardware
425  * registers to determine the appropriate contents of this structure,
426  * fill it, and pass it to net80211_register() so that the 802.11
427  * layer knows how to treat the hardware and what to advertise as
428  * supported to access points.
429  */
430 struct net80211_hw_info
431 {
432         /** Default hardware MAC address.
433          *
434          * The user may change this by setting the @c netX/mac setting
435          * before the driver's open function is called; in that case
436          * the driver must set the hardware MAC address to the address
437          * contained in the wrapping net_device's ll_addr field, or if
438          * that is impossible, set that ll_addr field back to the
439          * unchangeable hardware MAC address.
440          */
441         u8 hwaddr[ETH_ALEN];
442
443         /** A bitwise OR of the 802.11x modes supported by this device */
444         int modes;
445
446         /** A bitwise OR of the bands on which this device can communicate */
447         int bands;
448
449         /** A set of flags indicating peculiarities of this device. */
450         enum {
451                 /** Received frames include a frame check sequence. */
452                 NET80211_HW_RX_HAS_FCS = (1 << 1),
453
454                 /** Hardware doesn't support 2.4GHz short preambles
455                  *
456                  * This is only relevant for 802.11b operation above
457                  * 2Mbps. All 802.11g devices support short preambles.
458                  */
459                 NET80211_HW_NO_SHORT_PREAMBLE = (1 << 2),
460
461                 /** Hardware doesn't support 802.11g short slot operation */
462                 NET80211_HW_NO_SHORT_SLOT = (1 << 3),
463         } flags;
464
465         /** Signal strength information that can be provided by the device
466          *
467          * Signal strength is passed to net80211_rx(), primarily to
468          * allow determination of the closest access point for a
469          * multi-AP network. The units are provided for completeness
470          * of status displays.
471          */
472         enum {
473                 /** No signal strength information supported */
474                 NET80211_SIGNAL_NONE = 0,
475                 /** Signal strength in arbitrary units */
476                 NET80211_SIGNAL_ARBITRARY,
477                 /** Signal strength in decibels relative to arbitrary base */
478                 NET80211_SIGNAL_DB,
479                 /** Signal strength in decibels relative to 1mW */
480                 NET80211_SIGNAL_DBM,
481         } signal_type;
482
483         /** Maximum signal in arbitrary cases
484          *
485          * If signal_type is NET80211_SIGNAL_ARBITRARY or
486          * NET80211_SIGNAL_DB, the driver should report it on a scale
487          * from 0 to signal_max.
488          */
489         unsigned signal_max;
490
491         /** List of RF channels supported by the card */
492         struct net80211_channel channels[NET80211_MAX_CHANNELS];
493
494         /** Number of supported channels */
495         int nr_channels;
496
497         /** List of transmission rates supported by the card, indexed by band
498          *
499          * Rates should be in 100kbps increments (e.g. 11 Mbps would
500          * be represented as the number 110).
501          */
502         u16 rates[NET80211_NR_BANDS][NET80211_MAX_RATES];
503
504         /** Number of supported rates, indexed by band */
505         int nr_rates[NET80211_NR_BANDS];
506
507         /** Estimate of the time required to change channels, in microseconds
508          *
509          * If this is not known, a guess on the order of a few
510          * milliseconds (value of 1000-5000) is reasonable.
511          */
512         unsigned channel_change_time;
513 };
514
515 /** Structure tracking received fragments for a packet
516  *
517  * We set up a fragment cache entry when we receive a packet marked as
518  * fragment 0 with the "more fragments" bit set in its frame control
519  * header. We are required by the 802.11 standard to track 3
520  * fragmented packets arriving simultaneously; if we receive more we
521  * may drop some. Upon receipt of a new fragment-0 packet, if no entry
522  * is available or expired, we take over the most @e recent entry for
523  * the new packet, since we don't want to starve old entries from ever
524  * finishing at all. If we get a fragment after the zeroth with no
525  * cache entry for its packet, we drop it.
526  */
527 struct net80211_frag_cache
528 {
529         /** Whether this cache entry is in use */
530         u8 in_use;
531
532         /** Sequence number of this MSDU (packet) */
533         u16 seqnr;
534
535         /** Timestamp from point at which first fragment was collected */
536         u32 start_ticks;
537
538         /** Buffers for each fragment */
539         struct io_buffer *iob[16];
540 };
541
542 /** Interface to an 802.11 cryptographic algorithm
543  *
544  * Cryptographic algorithms define a net80211_crypto structure
545  * statically, using a gPXE linker table to make it available to the
546  * 802.11 layer. When the algorithm needs to be used, the 802.11 code
547  * will allocate a copy of the static definition plus whatever space
548  * the algorithm has requested for private state, and point
549  * net80211_device::crypto at it.
550  */
551 struct net80211_crypto
552 {
553         /** The cryptographic algorithm implemented */
554         enum net80211_crypto_alg algorithm;
555
556         /** Initialize cryptographic algorithm using a given key
557          *
558          * @v crypto    802.11 cryptographic algorithm
559          * @v key       Pointer to key bytes
560          * @v keylen    Number of key bytes
561          * @ret rc      Return status code
562          *
563          * This method is passed the communication key provided by the
564          * security handshake handler, which will already be in the
565          * low-level form required.
566          */
567         int ( * initialize ) ( struct net80211_crypto *crypto, u8 *key,
568                                int keylen );
569
570         /** Encrypt a frame using the cryptographic algorithm
571          *
572          * @v crypto    802.11 cryptographic algorithm
573          * @v iob       I/O buffer
574          * @ret eiob    Newly allocated I/O buffer with encrypted packet
575          *
576          * This method is called to encrypt a single frame. It is
577          * guaranteed that initialize() will have completed
578          * successfully before this method is called.
579          *
580          * The frame passed already has an 802.11 header prepended,
581          * but the PROTECTED bit in the frame control field will not
582          * be set; this method is responsible for setting it. The
583          * returned I/O buffer should contain a complete copy of @a
584          * iob, including the 802.11 header, but with the PROTECTED
585          * bit set, the data encrypted, and whatever encryption
586          * headers/trailers are necessary added.
587          *
588          * This method should never free the passed I/O buffer.
589          *
590          * Return NULL if the packet could not be encrypted, due to
591          * memory limitations or otherwise.
592          */
593         struct io_buffer * ( * encrypt ) ( struct net80211_crypto *crypto,
594                                            struct io_buffer *iob );
595
596         /** Decrypt a frame using the cryptographic algorithm
597          *
598          * @v crypto    802.11 cryptographic algorithm
599          * @v eiob      Encrypted I/O buffer
600          * @ret iob     Newly allocated I/O buffer with decrypted packet
601          *
602          * This method is called to decrypt a single frame. It is
603          * guaranteed that initialize() will have completed
604          * successfully before this method is called.
605          *
606          * Decryption follows the reverse of the pattern used for
607          * encryption: this method must copy the 802.11 header into
608          * the returned packet, decrypt the data stream, remove any
609          * encryption header or trailer, and clear the PROTECTED bit
610          * in the frame control header.
611          *
612          * This method should never free the passed I/O buffer.
613          *
614          * Return NULL if memory was not available for decryption, if
615          * a consistency or integrity check on the decrypted frame
616          * failed, or if the decrypted frame should not be processed
617          * by the network stack for any other reason.
618          */
619         struct io_buffer * ( * decrypt ) ( struct net80211_crypto *crypto,
620                                            struct io_buffer *iob );
621
622         /** Length of private data requested to be allocated */
623         int priv_len;
624
625         /** Private data for the algorithm to store key and state info */
626         void *priv;
627 };
628
629
630 struct net80211_probe_ctx;
631 struct net80211_assoc_ctx;
632
633
634 /** Structure encapsulating the complete state of an 802.11 device
635  *
636  * An 802.11 device is always wrapped by a network device, and this
637  * network device is always pointed to by the @a netdev field. In
638  * general, operations should never be performed by 802.11 code using
639  * netdev functions directly. It is usually the case that the 802.11
640  * layer might need to do some processing or bookkeeping on top of
641  * what the netdevice code will do.
642  */
643 struct net80211_device
644 {
645         /** The net_device that wraps us. */
646         struct net_device *netdev;
647
648         /** List of 802.11 devices. */
649         struct list_head list;
650
651         /** 802.11 device operations */
652         struct net80211_device_operations *op;
653
654         /** Driver private data */
655         void *priv;
656
657         /** Information about the hardware, provided to net80211_register() */
658         struct net80211_hw_info *hw;
659
660         /* ---------- Channel and rate fields ---------- */
661
662         /** A list of all possible channels we might use */
663         struct net80211_channel channels[NET80211_MAX_CHANNELS];
664
665         /** The number of channels in the channels array */
666         u8 nr_channels;
667
668         /** The channel currently in use, as an index into the channels array */
669         u8 channel;
670
671         /** A list of all possible TX rates we might use
672          *
673          * Rates are in units of 100 kbps.
674          */
675         u16 rates[NET80211_MAX_RATES];
676
677         /** The number of transmission rates in the rates array */
678         u8 nr_rates;
679
680         /** The rate currently in use, as an index into the rates array */
681         u8 rate;
682
683         /** The rate to use for RTS/CTS transmissions
684          *
685          * This is always the fastest basic rate that is not faster
686          * than the data rate in use. Also an index into the rates array.
687          */
688         u8 rtscts_rate;
689
690         /** Bitmask of basic rates
691          *
692          * If bit N is set in this value, with the LSB considered to
693          * be bit 0, then rate N in the rates array is a "basic" rate.
694          *
695          * We don't decide which rates are "basic"; our AP does, and
696          * we respect its wishes. We need to be able to identify basic
697          * rates in order to calculate the duration of a CTS packet
698          * used for 802.11 g/b interoperability.
699          */
700         u32 basic_rates;
701
702         /* ---------- Association fields ---------- */
703
704         /** The asynchronous association process.
705          *
706          * When an 802.11 netdev is opened, or when the user changes
707          * the SSID setting on an open 802.11 device, an
708          * autoassociation task is started by net80211_autoassocate()
709          * to associate with the new best network. The association is
710          * asynchronous, but no packets can be transmitted until it is
711          * complete. If it is successful, the wrapping net_device is
712          * set as "link up". If it fails, @c assoc_rc will be set with
713          * an error indication.
714          */
715         struct process proc_assoc;
716
717         /** Network with which we are associating
718          *
719          * This will be NULL when we are not actively in the process
720          * of associating with a network we have already successfully
721          * probed for.
722          */
723         struct net80211_wlan *associating;
724
725         /** Context for the association process
726          *
727          * This is a probe_ctx if the @c PROBED flag is not set in @c
728          * state, and an assoc_ctx otherwise.
729          */
730         union {
731                 struct net80211_probe_ctx *probe;
732                 struct net80211_assoc_ctx *assoc;
733         } ctx;
734
735         /** State of our association to the network
736          *
737          * Since the association process happens asynchronously, it's
738          * necessary to have some channel of communication so the
739          * driver can say "I got an association reply and we're OK" or
740          * similar. This variable provides that link. It is a bitmask
741          * of any of NET80211_PROBED, NET80211_AUTHENTICATED,
742          * NET80211_ASSOCIATED, NET80211_CRYPTO_SYNCED to indicate how
743          * far along in associating we are; NET80211_WORKING if the
744          * association task is running; and NET80211_WAITING if a
745          * packet has been sent that we're waiting for a reply to. We
746          * can only be crypto-synced if we're associated, we can
747          * only be associated if we're authenticated, we can only be
748          * authenticated if we've probed.
749          *
750          * If an association process fails (that is, we receive a
751          * packet with an error indication), the error code is copied
752          * into bits 6-0 of this variable and bit 7 is set to specify
753          * what type of error code it is. An AP can provide either a
754          * "status code" (0-51 are defined) explaining why it refused
755          * an association immediately, or a "reason code" (0-45 are
756          * defined) explaining why it canceled an association after it
757          * had originally OK'ed it. Status and reason codes serve
758          * similar functions, but they use separate error message
759          * tables. A gPXE-formatted return status code (negative) is
760          * placed in @c assoc_rc.
761          *
762          * If the failure to associate is indicated by a status code,
763          * the NET80211_IS_REASON bit will be clear; if it is
764          * indicated by a reason code, the bit will be set. If we were
765          * successful, both zero status and zero reason mean success,
766          * so there is no ambiguity.
767          *
768          * To prevent association when opening the device, user code
769          * can set the NET80211_NO_ASSOC bit. The final bit in this
770          * variable, NET80211_AUTO_SSID, is used to remember whether
771          * we picked our SSID through automated probing as opposed to
772          * user specification; the distinction becomes relevant in the
773          * settings applicator.
774          */
775         u16 state;
776
777         /** Return status code associated with @c state */
778         int assoc_rc;
779
780         /* ---------- Parameters of currently associated network ---------- */
781
782         /** 802.11 cryptographic algorithm for our current network
783          *
784          * For an open network, this will be set to NULL.
785          */
786         struct net80211_crypto *crypto;
787
788         /** MAC address of the access point most recently associated */
789         u8 bssid[ETH_ALEN];
790
791         /** SSID of the access point we are or will be associated with
792          *
793          * Although the SSID field in 802.11 packets is generally not
794          * NUL-terminated, here and in net80211_wlan we add a NUL for
795          * convenience.
796          */
797         char essid[IEEE80211_MAX_SSID_LEN+1];
798
799         /** Association ID given to us by the AP */
800         u16 aid;
801
802         /** TSFT value for last beacon received, microseconds */
803         u64 last_beacon_timestamp;
804
805         /** Time between AP sending beacons, microseconds */
806         u32 tx_beacon_interval;
807
808         /** Smoothed average time between beacons, microseconds */
809         u32 rx_beacon_interval;
810
811         /* ---------- Physical layer information ---------- */
812
813         /** Physical layer options
814          *
815          * These control the use of CTS protection, short preambles,
816          * and short-slot operation.
817          */
818         int phy_flags;
819
820         /** Signal strength of last received packet */
821         int last_signal;
822
823         /** Rate control state */
824         struct rc80211_ctx *rctl;
825
826         /* ---------- Packet handling state ---------- */
827
828         /** Fragment reassembly state */
829         struct net80211_frag_cache frags[NET80211_NR_CONCURRENT_FRAGS];
830
831         /** The sequence number of the last packet we sent */
832         u16 last_tx_seqnr;
833
834         /** Packet duplication elimination state
835          *
836          * We are only required to handle immediate duplicates for
837          * each direct sender, and since we can only have one direct
838          * sender (the AP), we need only keep the sequence control
839          * field from the most recent packet we've received. Thus,
840          * this field stores the last sequence control field we've
841          * received for a packet from the AP.
842          */
843         u16 last_rx_seq;
844
845         /** RX management packet queue
846          *
847          * Sometimes we want to keep probe, beacon, and action packets
848          * that we receive, such as when we're scanning for networks.
849          * Ordinarily we drop them because they are sent at a large
850          * volume (ten beacons per second per AP, broadcast) and we
851          * have no need of them except when we're scanning.
852          *
853          * When keep_mgmt is TRUE, received probe, beacon, and action
854          * management packets will be stored in this queue.
855          */
856         struct list_head mgmt_queue;
857
858         /** RX management packet info queue
859          *
860          * We need to keep track of the signal strength for management
861          * packets we're keeping, because that provides the only way
862          * to distinguish between multiple APs for the same network.
863          * Since we can't extend io_buffer to store signal, this field
864          * heads a linked list of "RX packet info" structures that
865          * contain that signal strength field. Its entries always
866          * parallel the entries in mgmt_queue, because the two queues
867          * are always added to or removed from in parallel.
868          */
869         struct list_head mgmt_info_queue;
870
871         /** Whether to store management packets
872          *
873          * Received beacon, probe, and action packets will be added to
874          * mgmt_queue (and their signal strengths added to
875          * mgmt_info_queue) only when this variable is TRUE. It should
876          * be set by net80211_keep_mgmt() (which returns the old
877          * value) only when calling code is prepared to poll the
878          * management queue frequently, because packets will otherwise
879          * pile up and exhaust memory.
880          */
881         int keep_mgmt;
882 };
883
884 /** Structure representing a probed network.
885  *
886  * This is returned from the net80211_probe_finish functions and
887  * passed to the low-level association functions. At least essid,
888  * bssid, channel, beacon, and security must be filled in if you want
889  * to build this structure manually.
890  */
891 struct net80211_wlan
892 {
893         /** The human-readable ESSID (network name)
894          *
895          * Although the 802.11 SSID field is generally not
896          * NUL-terminated, the gPXE code adds an extra NUL (and
897          * expects one in this structure) for convenience.
898          */
899         char essid[IEEE80211_MAX_SSID_LEN+1];
900
901         /** MAC address of the strongest-signal access point for this ESSID */
902         u8 bssid[ETH_ALEN];
903
904         /** Signal strength of beacon frame from that access point */
905         int signal;
906
907         /** The channel on which that access point communicates
908          *
909          * This is a raw channel number (net80211_channel::channel_nr),
910          * so that it will not be affected by reconfiguration of the
911          * device channels array.
912          */
913         int channel;
914
915         /** The complete beacon or probe-response frame received */
916         struct io_buffer *beacon;
917
918         /** Security handshaking method used on the network */
919         enum net80211_security_proto handshaking;
920
921         /** Cryptographic algorithm used on the network */
922         enum net80211_crypto_alg crypto;
923
924         /** Link to allow chaining multiple structures into a list to
925             be returned from net80211_probe_finish_all(). */
926         struct list_head list;
927 };
928
929
930 /**
931  * @defgroup net80211_probe 802.11 network location API
932  * @{
933  */
934 int net80211_prepare_probe ( struct net80211_device *dev, int band,
935                              int active );
936 struct net80211_probe_ctx * net80211_probe_start ( struct net80211_device *dev,
937                                                    const char *essid,
938                                                    int active );
939 int net80211_probe_step ( struct net80211_probe_ctx *ctx );
940 struct net80211_wlan *
941 net80211_probe_finish_best ( struct net80211_probe_ctx *ctx );
942 struct list_head *net80211_probe_finish_all ( struct net80211_probe_ctx *ctx );
943
944 void net80211_free_wlan ( struct net80211_wlan *wlan );
945 void net80211_free_wlanlist ( struct list_head *list );
946 /** @} */
947
948
949 /**
950  * @defgroup net80211_mgmt 802.11 network management API
951  * @{
952  */
953 struct net80211_device * net80211_get ( struct net_device *netdev );
954 void net80211_autoassociate ( struct net80211_device *dev );
955
956 int net80211_change_channel ( struct net80211_device *dev, int channel );
957 void net80211_set_rate_idx ( struct net80211_device *dev, int rate );
958
959 int net80211_keep_mgmt ( struct net80211_device *dev, int enable );
960 struct io_buffer * net80211_mgmt_dequeue ( struct net80211_device *dev,
961                                            int *signal );
962 int net80211_tx_mgmt ( struct net80211_device *dev, u16 fc,
963                        u8 bssid[ETH_ALEN], struct io_buffer *iob );
964 /** @} */
965
966
967 /**
968  * @defgroup net80211_assoc 802.11 network association API
969  * @{
970  */
971 int net80211_prepare_assoc ( struct net80211_device *dev,
972                              struct net80211_wlan *wlan );
973 int net80211_send_auth ( struct net80211_device *dev,
974                          struct net80211_wlan *wlan, int method );
975 int net80211_send_assoc ( struct net80211_device *dev,
976                           struct net80211_wlan *wlan );
977 /** @} */
978
979
980 /**
981  * @defgroup net80211_driver 802.11 driver interface API
982  * @{
983  */
984 struct net80211_device *net80211_alloc ( size_t priv_size );
985 int net80211_register ( struct net80211_device *dev,
986                         struct net80211_device_operations *ops,
987                         struct net80211_hw_info *hw );
988 u16 net80211_duration ( struct net80211_device *dev, int bytes, u16 rate );
989 void net80211_rx ( struct net80211_device *dev, struct io_buffer *iob,
990                    int signal, u16 rate );
991 void net80211_rx_err ( struct net80211_device *dev,
992                        struct io_buffer *iob, int rc );
993 void net80211_tx_complete ( struct net80211_device *dev,
994                             struct io_buffer *iob, int retries, int rc );
995 void net80211_unregister ( struct net80211_device *dev );
996 void net80211_free ( struct net80211_device *dev );
997 /** @} */
998
999 /**
1000  * Calculate duration field for a CTS control frame
1001  *
1002  * @v dev       802.11 device
1003  * @v size      Size of the packet being cleared to send
1004  *
1005  * A CTS control frame's duration field captures the frame being
1006  * protected and its 10-byte ACK.
1007  */
1008 static inline u16 net80211_cts_duration ( struct net80211_device *dev,
1009                                           int size )
1010 {
1011         return ( net80211_duration ( dev, 10,
1012                                      dev->rates[dev->rtscts_rate] ) +
1013                  net80211_duration ( dev, size, dev->rates[dev->rate] ) );
1014 }
1015
1016 #endif