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