Wireless Extensions for Linux

---

Jean Tourrilhes

23 January 97

A Wireless LAN API for the Linux operating system.

1 Introduction

The purpose of this document is to give an overview of the WirelessExtensions. The first part will explain the reason of thisdevelopment and the generals ideas behind this work. Then, we willgive the current status of the development. The third part willexplore the user interface. We will finish by some implementationdetails and the possible evolution of the Wireless Extensions.

This document is a part of the LinuxWireless LAN Howto. Please refer to it for details.

2 Philosophy & Goal

It all started when I tried to install a Wavelan network on Linux computers. I was having a ISA and a PCMCIA versions ofthe Wavelan, and the two drivers were using totally different methodsfor the setup and collection of statistics (and in fact fairlyincomplete...). As my small hard disks didn't allow me to reboot toDOS to set up those missing parameters, I started to modify the drivercode.

I decided to define a wireless API which would allow the user tomanipulate any wireless networking device in a standard anduniform way. Of course, those devices are fundamentallydifferent, so the standardisation would only be on the methods but noton the values (a Network ID is always a parameter that you may set andget and use to distinguish logical networks, but some devices mightuse 4 bits and others 16 bits, and the effect of a change may beimmediate or delayed after a reconfiguration of the device...).

This interface would need to be flexible and extensible. The primaryneed was for device configuration, but wirelessstatistics and the development of wireless awareapplications was desirable. I needed also something simple toimplement and conform to the Linux standard to have something mucheasier to share and maintain. The interface would need to evolve withthe apparition of new products and with specific needs.

I tried to be as generic as possible, but I was obliged to restrictmyself on a specific set of devices. I focused on the WirelessLAN type of devices (indoor radio networks), which appears in theoperating system as a normal network device. AX25 (AmateurRadio) devices are too specific and have already their own specificnetwork stack and tools. I also ruled out cellular data (dataover GSM and mobile phone) and medium and long distance wirelesscommunications because their interface are quite different and theydon't operate in the same way. InfraRed should be similarenough to Radio LANs to benefit from this interface (if someday anInfraRed 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 andAPI are too ambitious for this simple set of tools.

3 Availability

The wireless extensions have been implemented in three complementaryparts. The first part is the user interface, a set of tools tomanipulate those extensions. The second part is a modification of theLinux kernel to support and define the extensions. The third part isthe hardware interface and is implemented in each network driveritself to map the extensions to the actual hardware manipulations.

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 ofrelease 1.2.13 may use a patch to add the support in their kernels. Bydefault, the wireless extensions are disabled, and users need toenable the CONFIG_NET_RADIO option in the kernel configuration(this is the option which enables the choice of radio interfaces inthe network driver list).

The tools are quite simple and so should be able to compile in anyLinux system provided that the kernel supports wireless extensions.

The modifications of the wireless network drivers are probably themost important. Each driver needs to support wireless extensions andto perform the corresponding dialogue with the specific hardware. Fornow, only the Wavelan ISA and the Wavelan PCMCIA drivers supportwireless extensions, but I'm confident that others will eventuallyfollow. The modified Wavelan PCMCIA driver is available in the lastpcmcia packages (from 2.9.1). The modified Wavelan ISA driver isavailable in the kernel (from 2.0.30 and 2.1.17).

4 User interface and tools

The user interface is composed of 3 programs and a /procentry. The main goal of the Wireless Extension development effortwasn't the user interface, so this interface is quite basic.

4.1 /proc/net/wireless

This is a /proc entry. /proc is a pseudo file systemgiving information and statistics about the current system, which isusually located in /proc. These entries act as files, so a cat on them will give the required information. /proc/net/wireless is designed to give some wireless specificstatistics on each wireless interface in the system. This entry is infact a clone of /proc/net/dev which gives the standard driverstatistics.

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     0

For each device, the following information is given :

• Status : Its current state. This is a device dependent information.
• Quality - link : general quality of the reception.
• Quality - level : signal strength at the receiver.
• Quality - noise : silence level (no packet) at the receiver.
• Discarded - nwid : number of discarded packets due to invalid network id.
• Discarded - crypt : number of packet unable to decrypt.
• Discarded - misc : unused (for now).

These informations allow the user to have a better feedback about hissystem. A high value of Discarded - nwid packet might indicatea nwid configuration problem or an adjacent network. The Quality -level might help him to track shadow areas.

The basic difference between Quality - link and Quality -level is that the first indicate how good the reception is (forexample the percentage of correctly received packets) and the secondhow strong the signal is. The Quality - level is some directlymeasurable data that is likely to have the same signification acrossdevices.

When the Quality values have been updated since the last readof the entry, a dot will follow that value (typically, it mean that anew measure has been made).

4.2 iwconfig

This tool is designed to configure all the wireless specificparameters of the driver and the hardware. This is a clone of ifconfig used for standard device configuration. The followingparameters are available :

• freq or channel : the frequency or the channel sequence.
• nwid : network id or domain, to distinguish different logical networks.
• the name of the ``protocol'' used on the air.
• sens : this is the signal level threshold to trigger packet reception (sensitivity).
• enc : the encryption or scrambling key used.

The frequency or channel parameter is the physical separation betweennetworks (the keyword freq and channel aresynonymous). For frequency hopping devices, it might be the hoppingpattern. On the other hand, the nwid is only a logical (virtual)separation between networks which might be on the same frequency.

The name of the protocol is often the generic name of the deviceitself (for example ``Wavelan''). This is quite useful becausethese protocols are all incompatible. The apparition of standards suchas 802.11 and HiperLan might help a bit in the future.

The encryption setting includes the key itself (up to 64 bits), theactivation of encryption (on/off) and an optionalargument (either the type of algorithm or the key number for multi keysystems).

Without any argument, iwconfig gives the value of theseparameters (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:0

By giving a command line option, the user may change these parameters(if it is possible in the driver and if the user is root). Forexample, to change the frequency to 2.462 GHz and disable nwidchecking on the device eth2, the user will do :

#iwconfig eth2 freq 2.462G nwid off

The user may also list the available frequencies for a specific deviceor 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

4.3 iwspy

iwspy was designed to test the Mobile IP support. Itallows the user to set a list of network addresses in the driver. Thedriver will gather quality information for each of those addresses(updated each time it receives a packet from that address). The toolallows the user to display the information associated with eachaddress in the list.

iwspy accept IP address as well as hardware addresses (MAC). IPaddresses will be converted to hardware addresses before beingtransmitted to the driver. No verification is made on the hardwareaddress. On the command line, hardware addresses should be prefixed bythe keyword hw :

#iwspy eth2 15.144.104.4 hw 08:00:0E:21:3A:1F

The tool accept the keyword ``+'' to add the new addresses at the endof the list :

#iwspy eth2 + hw 08:00:0E:2A:26:FA

To 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 0

The (updated) indication show that we have received a packetsince we set the address in the driver. We haven't received anythingfrom the second and third address (this explain why the values are0). A ping to those address should solve the problem.

The number of addresses is limited to 8, because each address slowdown the driver (it increases the processing for each receivedpackets).

4.4 iwpriv

iwpriv is some experimental support for device specificextensions. Some drivers (like the Wavelan one) might define someextra parameters or functionality, iwpriv is used to manipulatethose.

5 Driver interface & programming issues

The implementation of the wireless extensions was designed to minimisethe number of changes in the kernel and to have a simple andextensible solution.

All the wireless interface (types and constants) is defined in thefile /usr/include/linux/wireless.h. This is the central pieceof the wireless extension.

5.1 /proc/net/wireless

This /proc entry is a clone of the /proc/net/dev entryand has been implemented in exactly the same way.

The Linux networking stack uses a structure (struct device) tokeep track of each device in the system. The first part of it isstandardised, and contains parameters (for example the base I/Oaddress and the IP address of the device) and callbacks (the procedureto 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 anddisplay the information it gets. If a device doesn't define thiscallback, it is ignored.

When called, the get_wireless_stats callback returns astructure (struct iw_statistics) containing all the fields thatwill be displayed by the /proc entry. This structure is ofcourse defined in the file /usr/include/linux/wireless.h.

5.2 ioctl

The usual method in Unix to set and get parameters from a networkdevice is through ioctl. Ioctl are usually operations performedon a file descriptor, but they also apply on network sockets. Theioctl is a kernel system call. The arguments of the ioctl define theoperations to be done, the parameters of these operations and thedevice they applies to.

For example, to change the IP address on device eth2, a program(like ifconfig) would make an ioctl call with the followingparameters : ``eth2'', SIOCSIFADDR, new address. The structuredefining the parameters layout may be found in/usr/include/linux/if.h and the ioctl call (the constantSIOCSIFADDR) 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 alsodefined the parameters to those calls (see/usr/include/linux/wireless.h). In fact those new calls mapclosely to the functionality offered by the wireless tools.

There is another popular way to set parameters in a network driver inLinux, which is initialisation parameters (either passed on the kernelcommand line or at module initialisation). This method has thedisadvantage that the parameters may only be set (and not read) andonly at initialisation time, which offers much less flexibility thanthe current solution. The other advantage of ioctl is that it is aprogramming interface (and not only a user interface), so any program(such as a Mobile IP implementation) may manipulate them directly.

5.3 More details

For people who needs more details on the actual implementation, thelist of ioctl calls or the parameters definitions, the ultimatereference is the source code. The file /usr/include/linux/wireless.h defines all the necessarypieces. The wireless tools offer some good examples on how to use theioctl calls. To know how the wireless extensions are used on thedriver side, the Wavelan driver source will answer most questions.

6 Areas of improvement

6.1 Other drivers

For now, only the Wavelan driver supports the wireless extensions. Theimplementation of the Wireless Extensions in other wireless networkdrivers might help to validate the Wireless Extensions genericity andto refine its definition. The problem is that quite few wirelessdevices have Linux drivers available.

Also the implementation of wireless extensions in some case is notthat easy. For example, the code to change the frequency in theWavelan driver is quite large and complex.

6.2 Users tools

They should be extended and refined. We could also imagine thedevelopment of a graphical interface (for example to have a smallgraph bar like for battery charge and system load).

6.3 Wireless Aware applications

The development of wireless aware applications will allow todemonstrate the concept and to expand the wireless extensions with theneeds of those applications. Mobile IP seems an obvious target.