[802.11] The 802.11 MAC layer, second big commit
[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 /* Constants for the (*config)() callback */
40 #define NET80211_CFG_CHANNEL     (1 << 0) /* channel # or txpower */
41 #define NET80211_CFG_RATE        (1 << 1)
42 #define NET80211_CFG_ASSOC       (1 << 2)
43 #define NET80211_CFG_ERP_PARAMS  (1 << 3)
44
45 struct net80211_device;
46
47 /** Operations that must be implemented by an 802.11 driver. */
48 struct net80211_device_operations {
49         /* These have the same semantics as they do in net_device. */
50
51         int (*open)(struct net80211_device *dev);
52         void (*close)(struct net80211_device *dev);
53         int (*transmit)(struct net80211_device *dev, struct io_buffer *iobuf);
54         void (*poll)(struct net80211_device *dev);
55         void (*irq)(struct net80211_device *dev, int enable);
56
57         /* And these are specific to 802.11. */
58
59         /** Update hardware state to match the state in
60             net80211_device with respect to `changed', a bitwise OR of
61             NET80211_CFG_* indicating what's changed. Only called when
62             the device is open. */
63         int (*config)(struct net80211_device *dev, int changed);
64 };
65
66 #define NET80211_BAND_2GHZ  (1 << 0)    /* the 2.4 GHz ISM band */
67 #define NET80211_BAND_5GHZ  (1 << 1)    /* the band from 4.9 to 5.7 GHz */
68
69 /** An 802.11 RF channel. */
70 struct net80211_channel
71 {
72         u8 band;                /* one of NET80211_BAND_* */
73
74         u8 channel_nr;          /* a traditional channel number,
75                                    e.g. 1-11 for the 2.4GHz band */
76
77         u16 center_freq;        /* MHz of channel center */
78         u8 maxpower;            /* maximum allowable EIRP in dBm */
79
80         /* There are more regulatory issues than this - bandwidth and
81            antenna gain are the main ones - but we can't do anything
82            about them based on the information in beacon frames, so we
83            assume 20 MHz bandwidth and a sane antenna setup by the user. */
84 };
85
86 #define NET80211_MODE_A  (1 << 0)
87 #define NET80211_MODE_B  (1 << 1)
88 #define NET80211_MODE_G  (1 << 2)
89 #define NET80211_MODE_N  (1 << 3)
90
91 #define NET80211_MAX_RATES     16
92 #define NET80211_MAX_CHANNELS  32
93
94 /** Information on the capabilities of the hardware supported by a
95     driver; must be filled in by said driver. */
96 struct net80211_hw_info
97 {
98         /** Hardware MAC address. */
99         u8 hwaddr[ETH_ALEN];
100
101         /** A bitwise OR of the 802.11x modes supported by this device. */
102         int modes;              /* e.g. NET80211_MODE_B | NET80211_MODE_G */
103
104         /** A bitwise OR of the bands on which this device can communicate. */
105         int bands;              /* e.g. NET80211_BAND_2GHZ */
106
107         enum {
108                 /** Received frames include a frame check sequence. */
109                 NET80211_HW_RX_HAS_FCS = (1 << 1),
110
111                 /** Hardware doesn't support short preambles on the
112                     2.4GHz band (all 802.11g devices do). */
113                 NET80211_HW_NO_SHORT_PREAMBLE = (1 << 2),
114
115                 /** Hardware doesn't support short slot operation on
116                     the 2.4GHz band (only relevant for 802.11g). */
117                 NET80211_HW_NO_SHORT_SLOT = (1 << 3),
118         } flags;
119
120         /** Set according to the type of signal strength information
121             that can be provided. */
122         enum {
123                 NET80211_SIGNAL_NONE = 0,  /**< no info at all */
124                 NET80211_SIGNAL_ARBITRARY, /**< arbitrary units */
125                 NET80211_SIGNAL_DB,        /**< dB relative to arbitrary base */
126                 NET80211_SIGNAL_DBM,       /**< dB relative to 1mW */
127         } signal_type;
128         
129         /** List of transmit supported by the card, in 100kbps
130             increments. */
131         u16 supported_rates[NET80211_MAX_RATES];
132         /** Number of supported rates. */
133         int nr_supported_rates;
134
135         /** If signal_type involves arbitrary units, it should be
136             reported on a scale from 0 to signal_max. */
137         unsigned signal_max;
138
139         /** Amount of time required to change channels, in
140             microseconds. */
141         unsigned channel_change_time;
142 };
143
144 /** Seconds we'll wait to get all fragments of a packet. If this
145     timer expires, we drop the fragments we've received so far. */
146 #define NET80211_FRAG_TIMEOUT  2
147
148 /** Keeps track of the fragments for a particular packet as we receive
149     them. We set up the frag_cache entry when we receive a fragment 0
150     with MOREFRAGS set; if all are unexpired we take over the one with
151     the most recent activity (and drop the frags it used to contain).
152     If we get a fragment after the zeroth with no cache entry for its
153     packet, we drop it. The standard says we're allowed to be cavalier
154     like this, as long as we have >= 3 cache entries. */
155 struct net80211_frag_cache
156 {
157         /** State of this frag cache entry. */
158         u8 state;
159 #define NET80211_FRAG_AVAIL     0 /* not in use */
160 #define NET80211_FRAG_WAITING   1 /* waiting for the final fragment */
161 #define NET80211_FRAG_FINISHING 2 /* waiting for holes to fill */
162
163         /** Number of fragments to expect, if state is FINISHING. */
164         u8 nfrags;
165
166         /** Sequence number of this MSDU (packet). */
167         u16 seqnr;
168
169         /** Timestamp of when we started collecting these frags. */
170         u32 start_ticks;
171
172         /** Buffers for each fragment (they can arrive out of order). */
173         struct io_buffer *iob[16];
174 };
175
176 /* 802.11 data security protocols: */
177 #define NET80211_CRYPT_NONE   0 /* "Open" */
178 #define NET80211_CRYPT_WEP40  2 /* "WEP 64-bit" (5-character key) */
179 #define NET80211_CRYPT_WEP104 3 /* "WEP 128-bit" (13-character key) */
180 #define NET80211_CRYPT_TKIP   4 /* "WPA Personal" */
181 #define NET80211_CRYPT_CCMP   5 /* "WPA2 Personal" */
182 #define NET80211_CRYPT_EAP    8 /* "WPA2 Enterprise" */
183
184 /** Interface to a cryptographic algorithm. */
185 struct net80211_crypto
186 {
187         /** Type, as one of the constants defined above. */
188         short type;
189
190         /** Initialize crypto algorithm using the given key. */
191         void (*initialize)(struct net80211_device *dev, u8 *key, int keylen);
192
193         /** Encrypt the given frame into a newly allocated io_buffer
194             with all frame headers intact. Returns NULL if out of
195             memory. */
196         struct io_buffer *(*encrypt)(struct net80211_device *dev,
197                                      struct io_buffer *iob);
198         
199         /** Decrypt the given frame into a newly allocated io_buffer
200             with all frame headers intact. Returns NULL if decryption
201             fails. */
202         struct io_buffer *(*decrypt)(struct net80211_device *dev,
203                                      struct io_buffer *iob);
204
205         /** Private data for the crypto algorithm to store key and
206             state information. */
207         void *priv;
208
209         /* More to come... */
210 };
211
212 /** Structure encapsulating the complete state of an 802.11
213     device. Stored in the `priv' member of some net_device. */
214 struct net80211_device
215 {
216         /** The net_device that wraps us. */
217         struct net_device *netdev;
218
219         /** List of 802.11 devices. */
220         struct list_head list;
221
222         /** Network device operations */
223         struct net80211_device_operations *op;
224
225         /** Driver private data */
226         void *priv;
227
228         /** Information about the hardware, which the driver is
229             responsible for providing. */
230         struct net80211_hw_info *hw;
231
232         /** The asynchronous association process. (Successful
233             association is represented as "link up".) */
234         struct process proc_assoc;
235         /** Data structure for the association process. */
236         struct net80211_wlan *associating;
237
238         /** A list of all possible channels, as computed from
239             regulatory information in the beacon frame. `channel' is
240             an index into this list. This should be NULL before
241             prepare() has been called. */
242         struct net80211_channel channels[NET80211_MAX_CHANNELS];
243         /** The number of channels in the `channels' list. */
244         u8 nr_channels;
245         /** The channel currently in use, as an index into the
246             `channels' list. */
247         u8 channel;
248
249         /** A list of all transmission rates supported by the AP we're
250             associated with, in units of 100 kbps. Max given flags is
251             16384 = 1.6 Gbps. */
252         u16 rates[NET80211_MAX_RATES];
253 #define NET80211_RATE_VALUE(r) ((r) & 0x3fff)
254 #define NET80211_RATE_ERP      0x8000 /* an 802.11g extended rate (>11Mbps) */
255         /** The number of transmission rates in the `rates' array. */
256         u8 nr_rates;    
257         /** The rate currently in use, as an index into the `rates' array. */
258         u8 rate;
259         /** If basic_rates & (1 << i), then rates[i] is a basic rate. */
260         u32 basic_rates;
261
262         /** State of our association to the network; bit OR of
263             NET80211_*ED and the most recent status returned by the
264             AP. */
265 #define NET80211_STATUS_MASK    0xFF /**< Mask for IEEE status code */
266 #define NET80211_AUTHENTICATED  (1 << 8)
267 #define NET80211_ASSOCIATED     (1 << 9)
268 #define NET80211_CRYPTO_SYNCED  (1 << 10)
269 #define NET80211_WORKING        (1 << 11) /**< Association task is running */
270 #define NET80211_WAITING        (1 << 12) /**< MAC layer awaiting AP reply */
271         short state;
272         /** Encryption method for the network we're associated to.
273             NULL for open. */
274         struct net80211_crypto *crypto;
275         /** Network to which we're associated, if `assoc' is set. */
276         u8 bssid[ETH_ALEN];
277         /** Name of the SSID we're connected to. */
278         char essid[IEEE80211_MAX_SSID_LEN+1];
279         /** Association ID given to us by the AP. */
280         u16 aid;
281         /** ERP-related options, set dynamically based on the assoc
282             reply packet. Set even for non-ERP networks based on the
283             capabilities field. */
284         int erp_flags;
285 #define NET80211_ERP_USE_PROTECTION      (1 << 1)
286 #define NET80211_ERP_USE_SHORT_PREAMBLE  (1 << 2)
287 #define NET80211_ERP_USE_SHORT_SLOT      (1 << 3)
288
289         /** Fragment reassembly state. IEEE standard requires >= 3. */
290 #define NET80211_NR_CONCURRENT_FRAGS  3
291         struct net80211_frag_cache frags[NET80211_NR_CONCURRENT_FRAGS];
292
293         /** The sequence number of the last packet we sent. */
294         u16 last_tx_seqnr;
295
296         /** Packet deduping state. We only are required to handle
297             immediate duplicates for each direct sender, and as we can
298             only have one direct sender (the AP), our job is easy. */
299         s16 last_rx_seq;        /* (frag << 12) | seqnr, as hdr->seq */
300
301         /** Sometimes we want to keep management packets we receive,
302             e.g. when we're scanning for networks. They will be stored
303             in this queue when keep_mgmt is true. */
304         struct list_head mgmt_queue;
305
306         /** RX packet info (signal strength) for packets in the
307             management queue. */
308         struct list_head mgmt_info_queue;
309
310         /** Store management packets only when TRUE. */
311         int keep_mgmt;
312 };
313
314 /** Structure returned from the scanning functions and passed to
315     net80211_associate(). At least essid, bssid, channel, and beacon
316     must be filled in. */
317 struct net80211_wlan
318 {
319         /** The human-readable ESSID (network name). */
320         char essid[IEEE80211_MAX_SSID_LEN+1];
321
322         /** The MAC address of the "best" access point (strongest
323             signal) for this ESSID. */
324         u8 bssid[ETH_ALEN];
325
326         /** The signal strength of communications from that access
327             point, measured in whatever units the hardware provides. */
328         int signal;
329
330         /** The channel on which that access point communicates;
331             pointer to an appropriate entry in dev->channels. */
332         struct net80211_channel *channel;
333
334         /** The complete beacon or probe-response frame from which
335             the network was identified. */
336         struct io_buffer *beacon;
337
338         /** One of the NET80211_CRYPT_* constants indicating the
339             security mode of the network. */
340         int security;
341         
342         /** State variable to be used by association task. */
343         int method;
344
345         /** Link to allow chaining multiple structures into a list to
346             be returned from net80211_scan(). */
347         struct list_head list;
348 };
349
350 /* Regulatory hints when we don't get any beacons: */
351 #define NET80211_REG_TXPOWER  20 /* conservative default, OK with
352                                     US/EU/JP at least */
353 /* 2.4GHz channels 1-11 are safe to transmit on everywhere. */
354
355
356 /* -- network scanning API: -- */
357
358 /** Scans the area, returning a list of net80211_wlan structures
359     corresponding to each of the reachable wireless networks. */
360 struct list_head *net80211_scan(struct net80211_device *dev);
361
362 /** Frees the list returned from a scan call. */
363 void net80211_free_wlanlist(struct list_head *netlist);
364
365 /** Scans for the given ESSID specifically. Can be used to associate
366     with "hidden" networks on the 2.4GHz band. */
367 struct net80211_wlan *net80211_probe(struct net80211_device *dev,
368                                      const char *essid, int active);
369
370 /** Frees a single net80211_wlan structure. */
371 void net80211_free_wlan(struct net80211_wlan *wlan);
372
373 /** Does scan/probe as appropriate given configured settings, and
374     associates. Operates as a background process; this function
375     returns immediately, before the association has been performed. */
376 void net80211_autoassociate(struct net80211_device *dev);
377
378 /* -- general-use net80211 API: -- */
379
380 /** If the passed net_device wraps a net80211_device, returns the
381     net80211_device. If not, returns NULL. */
382 struct net80211_device *net80211_get(struct net_device *netdev);
383
384 /* - association steps: -   [normally performed by autoassociate] */
385
386 /** Sets up the device's regulatory parameters to a sane default for
387     passive scanning or active 2.4GHz scanning. */
388 int net80211_prepare_default(struct net80211_device *dev, int band,
389                              int active);
390
391 /** Sets up the device's regulatory parameters as the provided beacon
392     or probe response frame tells us to. Must be called before
393     associating. */
394 int net80211_prepare(struct net80211_device *dev, struct net80211_wlan *wlan);
395
396 /** Performs an authentication sequence using the specified
397     method. Returns immediately, sets state variables. */
398 int net80211_send_auth(struct net80211_device *dev, struct net80211_wlan *wlan,
399                        int method);
400
401 /** Performs the actual association with the network described by
402     `wlan'. Requires authentication to have previously succeeded. */
403 int net80211_send_assoc(struct net80211_device *dev,
404                         struct net80211_wlan *wlan);
405
406 /* - management frame handling: - */
407
408 /** Sets the state of the device keeping management packets. Only call
409     this with enable == 1 if you're planning to actually look at all
410     the packets using net80211_mgmt_dequeue(); otherwise they'll pile
411     up and waste memory. Keeping management packets is disabled by
412     default. Returns the setting of keeping management packets that
413     preceded the function call. */
414 int net80211_keep_mgmt(struct net80211_device *dev, int enable);
415
416 /** Returns the next packet from the device's received management
417     packet queue, or NULL if the queue is empty. You must have called
418     net80211_set_management(dev, 1) previously. Ownership of the
419     returned io_buffer passes to the calling function. If `signal' is
420     non-NULL it is filled with the signal strength of the received
421     frame in device units. */
422 struct io_buffer *net80211_mgmt_dequeue(struct net80211_device *dev,
423                                         int *signal);
424
425 /** Sends an 802.11 management packet. The passed io_buffer must have
426     at least IEEE80211_TYP_FRAME_HEADER_LEN = 24 bytes of headroom for
427     the 802.11 frame header to be prepended. The management frame is
428     sent to the AP of the network identified by `bssid'; it is not
429     possible to use this function to send management frames that are
430     not directed at APs. The frame is encrypted if fc & PROTECTED. */
431 int net80211_tx_mgmt(struct net80211_device *dev, u16 fc, u8 bssid[6],
432                      struct io_buffer *iob);
433
434 /* -- Driver API: -- */
435
436 /* The 802.11 layer handles the things drivers usually do to the
437    wrapping net_device. Drivers should use the below functions and
438    *not* their net_device analogues on dev->netdev. */
439
440 /** Allocates a new 802.11 device with priv_size bytes of
441     driver-private data behind its `priv' pointer. This also allocates
442     the gPXE net_device and sets up its operations. */
443 struct net80211_device *net80211_alloc(size_t priv_size);
444
445 /** Set up an 802.11 device to use the provided operations and
446     hardware information, and register it with the network stack. The
447     hw info will be copied into a dynamically allocated structure that
448     the 802.11 layer takes ownership of; the ops are simply pointed
449     at, and should be defined statically. */
450 int net80211_register(struct net80211_device *dev,
451                       struct net80211_device_operations *ops,
452                       struct net80211_hw_info *hw);
453
454 /** Indicate receipt of a raw packet from the network interface. Takes
455     ownership of the iob. `signal' is signal strength in device
456     units. */
457 void net80211_rx(struct net80211_device *dev, struct io_buffer *iob,
458                  int signal);
459
460 /** Indicate an error in receiving a packet. Pass iob if you want it
461     freed. */
462 static inline void net80211_rx_err(struct net80211_device *dev,
463                                    struct io_buffer *iob, int rc) 
464 {
465         netdev_rx_err(dev->netdev, iob, rc);
466 }
467
468 /** Indicate the completed transmission of a packet passed to
469     (*transmit)(), successfully if rc == 0 and unsuccessfully if
470     not. In either case this function takes ownership of the iob. */
471 static inline void net80211_tx_complete(struct net80211_device *dev,
472                                         struct io_buffer *iob, int rc) 
473 {
474         netdev_tx_complete_err(dev->netdev, iob, rc);
475 }
476
477 /** Removes the registration of an 802.11 device. */
478 void net80211_unregister(struct net80211_device *dev);
479
480 /** Frees all memory allocated by the 802.11 layer for a device. */
481 void net80211_free(struct net80211_device *dev);
482
483 #endif