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