The calibrator and other useful utilities for TI wireless solution,
based on the wl12xx and wl18xx drivers.

--- Build procedure

Kernel configuration.
Make sure your kernel is configured to support nl80211 testmode commands
(NL80211_TESTMODE=y). Also enable following configurations:
CRC7=m
FW_LOADER=m

In userspace there is dependent on libnl v2.x package. It can be downloaded
from http://www.infradead.org/~tgr/libnl/files/libnl-2.0.tar.gz

Set follow environment variables:
export NFSROOT=<path to roofs of a target where installed libnl library>
export CROSS_COMPILE=arm-none-linux-gnueabi-
make
make install

--- How to calibrate wl12xx

Calibration is a process in which specific radio configuration
parameters are generated and saved into the NVS file, later to be used
by the wl12xx driver upon initialization.

These configuration parameters are specific to the chip on the
specific design and therefore are sent back to the driver to store in
non-volatile memory for later use. Upon initialization, the wl12xx
driver will load an NVS file where it expects to read those parameters
and send them to the chip.

The NVS file contains 2 main parts - one stores the calibration
parameters and the other one stores initialization information
required for the wl12xx driver.

Automatic calibration procedure.

* Make sure all modules up to wl12xx.ko are loaded. wl12xx_sdio.ko should NOT be loaded.
* The firmware directory must be writeable.
* A "plt firmware" must be present in the firmware directory.

calibrator plt autocalibrate <dev> <kernel mod> <ini> <nvs> <mac>
	dev		Device name. Probably wlan0
	kernel mod	Full path to wl12xx_sdio.ko kernel module
	ini 		Full path to Radio param ini file
	nvs		Full path of nvs file. Must be the real path as wl12xx will load it

This command will perform the following steps:

* Parse the ini and create an nvs without calibration data.
* Load kernel module.
* Perform TxBip and update nvs with calibration data.
* Unload kernel module.

Android example:
./calibrator plt autocalibrate wlan0 /system/lib/modules/wl12xx_sdio.ko TQS_D_1.7.ini /etc/firmware/ti-connectivity/wl1271-nvs.bin 00:01:02:03:04:05

Native Linux example:
./calibrator plt autocalibrate wlan0 /lib/modules/wl12xx_sdio.ko TQS_D_1.7.ini /lib/firmware/ti-connectivity/wl1271-nvs.bin 00:01:02:03:04:05

--- How to choose INI file (wl12xx)

For Beagle board and Panda board use ini_files/127x/TQS_S_2.6.ini
For Blaze board with ES2.1 or ES2.1 use ini_files/128x/TQS_D_1.7.ini

--- How to change MAC address in calibrated NVS

./calibrator set nvs_mac <nvs file> [<mac addr xx:xx:xx:xx:xx:xx>]

If the MAC address missing, the random valid value will be added.


--- How to dump NVS file (wl12xx)

calibrator get dump_nvs [<nvs filename>]


--- Detailed instructions for calibrator procedures (wl12xx)

Normally you should use the autocalibrate command but it's also possible to
run each step manually.

	TxBip procedure (calibration)

It is important to set MAC address to an interface before the procedure.
For example, `ifconfig wlan0 hw ether xx:xx:xx:xx:xx:xx'

calibrator wlan0 plt power_mode on
calibrator wlan0 plt tx_bip <0|1> <0|1> <0|1> <0|1> <0|1> <0|1> <0|1> <0|1>
calibrator wlan0 plt power_mode off

Result of this procedure is new NVS file created locally ./new-nvs.bin
In order to use it, copy the file to /lib/firmware/wl1271-nvs.bin and reload.

	TxCont procedure

calibrator wlan0 plt power_mode on
calibrator wlan0 plt tune_channel <band> <channel>
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>
calibrator wlan0 plt tx_stop
calibrator wlan0 plt power_mode off

Description: This test sends packets of data directly to air. It receives
several parameters as described bellow, to enable diversity of
operational modes.
It is mostly used to see Energy and radio impact on Air.
Content of Packet can be Random, or Zero, One, Zero, one...

Packets send are configurable with following parameters:
  Delay between packets in microseconds
  Rate
    1 Mbps -   0x00000001       MCS_0 - 0x00002000
    2 Mbps -   0x00000002       MCS_1 - 0x00004000
    5.5 Mbps - 0x00000004       MCS_2 - 0x00008000
    6 Mbps -   0x00000008       MCS_3 - 0x00010000
    9 Mbps -   0x00000010       MCS_4 - 0x00020000
    11 Mbps -  0x00000020       MCS_5 - 0x00040000
    12 Mbps -  0x00000040       MCS_6 - 0x00080000
    18 Mbps -  0x00000080       MCS_7 - 0x00100000
    24 Mbps -  0x00000200
    36 Mbps -  0x00000400
    48 Mbps -  0x00000800
    54 Mbps -  0x00001000
  Size of data field in MPDU (in bytes, 0 - 2284)
  Amount - number of packets in case of using series mode
  Power - output power in dBm*1000
  Seed - value for the scrambler
  Packet mode - 0-single, 1-multipile, 3-continuous, 4-FCC
  DC on/off - activate DCF
  gi - guard interval on/off for 11n rates
  Preamble
    1 Mbps - long preamble mode=0
    2, 5.5, 11 Mbps - long preamble mode=0, short preamble mode=1
    6, 9, 12, 18, 24, 36, 48, 54 Mbps - ofdm preamble mode=4
    from MCS_0 to MCS_7 - n mixed mode preamble mode=6, greenfield preamble mode=7
  Type is 0-data packet, 1-ack, 2-probe req, 3-random data, 4-user data
  Scrambler - on/off
  CLPC
    range 0-100 is disable calibration
  Sequence number mode (incremented or fixed)
  Destination Mac address

	RxStat procedure

There are 2 ways to do it - short where all parameters has default values and
full where you have to set all parameters manually.

Short way:
calibrator plt rx_statistics

In the short way each time the statistics will be reseted.

Full way:
calibrator wlan0 plt power_mode on
calibrator wlan0 plt start_rx_statcs
calibrator wlan0 plt get_rx_statcs
calibrator wlan0 plt stop_rx_statcs
calibrator wlan0 plt power_mode off

While willing to reset the statistic run:
calibrator wlan0 plt reset_rx_statcs

	Update NVS file procedure

This is procedure changes ini part of NVS file. It helps when there is need
to change ini part of NVS which already calibrated.

calibrator set upd_nvs <ini file> [<old nvs file> [<new nvs file>]]

If NVS filename parameter not provided the current NVS file will be used from
destination directory (usually /lib/firmware).


--- Miscellaneous procedures

	Read MAC address from NVS file

calibrator get nvs_mac [<nvs filename>]

	Set NVS to use auto FEM detection

calibrator set autofem 1


	Set FEM manufacturer

calibrator set fem_manuf 0|1


	Tone transmission testing
Get in PLT mode
calibrator wlan0 plt power_mode on

Run TxTone transmission
calibrator wlan0 plt tx_tone <tone type> <power>
Tone type
    1 - Carrier FeedThrough
    2 - Single tone
Power [0 - 10000] mdB

Stop transmission
calibrator wlan0 plt tx_stop

Get out from PLT mode
calibrator wlan0 plt power_mode off

-------------------------------------------------------------------------------

--- wl18xx calibration

The wl18xx hardware does most of the calibration by itself, so the
calibration per-se is not necessary.  The tool provides command for
PLT (Production Line Tests), though.

--- MAC addres for wl18xx

For now (as of 20.04.2012), the wl18xx driver uses an NVS file with
the same format as the one used for wl12xx.  Most of the parameters in
this file are not used.  One of the parameters that is still used is
the MAC address.  The wl18xx chip has its own MAC address derived from
FuseROM, but this address can be overriden by setting it in the NVS
file.   If the MAC address in the NVS file is 00:00:00:00:00:00, the
default MAC, burnt in FuseROM is used.

1. The following procedure allows the MAC address to be changed in the
NVS file:

   calibrator wlan0 plt set_mac <nvs_file> [<MAC address>|from_fuse|default]

	<MAC address>		specific address to use (XX:XX:XX:XX:XX:XX)
	from_fuse		try to read from the fuse ROM, if not available the command fails
	default			write 00:00:00:00:00:00 to have the driver read from the fuse ROM,
				fails if not available
	00:00:00:00:00:00	force use of a zeroed MAC address (use with caution!)

2. To read the MAC address that is derived from the FuseROM, the
following command can be used:

   calibrator wlan0 plt get_mac


--- wl18xx power modes

To be able to use the PLT procedures, the firmware needs to be booted
in PLT-mode.  To do so, the wl18xx modules need to be loaded and the
interface wlan0 must be down.  Then use the following command to boot
it in PLT-mode:

   calibrator wlan0 plt power_mode on

The following special plt power-on mode is available for WL6/WL7 devices and
is used to detect the wlan FEM radio module type. This can be used in order
to verify the fem manufacturer inside the ini file when using manual FEM detection.
There is no need to do power_mode off after detect mode:

   calibrator wlan0 plt power_mode fem_detect
   ...
   Firmware detect FEM type=1

The following special plt power-on mode is used to power the chip on without
downloading fw and enabling driver functionality except SDIO mem device.
This can be used in order to bridge RTTT using SDIO:

   calibrator wlan0 plt power_mode chip_awake

And to turn it off (so that it can be booted in normal mode by putting
the wlan0 interface up again):

    calibrator wlan0 plt power_mode off

--- TX simulation in wl18xx

The wl18xx firmware supports TX packets simulation.  With the
following commands, the device will send pre-defined packets to the
air:

1. Boot the firmware in PLT mode:

   calibrator wlan0 plt power_mode on

2. Select the channel to use:

   calibrator wlan0 wl18xx_plt tune_channel <channel> <band> <bandwidth>

   Eg., to use channel 1 with no HT bandwidth:
	calibrator wlan0 wl18xx_plt tune_channel 1 0 0

   Eg., to use channel 136 with 40MHz bandwidth:
	calibrator wlan0 wl18xx_plt tune_channel 136 1 1

   Eg., to use channel 1 with 40MHz Minus  bandwidth:
	calibrator wlan0 wl18xx_plt tune_channel 1 0 2

   Eg., to use channel 1 with 40MHz Plus bandwidth:
	calibrator wlan0 wl18xx_plt tune_channel 1 0 3

3. Start transmitting packets:

   calibrator wlan0 wl18xx_plt start_tx <delay> <rate> <size> <mode> <data_type> <gi> <options1> <options2> <source MAC> <dest MAC> <20|40>

   Where the following parameters can be used:

	 <delay>         delay between packets in us
	 <rate>          transmission rate:
			                0  =  1.0 Mbps                  1  =  2.0 Mbps
					2  =  5.0 Mbps                  3  = 11.0 Mbps
					4  =  6.0 Mbps                  5  =  9.0 Mbps
					6  = 12.0 Mbps                  7  = 18.0 Mbps
					8  = 24.0 Mbps                  9  = 36.0 Mbps
					10 = 48.0 Mbps                  11 = 54.0 Mbps
					12 =  6.5 Mbps (MCS0)           13 = 13.0 Mbps (MCS1)
					14 = 19.5 Mbps (MCS2)           15 = 26.0 Mbps (MCS3)
					16 = 39.0 Mbps (MCS4)           17 = 52.0 Mbps (MCS5)
					18 = 58.5 Mbps (MCS6)           19 = 65.0 Mbps (MCS7)
					20 = 65.0 Mbps + 10% (MCS7 SGI) 21 = MCS8/MCS4  at 40MHz
					22 = MCS9/MCS5  at 40MHz        23 = MCS10/MCS6 at 40MHz
					24 = MCS11/MCS7 at 40MHz        25 = MCS12/MCS7 at 40MHz SGI
					26 = MCS13                      27 = MCS14
					28 = MCS15                      29 = MCS15 SGI
	<size>          packet size (bytes)
	<mode>          number of packets (0 = endless)
	<data_type>     TBD
	<gi>            guard interval (0 = normal, 1 = short)
	<options1>      TBD
	<options2>      TBD
	<source MAC>    source MAC address (XX:XX:XX:XX:XX:XX)
	<dest MAC>      destination MAC address (XX:XX:XX:XX:XX:XX)
	<channel width> channel width (0 = 20 MHz, 1 = 40 MHz)

   For example, to transmit packets continuously at 500ms intervals
   with 1024 bytes length (plus headers) at 65 Mbps (MCS7) on a 40MHz
   channel:

      calibrator wlan0 wl18xx_plt start_tx 500000 19 1024 0 0 0 0 0 00:11:22:33:44:55 01:02:03:04:05:06 1

note, In start_tx there are 3 fields that are TBD and the user must send the command with some value, please “0”:
           - <option1> and <option2> set as 0.
           - <data_type> set as 0.

4. To stop transmitting packets:

      calibrator wlan0 wl18xx_plt stop_tx

   NOTE: it is very important to stop transmitting packets before
   attempting a second start_tx command! If this is not done properly,
   the results will be undefined (and probably not what you want).

--- RX statistics in wl18xx

The wl18xx firmware can capture packets from the air and report
statistics about it.  This can be used to make sure the calibration,
antennas and RF in general is working properly.

1. Boot the firmware in PLT mode:

   calibrator wlan0 plt power_mode on

2. Select the channel to use:

   calibrator wlan0 wl18xx_plt tune_channel <channel> <band> <bandwidth>

   Eg., to use channel 1 with 20MHz bandwidth:
	calibrator wlan0 wl18xx_plt tune_channel 1 0 0

   Eg., to use channel 136 with 40MHz bandwidth:
	calibrator wlan0 wl18xx_plt tune_channel 136 1 1

3. Start gathering data:

   calibrator wlan0 wl18xx_plt start_rx

4. Read the current statistics about packet reception:

   calibrator wlan0 wl18xx_plt get_rx_stats

5. Stop gathering RX statistics:

   calibrator wlan0 wl18xx_plt stop_rx



--- TX set power in wl18xx

1. Boot the firmware in PLT mode:

   calibrator wlan0 plt power_mode on

2. Select the channel to use (see above):

   calibrator wlan0 wl18xx_plt tune_channel <channel> <band> <bandwidth>

3. set the power

   calibrator wlan0 wl18xx_plt set_tx_power <output_power> <level> <band>
                 <primary_channel> <2nd_channel> <antenna> <non_serving_channel>
                  <channel_limitation> <frontend_limit> <gain_calculation>
                   <analog_gain_control_id> <post_dpd_gain>

   Where the following parameters can be used:

	<output_power>			Desired power output supplied in
					dBmX1000 at 125 resolution (1/8 dB),
					i.e. 16.125[dBm] = 16125
	<level>				Indicates which table to refer to (0-3)
	<band>				0 = G band
					1 = A band
	<primary_channel>		Operation channel
	<2nd_channel>			Select the 2nd channel in siso40
					0 = below
					1 = above
	<antenna>			Used for Tx antenna select.
					0 = auto mode
					1 = TX1
					2 = TX2
					3 = Both TX1 & TX2
	<non_serving_channel>		Will this level be used for
					non serving channel
	<channel_limitation>		Notifies the PHY FW when to discard
					internal limits, disable only per
					channel limits
	<frontend_limit>		Notifies the PHY FW when to discard
					external limits - disable per rate
					limits when using external PA platform
	<gain_calculation>		Used to determine one of three gain
					calculation modes (debug only)
					0 = normal operation
					1 = debug mode
					2 = override mode
	<analog_gain_control_id>	When gainCalcMode is set to mode 3,
					this indicator will be used to indicate
					the user's chosen analog index
	<post_dpd_gain>			sets the post DPD gain

   Good default values are:
	calibrator wlan0 wl18xx_plt set_tx_power <out_power> 0 <band> <channel> <freq2ndChInd> 0 0 0 0 1 0 0

   For example, to set the power to 20dBm @ channel 11 use the following command:
	calibrator wlan0 wl18xx_plt set_tx_power 20000 0 0 11 0 0 0 0 0 1 0 0

4. start transmit (see start TX)


---  Set antenna mode in wl18xx

1. Boot the firmware in PLT mode:

   calibrator wlan0 plt power_mode on

2. set the antenna for the 2.4GHz:

   calibrator wlan0 wl18xx_plt set_antenna_mode_24G <mac_prim_rx_chain> <mac_prim_tx_chain> <mac_rx_chain1_en> <mac_rx_chain2_en> <mac_tx_chain1_en> <mac_tx_chain2_en>

3. set the antenna for the 5GHz:

   calibrator wlan0 wl18xx_plt set_antenna_mode_5G <mac_prim_rx_chain> <mac_rx_chain1_en> <mac_rx_chain2_en> <mac_tx_chain1_en>

---  Read  PHY register in wl18xx

1. Boot the firmware in PLT mode:

   calibrator wlan0 plt power_mode on

2. Read register address:

   calibrator wlan0 wl18xx_plt wl18xx_plt phy_reg_read <addr>

   Note: the address is expected in hexadecimal representation.

---  Write PHY register in wl18xx

1. Boot the firmware in PLT mode:

   calibrator wlan0 plt power_mode on

2. Write register address:

   calibrator wlan0 wl18xx_plt wl18xx_plt phy_reg_write <addr> <data>

   Note: the address and data are expected in hexadecimal representation.


-------------------------------------------------------------------------------

The project can be accessed from git repository:
	git clone git://github.com/TI-OpenLink/ti-utils.git