drivers/net/wireless/libertas/README

   1 ================================================================================
   2                         README for USB8388
   3
   4  (c) Copyright © 2003-2006, Marvell International Ltd.
   5  All Rights Reserved
   6
   7  This software file (the "File") is distributed by Marvell International
   8  Ltd. under the terms of the GNU General Public License Version 2, June 1991
   9  (the "License").  You may use, redistribute and/or modify this File in
  10  accordance with the terms and conditions of the License, a copy of which
  11  is available along with the File in the license.txt file or by writing to
  12  the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  13  02111-1307 or on the worldwide web at http://www.gnu.org/licenses/gpl.txt.
  14
  15  THE FILE IS DISTRIBUTED AS-IS, WITHOUT WARRANTY OF ANY KIND, AND THE
  16  IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE
  17  ARE EXPRESSLY DISCLAIMED.  The License provides additional details about
  18  this warranty disclaimer.
  19 ================================================================================
  20
  21 =====================
  22 DRIVER LOADING
  23 =====================
  24
  25         o. Copy the firmware image (e.g. usb8388.bin) to /lib/firmware/
  26
  27         o. Load driver by using the following command:
  28
  29                 insmod usb8388.ko [fw_name=usb8388.bin]
  30
  31 =====================
  32 IWPRIV COMMAND
  33 =====================
  34
  35 NAME
  36         This manual describes the usage of private commands used in Marvell WLAN
  37         Linux Driver. All the commands available in Wlanconfig will not be available
  38         in the iwpriv.
  39
  40 SYNOPSIS
  41         iwpriv <ethX> <command> [sub-command] ...
  42
  43         iwpriv ethX setregioncode <n>
  44         iwpriv ethX getregioncode
  45
  46 Version 5 Command:
  47         iwpriv ethX ledgpio <n>
  48
  49 BT Commands:
  50         The blinding table (BT) contains a list of mac addresses that will be,
  51         by default, ignored by the firmware. It is also possible to invert this
  52         behavior so that we will ignore all traffic except for the portion
  53         coming from mac addresess in the list. It is primarily used for
  54         debugging and testing networks.  It can be edited and inspected with
  55         the following commands:
  56
  57         iwpriv ethX bt_reset
  58         iwpriv ethX bt_add <mac_address>
  59         iwpriv ethX bt_del <mac_address>
  60         iwpriv ethX bt_list <id>
  61         iwpriv ethX bt_get_invert <n>
  62         iwpriv ethX bt_set_invert <n>
  63
  64 FWT Commands:
  65         The forwarding table (FWT) is a feature used to manage mesh network
  66         routing in the firmware.  The FWT is essentially a routing table that
  67         associates a destination mac address (da) with a next hop receiver
  68         address (ra).  The FWT can be inspected and edited with the following
  69         iwpriv commands, which are described in greater detail below.
  70         Eventually, the table will be automatically maintained by a custom
  71         routing protocol.
  72
  73         NOTE: FWT commands replace the previous DFT commands.  What were the DFT
  74         commands?, you might ask.  They were an earlier API to the firmware that
  75         implemented a simple MAC-layer forwarding mechanism.  In the unlikely
  76         event that you were using these commands, you must migrate to the new
  77         FWT commands which can be used to achieve the same functionality.
  78
  79         iwpriv ethX fwt_add [parameters]
  80         iwpriv ethX fwt_del [parameters]
  81         iwpriv ethX fwt_lookup [parameters]
  82         iwpriv ethX fwt_list [parameters]
  83         iwpriv ethX fwt_list_route [parameters]
  84         iwpriv ethX fwt_list_neigh [parameters]
  85         iwpriv ethX fwt_reset [parameters]
  86         iwpriv ethX fwt_cleanup
  87         iwpriv ethX fwt_time
  88
  89 MESH Commands:
  90
  91         The MESH commands are used to configure various features of the mesh
  92         routing protocol.  The following commands are supported:
  93
  94         iwpriv ethX mesh_get_ttl
  95         iwpriv ethX mesh_set_ttl ttl
  96
  97 DESCRIPTION
  98         Those commands are used to send additional commands to the Marvell WLAN
  99         card via the Linux device driver.
 100
 101         The ethX parameter specifies the network device that is to be used to
 102                 perform this command on. it could be eth0, eth1 etc.
 103
 104 setregioncode
 105         This command is used to set the region code in the station.
 106         where value is 'region code' for various regions like
 107         USA FCC, Canada IC, Spain, France, Europe ETSI, Japan ...
 108
 109         Usage:
 110                 iwpriv ethX setregioncode 0x10: set region code to USA (0x10).
 111
 112 getregioncode
 113         This command is used to get the region code information set in the
 114         station.
 115
 116 ledgpio
 117         This command is used to set/get LEDs.
 118
 119         iwpriv ethX ledgpio <LEDs>
 120                 will set the corresponding LED for the GPIO Line.
 121
 122         iwpriv ethX ledgpio
 123                 will give u which LEDs are Enabled.
 124
 125         Usage:
 126                 iwpriv eth1 ledgpio 1 0 2 1 3 4
 127                         will enable
 128                         LED 1 -> GPIO 0
 129                         LED 2 -> GPIO 1
 130                         LED 3 -> GPIO 4
 131
 132                 iwpriv eth1 ledgpio
 133                         shows LED information in the format as mentioned above.
 134
 135         Note: LED0 is invalid
 136         Note: Maximum Number of LEDs are 16.
 137
 138 fwt_add
 139         This command is used to insert an entry into the FWT table. The list of
 140         parameters must follow the following structure:
 141
 142         iwpriv ethX fwt_add da ra [metric dir rate ssn dsn hopcount ttl expiration sleepmode snr]
 143
 144         The parameters between brackets are optional, but they must appear in
 145         the order specified.  For example, if you want to specify the metric,
 146         you must also specify the dir, ssn, and dsn but you need not specify the
 147         hopcount, expiration, sleepmode, or snr.  Any unspecified parameters
 148         will be assigned the defaults specified below.
 149
 150         The different parameters are:-
 151                 da              -- DA MAC address in the form 00:11:22:33:44:55
 152                 ra              -- RA MAC address in the form 00:11:22:33:44:55
 153                 metric          -- route metric (cost: smaller-metric routes are
 154                                    preferred, default is 0)
 155                 dir             -- direction (1 for direct, 0 for reverse,
 156                                    default is 1)
 157                 rate            -- data rate used for transmission to the RA,
 158                                    as specified for the rateadapt command,
 159                                    default is 3 (11Mbps)
 160                 ssn             -- Source Sequence Number (time at the RA for
 161                                    reverse routes.  Default is 0)
 162                 dsn             -- Destination Sequence Number (time at the DA
 163                                    for direct routes.  Default is 0)
 164                 hopcount        -- hop count (currently unused, default is 0)
 165                 ttl             -- TTL (Only used in reverse entries)
 166                 expiration      -- entry expiration (in ticks, where a tick is
 167                                    1024us, or ~ 1ms. Use 0 for an indefinite
 168                                    entry, default is 0)
 169                 sleepmode       -- RA's sleep mode (currently unused, default is
 170                                    0)
 171                 snr             -- SNR in the link to RA (currently unused,
 172                                    default is 0)
 173
 174         The command does not return anything.
 175
 176 fwt_del
 177         This command is used to remove an entry to the FWT table. The list of
 178         parameters must follow the following structure:
 179
 180                 iwpriv ethX fwt_del da ra [dir]
 181
 182         where the different parameters are:-
 183                 da              -- DA MAC address (in the form "00:11:22:33:44:55")
 184                 ra              -- RA MAC address (in the form "00:11:22:33:44:55")
 185                 dir             -- direction (1 for direct, 0 for reverse,
 186                                    default is 1)
 187
 188         The command does not return anything.
 189
 190 fwt_lookup
 191         This command is used to get the best route in the FWT table to a given
 192         host. The only parameter is the MAC address of the host that is being
 193         looked for.
 194
 195                 iwpriv ethX fwt_lookup da
 196
 197         where:-
 198                 da              -- DA MAC address (in the form "00:11:22:33:44:55")
 199
 200         The command returns an output string identical to the one returned by
 201         fwt_list described below.
 202
 203
 204 fwt_list
 205         This command is used to list a route from the FWT table. The only
 206         parameter is the index into the table. If you want to list all the
 207         routes in a table, start with index=0, and keep listing until you get a
 208         "(null)" string.  Note that the indicies may change as the fwt is
 209         updated.  It is expected that most users will not use fwt_list directly,
 210         but that a utility similar to the traditional route command will be used
 211         to invoke fwt_list over and over.
 212
 213                 iwpriv ethX fwt_list index
 214
 215         The output is a string of the following form:
 216
 217                 da ra valid metric dir rate ssn dsn hopcount ttl expiration
 218                 sleepmode snr precursor
 219
 220         where the different fields are:-
 221                 da              -- DA MAC address (in the form "00:11:22:33:44:55")
 222                 ra              -- RA MAC address (in the form "00:11:22:33:44:55")
 223                 valid           -- whether the route is valid (0 if not valid)
 224                 metric          -- route metric (cost: smaller-metric routes are preferred)
 225                 dir             -- direction (1 for direct, 0 for reverse)
 226                 rate            -- data rate used for transmission to the RA,
 227                                    as specified for the rateadapt command
 228                 ssn             -- Source Sequence Number (time at the RA for reverse routes)
 229                 dsn             -- Destination Sequence Number (time at the DA for direct routes)
 230                 hopcount        -- hop count (currently unused)
 231                 ttl             -- TTL (only used in reverse entries)
 232                 expiration      -- entry expiration (in ticks, where a tick is 1024us, or ~ 1ms. Use 0 for an indefinite entry)
 233                 sleepmode       -- RA's sleep mode (currently unused)
 234                 snr             -- SNR in the link to RA (currently unused)
 235                 precursor       -- predecessor in direct routes
 236
 237 fwt_list_route
 238         This command is equivalent to fwt_list.
 239
 240 fwt_list_neigh
 241         This command is used to list a neighbor from the FWT table. The only
 242         parameter is the neighbor ID. If you want to list all the neighbors in a
 243         table, start with nid=0, and keep incrementing nid until you get a
 244         "(null)" string.  Note that the nid from a fwt_list_route command can be
 245         used as an input to this command.  Also note that this command is meant
 246         mostly for debugging.  It is expected that users will use fwt_lookup.
 247         One important reason for this is that the neighbor id may change as the
 248         neighbor table is altered.
 249
 250                 iwpriv ethX fwt_list_neigh nid
 251
 252         The output is a string of the following form:
 253
 254                 ra sleepmode snr references
 255
 256         where the different fields are:-
 257                 ra              -- RA MAC address (in the form "00:11:22:33:44:55")
 258                 sleepmode       -- RA's sleep mode (currently unused)
 259                 snr             -- SNR in the link to RA (currently unused)
 260                 references      -- RA's reference counter
 261
 262 fwt_reset
 263         This command is used to reset the FWT table, getting rid of all the
 264         entries. There are no input parameters.
 265
 266                 iwpriv ethX fwt_reset
 267
 268         The command does not return anything.
 269
 270 fwt_cleanup
 271         This command is used to perform user-based garbage recollection. The
 272         FWT table is checked, and all the entries that are expired or invalid
 273         are cleaned. Note that this is exported to the driver for debugging
 274         purposes, as garbage collection is also fired by the firmware when in
 275         space problems. There are no input parameters.
 276
 277                 iwpriv ethX fwt_cleanup
 278
 279         The command does returns the number of invalid/expired routes deleted.
 280
 281 fwt_time
 282         This command returns a card's internal time representation.  It is this
 283         time that is used to represent the expiration times of FWT entries.  The
 284         number is not consistent from card to card; it is simply a timer count.
 285         The fwt_time command is used to inspect the timer so that expiration
 286         times reported by fwt_list can be properly interpreted.
 287
 288                 iwpriv ethX fwt_time
 289
 290 mesh_get_ttl
 291
 292         The mesh ttl is the number of hops a mesh packet can traverse before it
 293         is dropped.  This parameter is used to prevent infinite loops in the
 294         mesh network.  The value returned by this function is the ttl assigned
 295         to all mesh packets.  Currently there is no way to control the ttl on a
 296         per packet or per socket basis.
 297
 298         iwpriv ethX mesh_get_ttl
 299
 300 mesh_set_ttl ttl
 301
 302         Set the ttl.  The argument must be between 0 and 255.
 303
 304         iwpriv ethX mesh_set_ttl <ttl>
 305
 306 =========================
 307 ETHTOOL
 308 =========================
 309
 310
 311 Use the -i option to retrieve version information from the driver.
 312
 313 # ethtool -i eth0
 314 driver: libertas
 315 version: COMM-USB8388-318.p4
 316 firmware-version: 5.110.7
 317 bus-info:
 318
 319 Use the -e option to read the EEPROM contents of the card.
 320
 321         Usage:
 322         ethtool -e ethX [raw on|off] [offset N] [length N]
 323
 324        -e     retrieves and prints an EEPROM dump for the  specified  ethernet
 325               device.   When raw is enabled, then it dumps the raw EEPROM data
 326               to stdout. The length and offset parameters allow  dumping  cer-
 327               tain portions of the EEPROM.  Default is to dump the entire EEP-
 328               ROM.
 329
 330 # ethtool -e eth0 offset 0 length 16
 331 Offset          Values
 332 ------          ------
 333 0x0000          38 33 30 58 00 00 34 f4 00 00 10 00 00 c4 17 00
 334
 335 ========================
 336 DEBUGFS COMMANDS
 337 ========================
 338
 339 those commands are used via debugfs interface
 340
 341 ===========
 342 rdmac
 343 rdbbp
 344 rdrf
 345         These commands are used to read the MAC, BBP and RF registers from the
 346         card.  These commands take one parameter that specifies the offset
 347         location that is to be read.  This parameter must be specified in
 348         hexadecimal (its possible to preceed preceding the number with a "0x").
 349
 350         Path: /debugfs/libertas_wireless/ethX/registers/
 351
 352         Usage:
 353                 echo "0xa123" > rdmac ; cat rdmac
 354                 echo "0xa123" > rdbbp ; cat rdbbp
 355                 echo "0xa123" > rdrf ; cat rdrf
 356 wrmac
 357 wrbbp
 358 wrrf
 359         These commands are used to write the MAC, BBP and RF registers in the
 360         card.  These commands take two parameters that specify the offset
 361         location and the value that is to be written. This parameters must
 362         be specified in hexadecimal (its possible to preceed the number
 363         with a "0x").
 364
 365         Usage:
 366                 echo "0xa123 0xaa" > wrmac
 367                 echo "0xa123 0xaa" > wrbbp
 368                 echo "0xa123 0xaa" > wrrf
 369
 370 sleepparams
 371         This command is used to set the sleepclock configurations
 372
 373         Path: /debugfs/libertas_wireless/ethX/
 374
 375         Usage:
 376                 cat sleepparams: reads the current sleepclock configuration
 377
 378                 echo "p1 p2 p3 p4 p5 p6" > sleepparams: writes the sleepclock configuration.
 379
 380                 where:
 381                         p1 is Sleep clock error in ppm (0-65535)
 382                         p2 is Wakeup offset in usec (0-65535)
 383                         p3 is Clock stabilization time in usec (0-65535)
 384                         p4 is Control periodic calibration (0-2)
 385                         p5 is Control the use of external sleep clock (0-2)
 386                         p6 is reserved for debug (0-65535)
 387
 388 subscribed_events
 389
 390         The subscribed_events directory contains the interface for the
 391         subscribed events API.
 392
 393         Path: /debugfs/libertas_wireless/ethX/subscribed_events/
 394
 395         Each event is represented by a filename. Each filename consists of the
 396         following three fields:
 397         Value Frequency Subscribed
 398
 399         To read the current values for a given event, do:
 400                 cat event
 401         To set the current values, do:
 402                 echo "60 2 1" > event
 403
 404         Frequency field specifies the reporting frequency for this event.
 405         If it is set to 0, then the event is reported only once, and then
 406         automatically unsubscribed. If it is set to 1, then the event is
 407         reported every time it occurs. If it is set to N, then the event is
 408         reported every Nth time it occurs.
 409
 410         beacon_missed
 411         Value field specifies the number of consecutive missing beacons which
 412         triggers the LINK_LOSS event. This event is generated only once after
 413         which the firmware resets its state. At initialization, the LINK_LOSS
 414         event is subscribed by default. The default value of MissedBeacons is
 415         60.
 416
 417         failure_count
 418         Value field specifies the consecutive failure count threshold which
 419         triggers the generation of the MAX_FAIL event. Once this event is
 420         generated, the consecutive failure count is reset to 0.
 421         At initialization, the MAX_FAIL event is NOT subscribed by
 422         default.
 423
 424         high_rssi
 425         This event is generated when the average received RSSI in beacons goes
 426         above a threshold, specified by Value.
 427
 428         low_rssi
 429         This event is generated when the average received RSSI in beacons goes
 430         below a threshold, specified by Value.
 431
 432         high_snr
 433         This event is generated when the average received SNR in beacons goes
 434         above a threshold, specified by Value.
 435
 436         low_snr
 437         This event is generated when the average received SNR in beacons goes
 438         below a threshold, specified by Value.
 439
 440 extscan
 441         This command is used to do a specific scan.
 442
 443         Path: /debugfs/libertas_wireless/ethX/
 444
 445         Usage: echo "SSID" > extscan
 446
 447         Example:
 448                 echo "LINKSYS-AP" > extscan
 449
 450         To see the results of use getscantable command.
 451
 452 getscantable
 453
 454         Display the current contents of the driver scan table (ie. get the
 455         scan results).
 456
 457         Path: /debugfs/libertas_wireless/ethX/
 458
 459         Usage:
 460                 cat getscantable
 461
 462 setuserscan
 463         Initiate a customized scan and retrieve the results
 464
 465
 466         Path: /debugfs/libertas_wireless/ethX/
 467
 468     Usage:
 469        echo "[ARGS]" > setuserscan
 470
 471          where [ARGS]:
 472
 473       chan=[chan#][band][mode] where band is [a,b,g] and mode is
 474                                blank for active or 'p' for passive
 475       bssid=xx:xx:xx:xx:xx:xx  specify a BSSID filter for the scan
 476       ssid="[SSID]"            specify a SSID filter for the scan
 477       keep=[0 or 1]            keep the previous scan results (1), discard (0)
 478       dur=[scan time]          time to scan for each channel in milliseconds
 479       probes=[#]               number of probe requests to send on each chan
 480       type=[1,2,3]             BSS type: 1 (Infra), 2(Adhoc), 3(Any)
 481
 482     Any combination of the above arguments can be supplied on the command line.
 483       If the chan token is absent, a full channel scan will be completed by
 484       the driver.  If the dur or probes tokens are absent, the driver default
 485       setting will be used.  The bssid and ssid fields, if blank,
 486       will produce an unfiltered scan. The type field will default to 3 (Any)
 487       and the keep field will default to 0 (Discard).
 488
 489     Examples:
 490     1) Perform an active scan on channels 1, 6, and 11 in the 'g' band:
 491             echo "chan=1g,6g,11g" > setuserscan
 492
 493     2) Perform a passive scan on channel 11 for 20 ms:
 494             echo "chan=11gp dur=20" > setuserscan
 495
 496     3) Perform an active scan on channels 1, 6, and 11; and a passive scan on
 497        channel 36 in the 'a' band:
 498
 499             echo "chan=1g,6g,11g,36ap" > setuserscan
 500
 501     4) Perform an active scan on channel 6 and 36 for a specific SSID:
 502             echo "chan=6g,36a ssid="TestAP"" > setuserscan
 503
 504     5) Scan all available channels (B/G, A bands) for a specific BSSID, keep
 505        the current scan table intact, update existing or append new scan data:
 506             echo "bssid=00:50:43:20:12:82 keep=1" > setuserscan
 507
 508     6) Scan channel 6, for all infrastructure networks, sending two probe
 509        requests.  Keep the previous scan table intact. Update any duplicate
 510        BSSID/SSID matches with the new scan data:
 511             echo "chan=6g type=1 probes=2 keep=1" > setuserscan
 512
 513     All entries in the scan table (not just the new scan data when keep=1)
 514     will be displayed upon completion by use of the getscantable ioctl.
 515
 516 ==============================================================================