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