source: grub-pc/trunk/fuentes/debian/grub-extras/disabled/gpxe/src/include/gpxe/net80211.h @ 22

Last change on this file since 22 was 22, checked in by mabarracus, 4 years ago

updated version and apply net.ifnames=0 into debian/rules

File size: 33.0 KB
Line 
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
34FILE_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 */
96enum 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 */
126enum 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
284struct net80211_device;
285
286/** Operations that must be implemented by an 802.11 driver */
287struct 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. */
379struct 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 */
430struct 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 */
527struct 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 */
551struct 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
630struct net80211_probe_ctx;
631struct 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 */
643struct 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 */
891struct 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 */
934int net80211_prepare_probe ( struct net80211_device *dev, int band,
935                             int active );
936struct net80211_probe_ctx * net80211_probe_start ( struct net80211_device *dev,
937                                                   const char *essid,
938                                                   int active );
939int net80211_probe_step ( struct net80211_probe_ctx *ctx );
940struct net80211_wlan *
941net80211_probe_finish_best ( struct net80211_probe_ctx *ctx );
942struct list_head *net80211_probe_finish_all ( struct net80211_probe_ctx *ctx );
943
944void net80211_free_wlan ( struct net80211_wlan *wlan );
945void net80211_free_wlanlist ( struct list_head *list );
946/** @} */
947
948
949/**
950 * @defgroup net80211_mgmt 802.11 network management API
951 * @{
952 */
953struct net80211_device * net80211_get ( struct net_device *netdev );
954void net80211_autoassociate ( struct net80211_device *dev );
955
956int net80211_change_channel ( struct net80211_device *dev, int channel );
957void net80211_set_rate_idx ( struct net80211_device *dev, int rate );
958
959int net80211_keep_mgmt ( struct net80211_device *dev, int enable );
960struct io_buffer * net80211_mgmt_dequeue ( struct net80211_device *dev,
961                                           int *signal );
962int 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 */
971int net80211_prepare_assoc ( struct net80211_device *dev,
972                             struct net80211_wlan *wlan );
973int net80211_send_auth ( struct net80211_device *dev,
974                         struct net80211_wlan *wlan, int method );
975int 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 */
984struct net80211_device *net80211_alloc ( size_t priv_size );
985int net80211_register ( struct net80211_device *dev,
986                        struct net80211_device_operations *ops,
987                        struct net80211_hw_info *hw );
988u16 net80211_duration ( struct net80211_device *dev, int bytes, u16 rate );
989void net80211_rx ( struct net80211_device *dev, struct io_buffer *iob,
990                   int signal, u16 rate );
991void net80211_rx_err ( struct net80211_device *dev,
992                       struct io_buffer *iob, int rc );
993void net80211_tx_complete ( struct net80211_device *dev,
994                            struct io_buffer *iob, int retries, int rc );
995void net80211_unregister ( struct net80211_device *dev );
996void 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 */
1008static 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
Note: See TracBrowser for help on using the repository browser.