drivers/staging/rtl8192su/ieee80211/readme

   1 What this layer should do
   2
   3 - It mantain the old mechanism as alternative, so the
   4   ipw2100 driver works with really few changes.
   5 - Encapsulate / Decapsulate ieee80211 packet
   6 - Handle fragmentation
   7 - Optionally provide an alterantive mechanism for netif queue stop/wake,
   8   so that the ieee80211 layer will pass one fragment per time instead of
   9   one txb struct per time. so the driver can stop the queue in the middle
  10   of a packet.
  11 - Provide two different TX interfaces for cards that can handle management
  12   frames on one HW queue, and data on another, and for cards that have only
  13   one HW queue  (the latter untested and very, very rough).
  14 - Optionally provide the logic for handling IBSS/MASTER/MONITOR/BSS modes
  15   and for the channel, essid and wap get/set wireless extension requests.
  16   so that the driver has only to change channel when the ieee stack tell it.
  17 - Optionally provide a scanning mechanism so that the driver has not to
  18   worry about this, just implement the set channel calback and pass
  19   frames to the upper layer
  20 - Optionally provide the bss client protocol handshaking (just with open
  21   authentication)
  22 - Optionally provide the probe request send mechanism
  23 - Optionally provide the bss master mode logic to handle association
  24   protocol (only open authentication) and probe responses.
  25 - SW wep encryption (with open authentication)
  26 - It collects some stats
  27 - It provides beacons to the card when it ask for them
  28
  29 What this layer doesn't do (yet)
  30 - Perform shared authentication
  31 - Have full support for master mode (the AP should loop back in the air
  32   frames from an associated client to another. This could be done easily
  33   with few lines of code, and it is done in my previous version of the
  34   stach, but a table of association must be keept and a disassociation
  35   policy must be decided and implemented.
  36 - Handle cleanly the full ieee 802.11 protocol. In AP mode it never
  37   disassociate clients, and it is really prone to always allow access.
  38   In bss client mode it is a bit rough with AP deauth and disassoc requests.
  39 - It has not any entry point to view the collected stats.
  40 - Altought it takes care of the card supported rates in the management frame
  41   it sends, support for rate changing on TXed packet is not complete.
  42 - Give up once associated in bss client mode (it never detect a
  43   signal loss condition to disassociate and restart scanning)
  44 - Provide a mechanism for enabling the TX in monitor mode, so
  45   userspace programs can TX raw packets.
  46 - Provide a mechanism for cards that need that the SW take care of beacon
  47   TX completely, in sense that the SW has to enqueue by itself beacons
  48   to the card so it TX them (if any...)
  49 APIs
  50
  51 Callback functions in the original stack has been mantained.
  52 following has been added (from ieee80211.h)
  53
  54         /* Softmac-generated frames (mamagement) are TXed via this
  55          * callback if the flag IEEE_SOFTMAC_SINGLE_QUEUE is
  56          * not set. As some cards may have different HW queues that
  57          * one might want to use for data and management frames
  58          * the option to have two callbacks might be useful.
  59          * This fucntion can't sleep.
  60          */
  61         int (*softmac_hard_start_xmit)(struct sk_buff *skb,
  62                                struct net_device *dev);
  63
  64         /* used instead of hard_start_xmit (not softmac_hard_start_xmit)
  65          * if the IEEE_SOFTMAC_TX_QUEUE feature is used to TX data
  66          * frames. I the option IEEE_SOFTMAC_SINGLE_QUEUE is also set
  67          * then also management frames are sent via this callback.
  68          * This function can't sleep.
  69          */
  70         void (*softmac_data_hard_start_xmit)(struct sk_buff *skb,
  71                                struct net_device *dev);
  72
  73         /* stops the HW queue for DATA frames. Useful to avoid
  74          * waste time to TX data frame when we are reassociating
  75          * This function can sleep.
  76          */
  77         void (*data_hard_stop)(struct net_device *dev);
  78
  79         /* OK this is complementar to data_poll_hard_stop */
  80         void (*data_hard_resume)(struct net_device *dev);
  81
  82         /* ask to the driver to retune the radio .
  83          * This function can sleep. the driver should ensure
  84          * the radio has been swithced before return.
  85          */
  86         void (*set_chan)(struct net_device *dev,short ch);
  87
  88         /* These are not used if the ieee stack takes care of
  89          * scanning (IEEE_SOFTMAC_SCAN feature set).
  90          * In this case only the set_chan is used.
  91          *
  92          * The syncro version is similar to the start_scan but
  93          * does not return until all channels has been scanned.
  94          * this is called in user context and should sleep,
  95          * it is called in a work_queue when swithcing to ad-hoc mode
  96          * or in behalf of iwlist scan when the card is associated
  97          * and root user ask for a scan.
  98          * the fucntion stop_scan should stop both the syncro and
  99          * background scanning and can sleep.
 100          * The fucntion start_scan should initiate the background
 101          * scanning and can't sleep.
 102          */
 103         void (*scan_syncro)(struct net_device *dev);
 104         void (*start_scan)(struct net_device *dev);
 105         void (*stop_scan)(struct net_device *dev);
 106
 107         /* indicate the driver that the link state is changed
 108          * for example it may indicate the card is associated now.
 109          * Driver might be interested in this to apply RX filter
 110          * rules or simply light the LINK led
 111          */
 112         void (*link_change)(struct net_device *dev);
 113
 114 Functions hard_data_[resume/stop] are optional and should not be used
 115 if the driver decides to uses data+management frames enqueue in a
 116 single HQ queue (thus using just the softmac_hard_data_start_xmit
 117 callback).
 118
 119 Function that the driver can use are:
 120
 121 ieee80211_get_beacon             - this is called by the driver when
 122                                    the HW needs a beacon.
 123 ieee80211_softmac_start_protocol - this should normally be called in the
 124                                    driver open function
 125 ieee80211_softmac_stop_protocol  - the opposite of the above
 126 ieee80211_wake_queue             - this is similar to netif_wake_queue
 127 ieee80211_reset_queue            - this throw away fragments pending(if any)
 128 ieee80211_stop_queue             - this is similar to netif_stop_queue
 129
 130
 131 known BUGS:
 132 - When performing syncro scan (possiblily when swithcing to ad-hoc mode
 133   and when running iwlist scan when associated) there is still an odd
 134   behaviour.. I have not looked in this more accurately (yet).
 135
 136 locking:
 137 locking is done by means of three structures.
 138 1- ieee->lock (by means of spin_[un]lock_irq[save/restore]
 139 2- ieee->wx_sem
 140 3- ieee->scan_sem
 141
 142 the lock 1 is what protect most of the critical sections in the ieee stack.
 143 the lock 2 is used to avoid that more than one of the SET wireless extension
 144 handlers (as well as start/stop protocol function) are running at the same time.
 145 the lock 1 is used when we need to modify or read the shared data in the wx handlers.
 146 In other words the lock 2 will prevent one SET action will run across another SET
 147 action (by make sleep the 2nd one) but allow GET actions, while the lock 1
 148 make atomic those little shared data access in both GET and SET operation.
 149 So get operation will be never be delayed really: they will never sleep..
 150 Furthermore in the top of some SET operations a flag is set before acquiring
 151 the lock. This is an help to make the previous running SET operation to
 152 finish faster if needed (just in case the second one will totally undo the
 153 first, so there is not need to complete the 1st really.. ).
 154 The background scanning mechaninsm is protected by the lock 1 except for the
 155 workqueue. this wq is here just to let the set_chan callback sleep (I thinked it
 156 might be appreciated by USB network card driver developer). In this case the lock 3
 157 take its turn.
 158 Thus the stop function needs both the locks.
 159 Funny in the syncro scan the lock 2 play its role (as both the syncro_scan
 160 function and the stop scan function are called with this semaphore held).
 161
 162