Home | History | Annotate | Download | only in ti-utils
      1 
      2 The calibrator and other useful utilities for TI wireless solution,
      3 based on wl12xx driver.
      4 
      5 Calibration is a process in which specific radio configuration parameters are
      6 generated and saved into the NVS file, later to be used by the wl12xx driver
      7 upon initialization.
      8 These configuration parameters are specific to the chip on the specific design
      9 and therefore are sent back to the driver to store in non-volatile memory for
     10 later use. Upon initialization, the wl12xx driver will load an NVS file where
     11 it expects to read those parameters and send them to the chip.
     12 
     13 The NVS file contains 2 main parts - one stores the calibration parameters and
     14 the other one stores initialization information required for the wl12xx driver.
     15 
     16 --- Build procedure
     17 
     18 Kernel configuration.
     19 Make sure your kernel is configured to support nl80211 testmode commands
     20 (NL80211_TESTMODE=y). Also enable following configurations:
     21 CRC7=m
     22 FW_LOADER=m
     23 
     24 In userspace there is dependent on libnl v2.x package. It can be downloaded
     25 from http://www.infradead.org/~tgr/libnl/files/libnl-2.0.tar.gz
     26 
     27 Set follow environment variables:
     28 export NFSROOT=<path to roofs of a target where installed libnl library>
     29 export CROSS_COMPILE=arm-none-linux-gnueabi-
     30 make
     31 make install
     32 
     33 Make sure that calibrator utility and go.sh script placed in the same dir.
     34 
     35 --- How to calibrate
     36 
     37 Native Linux calibration procedure.
     38 
     39     ./go.sh -c <path to INI file> [<path to firmware directory>]
     40 
     41 Android calibration procedure.
     42 
     43     Based on adb utility which comes native with Android SDK
     44 
     45     adb shell "echo Going to stop GUI"
     46     adb shell "stop"
     47 
     48     adb shell "echo Create reference NVS"
     49     adb shell "calibrator set ref_nvs /data/TQS_D_1.7.ini"
     50 
     51     adb shell "echo Copy reference NVS file"
     52     adb shell "cat ./new-nvs.bin > /system/etc/firmware/ti-connectivity/wl1271-nvs.bin"
     53 
     54     adb shell "echo Insert wl12xx SDIO module"
     55     adb shell "insmod /system/lib/modules/wl12xx_sdio.ko"
     56 
     57     adb shell "echo Calibrate device"
     58     adb shell "calibrator wlan0 plt power_mode on"
     59     adb shell "calibrator wlan0 plt tune_channel 0 7"
     60     adb shell "calibrator wlan0 plt tx_bip 1 1 1 1 1 1 1 1"
     61     adb shell "calibrator wlan0 plt power_mode off"
     62 
     63     adb shell "echo Set MAC address in NVS file"
     64     adb shell "calibrator set nvs_mac ./new-nvs.bin 08:00:28:90:64:31"
     65 
     66     adb shell "echo Remove wl12xx modules"
     67     adb shell "rmmod wl12xx_sdio wl12xx"
     68     adb shell "rmmod wl12xx"
     69 
     70     adb shell "echo Copy calibrated NVS file"
     71     adb shell "cat ./new-nvs.bin > /system/etc/firmware/ti-connectivity/wl1271-nvs.bin"
     72     adb shell "insmod /system/lib/modules/wl12xx.ko"
     73 
     74     adb shell "echo Going to start GUI"
     75     adb shell "start"
     76 
     77 --- How to calibrate with AutoFEM
     78 
     79 The wl12xx driver has ability to use it's NVS file with radio parameters for 2
     80 different frontend modules. The driver requires firmware at boot time which
     81 FEM parameters it needs and provides radio parameters according to answer.
     82 
     83 There is also scenario when driver decides which radio parameters to give
     84 to firmware. In such case, 2 parameters should be set. The autofem should be
     85 0 and fem_manuf should be 0 or 1, depends on FEM manufacturer.
     86 
     87 In order to prepare NVS file with radio parameters for 2 FEMs, do follows
     88 
     89     ./go.sh -c2 <path to INI file> [<path to INI file>]
     90 
     91 There is option to use the feature manualy. In such case, there is need to set
     92 AutoFEM flag to 0 and explicitly set fem_manuf flag.
     93 
     94     ./calibrator set autofem <0-manual|1-auto> [<nvs file>]
     95     ./calibrator set fem_manuf <0|1> [<nvs file>]
     96 
     97 --- How to choose INI file
     98 
     99 It is very important to select INI file according to the firmware (see below).
    100 Those files organized in 3 directories:
    101 station - currently supported station firmware (wl1271-fw.bin)
    102 access_point - currently supported access point (wl1271-fw-ap.bin)
    103 
    104 For Beagle board and Panda board use ini_files/station/127x/TQS_S_2.6.ini
    105 For Blaze board with ES2.1 or ES2.1 use ini_files/station/128x/TQS_D_1.7.ini
    106 
    107 
    108 --- How to change MAC address in calibrated NVS
    109 
    110 ./calibrator set nvs_mac <nvs file> [<mac addr xx:xx:xx:xx:xx:xx>]
    111 
    112 If the MAC address missing, the random valid value will be added.
    113 
    114 
    115 --- How to dump NVS file
    116 
    117 calibrator get dump_nvs [<nvs filename>]
    118 
    119 
    120 --- Firmware files
    121 
    122 The firmware files can be reached from git repository
    123 git://git.kernel.org/pub/scm/linux/kernel/git/dwmw2/linux-firmware.git
    124 under directory ti-connectivity.
    125 There are 2 firmware files there:
    126 wl1271-fw.bin    - station firmware
    127 wl1271-fw-ap.bin    - access point firmware
    128 
    129 
    130 --- Detailed instructions for calibrator procedures
    131 
    132 The following detailed instructions are collection of commands done by
    133 default calibration procedure.
    134 
    135     TxBip procedure (calibration)
    136 
    137 It is important to set MAC address to an interface before the procedure.
    138 For example, `ifconfig wlan0 hw ether xx:xx:xx:xx:xx:xx'
    139 There are 2 ways to do it - short where all parameters has default values and
    140 full where you have to set all parameters manually.
    141 
    142 Short way:
    143 calibrator plt calibrate
    144 
    145 Full way:
    146 calibrator wlan0 plt power_mode on
    147 calibrator wlan0 plt tx_bip <0|1> <0|1> <0|1> <0|1> <0|1> <0|1> <0|1> <0|1>
    148 calibrator wlan0 plt power_mode off
    149 
    150 Result of this procedure is new NVS file created locally ./new-nvs.bin
    151 In order to use it, copy the file to /lib/firmware/wl1271-nvs.bin and reload.
    152 
    153     TxCont procedure
    154 
    155 calibrator wlan0 plt power_mode on
    156 calibrator wlan0 plt tune_channel <band> <channel>
    157 calibrator wlan0 plt tx_cont <delay> <rate> <size> <amount> <power> <seed> <pkt mode> <DC on/off> <gi> <preamble> <type> <scramble> <clpc> <seq nbr mode> <dest mac>
    158 calibrator wlan0 plt tx_stop
    159 calibrator wlan0 plt power_mode off
    160 
    161 Description: This test sends packets of data directly to air. It receives
    162 several parameters as described bellow, to enable diversity of
    163 operational modes.
    164 It is mostly used to see Energy and radio impact on Air.
    165 Content of Packet can be Random, or Zero, One, Zero, one...
    166 
    167 Packets send are configurable with following parameters:
    168   Delay between packets in microseconds
    169   Rate
    170     1 Mbps -   0x00000001       MCS_0 - 0x00002000
    171     2 Mbps -   0x00000002       MCS_1 - 0x00004000
    172     5.5 Mbps - 0x00000004       MCS_2 - 0x00008000
    173     6 Mbps -   0x00000008       MCS_3 - 0x00010000
    174     9 Mbps -   0x00000010       MCS_4 - 0x00020000
    175     11 Mbps -  0x00000020       MCS_5 - 0x00040000
    176     12 Mbps -  0x00000040       MCS_6 - 0x00080000
    177     18 Mbps -  0x00000080       MCS_7 - 0x00100000
    178     24 Mbps -  0x00000200
    179     36 Mbps -  0x00000400
    180     48 Mbps -  0x00000800
    181     54 Mbps -  0x00001000
    182   Size of data field in MPDU (in bytes, 0 - 2284)
    183   Amount - number of packets in case of using series mode
    184   Power - output power in dBm*1000
    185   Seed - value for the scrambler
    186   Packet mode - 0-single, 1-multipile, 3-continuous, 4-FCC
    187   DC on/off - activate DCF
    188   gi - guard interval on/off for 11n rates
    189   Preamble
    190     1 Mbps - long preamble mode=0
    191     2, 5.5, 11 Mbps - long preamble mode=0, short preamble mode=1
    192     6, 9, 12, 18, 24, 36, 48, 54 Mbps - ofdm preamble mode=4
    193     from MCS_0 to MCS_7 - n mixed mode preamble mode=6, greenfield preamble mode=7
    194   Type is 0-data packet, 1-ack, 2-probe req, 3-random data, 4-user data
    195   Scrambler - on/off
    196   CLPC
    197     range 0-100 is disable calibration
    198   Sequence number mode (incremented or fixed)
    199   Destination Mac address
    200 
    201     RxStat procedure
    202 
    203 There are 2 ways to do it - short where all parameters has default values and
    204 full where you have to set all parameters manually.
    205 
    206 Short way:
    207 calibrator plt rx_statistics
    208 
    209 In the short way each time the statistics will be reseted.
    210 
    211 Full way:
    212 calibrator wlan0 plt power_mode on
    213 calibrator wlan0 plt start_rx_statcs
    214 calibrator wlan0 plt get_rx_statcs
    215 calibrator wlan0 plt stop_rx_statcs
    216 calibrator wlan0 plt power_mode off
    217 
    218 While willing to reset the statistic run:
    219 calibrator wlan0 plt reset_rx_statcs
    220 
    221     Update NVS file procedure
    222 
    223 This is procedure changes ini part of NVS file. It helps when there is need
    224 to change ini part of NVS which already calibrated.
    225 
    226 calibrator set upd_nvs <ini file> [<nvs file>]
    227 
    228 If NVS filename parameter not provided the current NVS file will be used from
    229 destination directory (usually /lib/firmware).
    230 
    231 
    232 --- Miscellaneous procedures
    233 
    234     Read MAC address from NVS file
    235 
    236 calibrator get nvs_mac <nvs filename>
    237 
    238 
    239     Push local NVS to the system:
    240 
    241 calibrator phy <phyname> set push_nvs <nvs filename>
    242 
    243 
    244     Set NVS to use auto FEM detection
    245 
    246 calibrator set autofem 1
    247 
    248 
    249     Set FEM manufacturer
    250 
    251 calibrator set fem_manuf 0|1
    252 
    253 
    254     Tone transmission testing
    255 Get in PLT mode
    256 calibrator wlan0 plt power_mode on
    257 
    258 Run TxTone transmission
    259 calibrator set plt_tx_tone <power> <tone type>
    260 Power
    261 Tone type
    262  1 - Single tone
    263  2 - Carrier FeedThrough
    264 
    265 Stop transmission
    266 calibrator wlan0 plt tx_stop
    267 
    268 Get out from PLT mode
    269 calibrator wlan0 plt power_mode off
    270 
    271 -------------------------------------------------------------------------------
    272 
    273 The project can be accessed from git repository:
    274     git clone git://github.com/gxk/ti-utils.git
    275 
    276 Please send all patches to Gery Kahn <geryk (a] ti.com>
    277 and CC linux-wireless (a] vger.kernel.org for community review.
    278 
    279