
Intel PRO/Wireless 2100 (IPW2100)
Copyright (C) 2004 - Intel Corporation
----------------------------------------------------------------------


 --    THIS IS OUT OF DATE AND NEEDS TO BE UPDATED  --





Overview
===== ====  ===   ==    =     =      =
This document outlines the general design and functional breakdown of 
the ipw2100 driver for the IPW2100 802.11b LAN card.

There are a few key capabilities that differentiate this driver from 
others in the Linux kernel.

1) Advanced power management capabilities
2) Optional radio kill switch (RF KILL)
3) Non-resident firmware

Each of these features is briefly described here, as well as the 
interaction of those features with the rest of the Linux system


Advanced Power Management Capabilities
----- ----  ---   --    -      -      -        -

The IPW2100 has several different power levels that can be configured 
by the user or system software.  These are exposed to user space 
through private members of the wireless extension interface.


Optional radio kill switch (RF KILL)
----- ----  ---   --    -     -       -        -
On some OEM systems that provide the IPW2100, a radio kill 
switch (RF KILL) has been implemented.  This kill switch has the 
ability to physically disable the radio on the IPW2100.  Notification 
of the state of this switch is sent to the driver through the 
IPW2100's firmware.

With some solutions this switch is a physical switch.  On other 
systems it is implemented through a keyboard button or sequence and 
software that can then change the state of the switch.

In the event that the switch state is controlled via software, the 
IPW2100 driver must have the capability to control that switch such 
that a user space program can then be linked to the button or keyboard
sequence and invoke the appropriate call.

For now, this capability is implemented through a private interface 
of the wireless extension.  However, each specific OEM product may 
have a different method of toggling the RF KILL switch.  This is 
important to realize as some systems boot with the RF KILL enabled 
(meaning the radio is physically disabled).  In these situations, 
without the correct software there is no way for the IPW2100 driver 
to enable the radio.

At the time of this writing support has been tested on the following:

Manufacturer		Model		Mode
Averatec		5100P		GPIO


Non-resident Firmware
----- ----  ---   --    -     -      -       -
The IPW2100 contains a run-time programmable firmware responsible for 
controlling the internal MAC and the Radio.  The firmware exposes an 
API that is then used by the Linux driver to control those devices.

Due to the size of the firmware binary image and the fact that once 
loaded into the firmware there is no reason to keep the image resident
in memory, the firmware is loaded into the IPW2100 driver through a 
user space daemon.

The typical scenario is to initialize the IPW2100 and then load the 
firmware. In the event that the card has to be re-initialized the 
firmware must also be reloaded.  As a result, the user space daemon
can not simply load the firmware and go away.  It must listen for the 
driver to notify it to reload the image.


Trasmit and Receive
===== ====  ===   ==    =     =      =
The IPW2100 performs Tx/Rx operations between the driver and firmware
via two circular queues in a shared region of memory.  There is one
queue each for the Tx and Rx.

The Tx queue is used for sending both network packets as well as
command packets used to control the firmware.

Trasmit Part 1: Tx Data 
----- ----  ---   --    -     -      -       -
When a packet is provided to the driver from the kernel (via the 
net_device's hard_start_xmit callback function ipw2100_tx) the driver
places the packet onto an internal queue of pending Tx packets.  
Control is then returned to the kernel.

When the Tx packet is placed in the pending queue a check is first
made to see if there is room in the driver/firmware shared Tx data 
queue.  If so, information pertaining to the packet is entered into a
Transfer Buffer Descriptor (TBD) and placed in the shared Tx queue.
If not, the packet remains in the pending queue until space is 
available.

At this point, the reference to the Tx packet is moved from the Tx
pending queue and into a Firmware queue used for tracking both Data and 
Command Tx operations to the firmware.

The reason for this second queue is to be able to perform cleanup of
allocated kernel structures (primarily SKBs) once the firmware has
finished using the data.

This is probably a good place to briefly describe the shared data
queue.

The Tx data queue is a circular list of TBD entries.  There are two
indexes into this list: the read index owned by the firmware, and the
write index owned by the driver.

When a packet is placed into the shared queue, it is placed into
the slot identified by the write index, and the write index is
incremented (wrapping if necessary).  Once the write index has moved
forward, the firmware is informed via the kickoff of a DMA operation.

When a packet has been used by the firmware it will trigger an 
interrupt and provide information indicating that a packet was
read.

At this point, the driver must come in and determine how far the 
firmware has read in the TBD queue.  All entries between the last
recorded "used" index and the current read index are free to be
restored.

Care must be taken not to overwrite used but not freed TBD entries
as new entries are placed into the queue.  








init
- register in proc
- register driver w/ pci

pci_init

card_init_pt1
- send FW dump request to userspace
- wait for FW update

fw_update
- if in card_init_pt1 then continue card_init_pt2 after FW dump

on_fw_hang
- card_init_pt1

on_tx
- decrypt
- defrag
- put in buffer

on_rx
- fragment
- encrypt
- put in buffer

