M7350/wlan/tools/dsrc/README.md

Sample Apps
===========

This folder contains programs written in C language. These are a few sample apps and
re-usable utilities to develop the DSRC driver/application. This is to exemplify
the support in the WLAN Host driver.

There are four sample applications to demonstrate the configuration, sending
and receiving packets on 802.11p channels. See the [BUILDING] section for how to
build the applications from sources.

Simple RX and TX applications:
It encapsulates a packet with a 802.3 custom header before transmitting.
The receiver then deencapsulates this packet and verifies the contents.
Note that we use sendmsg() and recvmsg() for sending/receiving packets.

BUILDING
========

The code in ths folder has been verified with `gcc` cross compiled to different
linux variants. Identify the linux run-time needed for your target device. Make
sure the compiler is in your path.

Use `make` to compile the applications.

- make will look at the CROSS_COMPILE environment variable to determine which
compiler to use. If CROSS_COMPILE is already set:
    make all

- To cross compile for a specific target:
    CROSS_COMPILE=arm-oe-linux-gnueabi- make all

- or
    CROSS_COMPILE=arm-linux-gnueabihf- make all

- To cross compile using native `gcc`:
    make all

- Clean the corresponding intermediate and final objects:
    [CROSS_COMPILE=<variant>] make clean

DSRC additional control commands are implemented using nl80211 sockets. These
require the nl80211 library to be installed in the host and target. In order to
build the `dsrc_config` app, add a configuration variable according to the library
version that is available in the target:

- For libnl-2:


    HAVE_LIBNL=1 CROSS_COMPILE=<variant> make dsrc_config

- For libnl-3:


    HAVE_LIBNL3=1 CROSS_COMPILE=<variant> make dsrc_config

- Follow these commands to install libnl-3 on the build machine


    sudo apt-get install bison flex
    wget http://www.infradead.org/~tgr/libnl/files/libnl-3.2.25.tar.gz
    tar -xzf libnl-3.2.25.tar.gz
    cd libnl-3.2.25
    ./configure --host=arm-linux-gnueabihf --prefix=/usr/arm-linux-gnueabihf
    make
    sudo make install
    cd include/
    sudo make install

USING APPLICATIONS
==================

First configure the channels for OCB communications using `dsrc_set_chan` app.
Channels are expressed with center frequency and optionally with bandwidth.
Default channel bandwidth if not provided is the maximum bandwidth allowed by
that channel (10 MHz for most channels in the 5.9 GHz band).

__Example__ 5860 MHz corresponds to Channel 172.

Once channels have been setup use the `dsrc_tx` app to transmit and `dsrc_rx`
app to recieve.


CONFIGURE CHANNEL
=================

Usage
-----

    dsrc_set_chan [-i <interface>] [-c <channel frequency>] [-c <channel options>]

    Defaults: interface wlanocb0, channel 5860
    -c <channel options> :
        num_channels={1|2} :
           when 1 channel_freq0 and channel_bandwidth0 are needed.
           when 2 same as 1, additionally freq1 and bandwith1 are needed.
        channel_freq0=<center frequency in MHz>
        channel_bandwidth0=<bandwidth in MHz>
        tx_power0=<an integer value, max transmit power in 0.5dbm step size. For example value 6 results in 3dbm>
        channel_freq1=<center frequency in MHz>
        channel_bandwidth1=<bandwidth in MHz>
        tx_power1=<an integer value, max transmit power on channel_freq1, in 0.5dmb step size>

__Note__ `num_channels=2` will mean the alternate channel switching. Channel switching
is only supported on devices that are capable of feeding the Pulse Per Second
signal to WLAN processor. Please check with your platform configuration whether
this support exists.

Example
-------

- To set a channel 5900 on wlanocb0, with 10MHz (default) bandwidth
    dsrc_set_chan -c 5900

- To set a channel 5875 on wlanocb0, with 20MHz bandwidth and max tx power of 17dbm
    dsrc_set_chan -c num_channels=1,channel_freq0=5875,channel_bandwidth0=20,tx_power0=34

- To set 2 channels alternating
    dsrc_set_chan -c num_channels=2,channel_freq0=5860,channel_bandwidth0=10,tx_power0=34,channel_freq1=5875,channel_bandwidth1=20,tx_power1=44


TRANSMIT APP
============
Usage
-----

    Usage: dsrc_tx [-i <interface>] [-c <channel freq>] [-d]
        [-h] [-n] [-p <power>] [-m <MCS index>]
        [-r <retry limit>] [-t <TSF expire high>]
        [-s <TSF expire low>] [-a <chain mask>]
        [-o <traffic ID>] [-x <repeat interval msec>]
        [-p <tx power>] [-k <number of packets>]
        [-l <payload length>] -f <input file>
    Defaults: interface wlanocb0, channel 5860, no dump
    -h : this message
    -d : dump TX packet
    -n : no TX control header
    -m [MCS index] : (data rates @ 20 MHz BW
        0: 6 MBPS
        1: 9 MBPS
        2: 12 MBPS
        3: 18 MBPS
        4: 24 MBPS
        5: 36 MBPS
        6: 48 MBPS
        7: 54 MBPS
    -a : chain mask (antenna).
        eg : for chain 0 use "-a 1"
             for chain 1 "-a 2"
             for chain 0 and 1 "-a 3"
    -o : Traffic ID (priority 0-15)
    -x : repeat with the interval in milliseconds
    -p : tx power at 0.5dbm step. (eg : value 10 is 5dbm)
    -k : number of packets
    -l : payload length in bytes
    -f : input file with contents to transmit
    -e : 802.3 frame with LLC header
         If this flag is not present, an 802.11 frame with EPD header
         will be sent.
    -v : send a VSA frame instead of data frame. This will always use
         an 802.11 frame.

Example
-------
To transmit 10 packets of 500 bytes each 100 milliseconds apart, at 2.5dbm transmit power
at 6mbps data rate (assume 10Mhz channel bandwidth set by dsrc_set_chan)

    dsrc_tx -m 2 -p 5 -k 10 -l 500 -x 100

If two channels have been configured to alternate according to a schedule, the
-c option would be used to specify which channel to transmit on. Note that -c
cannot be used to transmit on a channel that has not been configured. For example,
after configuring channels 5860 and 5900 without `dsrc_set_chan` or `dsrc_config`,
this command can be used to transmit a packet on channel 5860 at 5 dbm

    dsrc_tx -c 5860 -p 10

If the device has been configured for two channels but the -c option is not provided,
the packet may be transmitted on either channel.

RECEIVE APP
===========
Usage
-----

    dsrc_rx [-i <interface>] [-d] [-f <output file>
    Defaults: interface wlanocb0, no dump
    -d : dump raw packet
    -i <interface> : interface name as found in listing by ifconfig
    -f : output file
    -e : expect to receive 802.3 frames. Otherwise expect to receive 802.11 frames.


CONFIGURATION APP
=================
Usage
-----

    dsrc_config [-i <interface>] -c <command> <additional parameters>
    Defaults: interface wlanocb0
    -i <interface> : interface name as found in listing by ifconfig
    -c <command> : command name as specified in the list of commands

Each command will have a separate list of additional parameters.

List of commands:

### 1. set_config ###
Description: Sets the complete OCB configuration including DCC paramters.
The DCC parameters will be read from the dcc.dat file which should be in the
same folder as the dsrc_config executable.

    Usage: dsrc_config -c set_config [-i <interface>] [-o <channel options>]
    -o <channel options> :
        Used for set_config, get_stats, start_ta and stop_ta.
        num_channels={1|2} :
           when 1 channel_freq0 and channel_bandwidth0 are needed.
           when 2 same as 1, additionally freq1 and bandwidth1 are needed.
        channel_freq0=<center frequency in MHz>
        channel_bandwidth0=<bandwidth in MHz>
        tx_power0=<max transmit power in dbm>
        duration0=<channel schedule duration in ms>
        guard0=<schedule start guard interval in ms>
        disable_rx_stats0={0|1} :
           when 0 (default) RX stats headers are added.
           when 1 RX stats headers are not added.
        channel_freq1=<center frequency in MHz>
        channel_bandwidth1=<bandwidth in MHz>
        tx_power1=<max transmit power on channel_freq1>
        duration1=<channel schedule duration in ms>
        guard1=<schedule start guard interval in ms>
        disable_rx_stats1={0|1} :
           when 0 (default) RX stats headers are added.
           when 1 RX stats headers are not added.
        expiry_tsf={0|1} :
           when 0 (default) expiry time in TX options is relative.
           when 1 expiry time in TX options is interpreted as a TSF time.
        eth_mode={0|1} :
           when 0 (default) the app must send 802.11 frames and firmware will not convert.
           when 1 the firmware will convert 802.3 frames to 802.11.
    -d :
        Enable DCC parameters if this option is present.
        Used for the set_config command.

For example, to configure channel 5860

    dsrc_config -c set_config -o channel_freq0=5860

To configure channel 5875 with a 20 MHz bandwidth

    dsrc_config -c set_config -o channel_freq0=5875,channel_bandwidth0=20

Note, there must not be any spaces between the suboptions provided for -o.

To configure channels 5860 and 5900 to alternate with 100 ms on each channel with a
15 ms guard interval

    dsrc_config -c set_config -o num_channels=2,channel_freq0=5860,duration0=100,guard0=15,channel_freq1=5900,duration1=100,guard1=15

Note, the guard interval is included in the duration.

### 2. ndl_update ###
Description: Updates the DCC NDL parameters. The DCC parameters will be read
from the dcc.dat file which should be in the same folder as the dsrc_config
executable.

    Usage: dsrc_config -c ndl_update

### 3. get_stats ###
Description: Reads the DCC statistics and displays them.

    Usage: dsrc_config -c get_stats

### 4. stats_event ###
Description: Listen for DCC statistics events. The WLAN driver will send
periodical updates of the DCC statistics and they will get displayed in the
terminal.

    Usage: dsrc_config -c stats_event -o <channel options>
    -o <channel options> :
        num_channels={1|2} :
        channel_freq0=<center frequency in MHz>
        channel_freq1=<center frequency in MHz>

Note, there must not be any spaces between the suboptions provided for -o.

### 5. clear_stats ###
Description: Resets the DCC statistics to their initial state. This will clear
all the DCC statistics.

    Usage: dsrc_config -c clear_stats

### 6. set_utc ###
Description: Sends the system time in 802.11p defined UTC format to the WLAN
host driver. UTC time in this case is defined as the number of nanoseconds from
Jan 1st 1958.

    Usage: dsrc_config -c set_utc

### 7. start_ta ###
Description: Start sending timing advertisement frames on a specified channel
and specified repeat rate. The repeat rate is defined as the number of times the
TA frame will be sent during a 5 seconds interval. The set_utc command must
be executed before this command.

    Usage: dsrc_config -c start_ta -o channel_freq0=<channel freq> -r <repeat rate>

For example, to configure the device to transmit the timing advertisement frame
once a second on channel 5860

    dsrc_config -c set_config -o channel_freq0=5860
    dsrc_config -c set_utc
    dsrc_config -c start_ta -o channel_freq0=5860 -r 5

### 8. stop_ta ###
Description: Stop sending timing advertisement frames on a specified channel.

    Usage: dsrc_config -c stop_ta -o channel_freq0=<channel freq>

### 9. get_tsf ###
Description: Gets the Timing Synchronization Function timer value and displays
it as a 64-bit integer.

    Usage: dsrc_config -c get_tsf

### 10. rx_vsa ###
Description: Receive and display Vendor Specific Action frames.

    Usage: dsrc_config -c rx_vsa

EXAMPLE USE CASES
=================

Multi-channel operation using 3 devices (DUTs)
==============================================

1pps signal must be present at GPIO1

TX multi-channel, RX single channel
-----------------------------------

DUT 1: TX multi-channel, chan 5870 and 5900
    ./dsrc_set_chan -c num_channels=2,channel_freq0=5870,channel_bandwidth0=10,channel_freq1=5900,channel_bandwidth1=10
    ./dsrc_tx -c 5870 -p 1 -m 0 -a 1 -x 5000& ./dsrc_tx -c 5900 -p 1 -m 0 -a 1 -x 5000

DUT 2: RX single channel, chan 5870
    ./dsrc_set_chan -c 5870
    ./dsrc_rx

DUT 3: RX single channel, chan 5900
    ./dsrc_set_chan -c 5900
    ./dsrc_rx

TX multi-channel, RX multi-channel
----------------------------------

DUT 1: TX multi-channel, chan 5870 and 5900
    ./dsrc_set_chan -c num_channels=2,channel_freq0=5870,channel_bandwidth0=10,channel_freq1=5900,channel_bandwidth1=10
    ./dsrc_tx -c 5870 -p 1 -m 0 -a 1 -x 2000& ./dsrc_tx -c 5900 -p 1 -m 0 -a 1 -x 2000

DUT 2: RX multi-channel, chan 5870 and 5900
    ./dsrc_set_chan -c num_channels=2,channel_freq0=5870,channel_bandwidth0=10,channel_freq1=5900,channel_bandwidth1=10
    ./dsrc_rx

DUT 3: RX multi-channel, chan 5870 and 5900
    ./dsrc_set_chan -c num_channels=2,channel_freq0=5870,channel_bandwidth0=10,channel_freq1=5900,channel_bandwidth1=10
    ./dsrc_rx


Timing Advertisement
====================

DUT 1: TX
Connect 1pps
    ./dsrc_set_chan -c 5870
    ./dsrc_config -c set_utc
    ./dsrc_config -c start_ta -r 3 -o channel_freq0=5870
    ./dsrc_config -c stop_ta

DUT 2: RX
    ./dsrc_set_chan -c 5870

Channel Load
============

Channel load is the percentage of time that the channel is in use, in steps
of 0.1%.

DUT 1: TX

    ./dsrc_config -o num_channels=1,channel_freq0=5860
    ./dsrc_tx -p 10 -m 0 -x 0 -l 1400

DUT 2: RX

    ./dsrc_config -o num_channels=1,channel_freq0=5860 -d
    ./dsrc_config -c get_stats

Observe channel load in get_stats output
e.g. DCC NDL channel load = 980