A Wireless LAN API for the Linux operating system.
This document is a part of the Linux Wireless LAN Howto. Please refer to it for details.
I decided to define a wireless API which would allow the user to manipulate any wireless networking device in a standard and uniform way. Of course, those devices are fundamentally different, so the standardisation would only be on the methods but not on the values (a Network ID is always a parameter that you may set and get and use to distinguish logical networks, but some devices might use 4 bits and others 16 bits, and the effect of a change may be immediate or delayed after a reconfiguration of the device...).
This interface would need to be flexible and extensible. The primary need was for device configuration, but wireless statistics and the development of wireless aware applications was desirable. I needed also something simple to implement and conform to the Linux standard to have something much easier to share and maintain. The interface would need to evolve with the apparition of new products and with specific needs.
I tried to be as generic as possible, but I was obliged to restrict myself on a specific set of devices. I focused on the Wireless LAN type of devices (indoor radio networks), which appears in the operating system as a normal network device. AX25 (Amateur Radio) devices are too specific and have already their own specific network stack and tools. I also ruled out cellular data (data over GSM and mobile phone) and medium and long distance wireless communications because their interface are quite different and they don't operate in the same way. InfraRed should be similar enough to Radio LANs to benefit from this interface (if someday an InfraRed network driver for Linux appears).
As it was only an extension to the current Linux networking interface, I decided to call it ``Wireless Extensions''. The words interface and API are too ambitious for this simple set of tools.
The kernel modifications have been included in the last Linux releases (from 2.0.30 and 2.1.17) and so the kernel now supports them. Users of release 1.2.13 may use a patch to add the support in their kernels. By default, the wireless extensions are disabled, and users need to enable the CONFIG_NET_RADIO option in the kernel configuration (this is the option which enables the choice of radio interfaces in the network driver list).
The tools are quite simple and so should be able to compile in any Linux system provided that the kernel supports wireless extensions.
The modifications of the wireless network drivers are probably the most important. Each driver needs to support wireless extensions and to perform the corresponding dialogue with the specific hardware. For now, only the Wavelan ISA and the Wavelan PCMCIA drivers support wireless extensions, but I'm confident that others will eventually follow. The modified Wavelan PCMCIA driver is available in the last pcmcia packages (from 2.9.1). The modified Wavelan ISA driver is available in the kernel (from 2.0.30 and 2.1.17).
The output looks like this :
<jean@tourrilhes>cat /proc/net/wireless Inter-|sta| Quality | Discarded packets face |tus|link level noise| nwid crypt misc eth2: f0 15. 24. 4. 181 0 0For each device, the following information is given :
The basic difference between Quality - link and Quality - level is that the first indicate how good the reception is (for example the percentage of correctly received packets) and the second how strong the signal is. The Quality - level is some directly measurable data that is likely to have the same signification across devices.
When the Quality values have been updated since the last read of the entry, a dot will follow that value (typically, it mean that a new measure has been made).
The name of the protocol is often the generic name of the device itself (for example ``Wavelan''). This is quite useful because these protocols are all incompatible. The apparition of standards such as 802.11 and HiperLan might help a bit in the future.
The encryption setting includes the key itself (up to 64 bits), the activation of encryption (on/off) and an optional argument (either the type of algorithm or the key number for multi key systems).
Without any argument, iwconfig gives the value of these parameters (and the content of /proc/net/wireless) :
<jean@tourrilhes>iwconfig lo no wireless extensions. eth1 no wireless extensions. eth2 Wavelan NWID:1234 Frequency:2.422GHz Sensitivity:4 Link quality:15/15 Signal level:22/63 Noise level:0/63 Rx invalid nwid:181 invalid crypt:0 invalid misc:0By giving a command line option, the user may change these parameters (if it is possible in the driver and if the user is root). For example, to change the frequency to 2.462 GHz and disable nwid checking on the device eth2, the user will do :
#iwconfig eth2 freq 2.462G nwid offThe user may also list the available frequencies for a specific device or the number of channels defined :
<jean@tourrilhes>iwconfig eth2 list_freq 10 channels ; available frequencies : 2.422GHz 2.425GHz 2.4305GHz 2.432GHz 2.442GHz 2.452GHz 2.46GHz 2.462GHz
iwspy accept IP address as well as hardware addresses (MAC). IP addresses will be converted to hardware addresses before being transmitted to the driver. No verification is made on the hardware address. On the command line, hardware addresses should be prefixed by the keyword hw :
#iwspy eth2 126.96.36.199 hw 08:00:0E:21:3A:1FThe tool accept the keyword ``+'' to add the new addresses at the end of the list :
#iwspy eth2 + hw 08:00:0E:2A:26:FATo display the list of address :
<jean@tourrilhes>iwspy eth2 08:00:0E:21:D7:4E : Quality 15 ; Signal 29 ; Noise 0 (updated) 08:00:0E:21:3A:1F : Quality 0 ; Signal 0 ; Noise 0 08:00:0E:2A:26:FA : Quality 0 ; Signal 0 ; Noise 0The (updated) indication show that we have received a packet since we set the address in the driver. We haven't received anything from the second and third address (this explain why the values are 0). A ping to those address should solve the problem.
The number of addresses is limited to 8, because each address slow down the driver (it increases the processing for each received packets).
All the wireless interface (types and constants) is defined in the file /usr/include/linux/wireless.h. This is the central piece of the wireless extension.
The Linux networking stack uses a structure (struct device) to keep track of each device in the system. The first part of it is standardised, and contains parameters (for example the base I/O address and the IP address of the device) and callbacks (the procedure to start the device, to send a packet...).
I've added to this structure another standard callback (get_wireless_stats) to get the wireless statistics that /proc/net/wireless needs. When the /proc entry is read, it calls this callback for all the devices present in the system and display the information it gets. If a device doesn't define this callback, it is ignored.
When called, the get_wireless_stats callback returns a structure (struct iw_statistics) containing all the fields that will be displayed by the /proc entry. This structure is of course defined in the file /usr/include/linux/wireless.h.
For example, to change the IP address on device eth2, a program (like ifconfig) would make an ioctl call with the following parameters : ``eth2'', SIOCSIFADDR, new address. The structure defining the parameters layout may be found in /usr/include/linux/if.h and the ioctl call (the constant SIOCSIFADDR) is defined in /usr/include/linux/sockios.h.
For the wireless extensions, I've defined a new set of ioctl calls (for example SIOCSIWFREQ to change the frequency). I've also defined the parameters to those calls (see /usr/include/linux/wireless.h). In fact those new calls map closely to the functionality offered by the wireless tools.
There is another popular way to set parameters in a network driver in Linux, which is initialisation parameters (either passed on the kernel command line or at module initialisation). This method has the disadvantage that the parameters may only be set (and not read) and only at initialisation time, which offers much less flexibility than the current solution. The other advantage of ioctl is that it is a programming interface (and not only a user interface), so any program (such as a Mobile IP implementation) may manipulate them directly.
Also the implementation of wireless extensions in some case is not that easy. For example, the code to change the frequency in the Wavelan driver is quite large and complex.
Linux Wireless LAN Howto -
Converted to html from Frame Maker - 18 March 97
Updated 23 January 97
Copyright © 1996-2004 Jean Tourrilhes
Project hosted and sponsored by :