/* * Copyright (c) 2015-2016, The Linux Foundation. All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above * copyright notice, this list of conditions and the following * disclaimer in the documentation and/or other materials provided * with the distribution. * * Neither the name of The Linux Foundation nor the names of its * contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /** @page sample_apps Sample Applications The sample_apps folder, which is part of the software release package folder, contains programs written in the C language. These are a few sample applications 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 and sending and receiving packets on 802.11p channels. See the [Building] section for instructions on 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 de-encapsulates this packet and verifies the contents. Note that sendmsg() and recvmsg() are used for sending/receiving packets. @section building 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: @verbatim make all @endverbatim - To cross compile for a specific target: @verbatim CROSS_COMPILE=arm-oe-linux-gnueabi- make all @endverbatim - or @verbatim CROSS_COMPILE=arm-linux-gnueabihf- make all @endverbatim - To cross compile using native gcc: @verbatim make all @endverbatim - Clean the corresponding intermediate and final objects: @verbatim [CROSS_COMPILE=] make clean @endverbatim 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 application, add a configuration variable according to the library version that is available in the target: - For libnl-2: @verbatim HAVE_LIBNL=1 CROSS_COMPILE= make dsrc_config @endverbatim - For libnl-3: @verbatim HAVE_LIBNL3=1 CROSS_COMPILE= make dsrc_config @endverbatim - Follow these commands to install libnl-3 on the build machine @verbatim 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 @endverbatim @section using_applications Using Applications First configure the channels for OCB communications using the dsrc_set_chan application. 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 set up, use the dsrc_tx application to transmit and the dsrc_rx application to receive. @subsection configure_channel Configure Channel Usage: @verbatim dsrc_set_chan [-i ] [-c ] [-c ] Defaults: interface wlanocb0, channel 5860 -c : 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=
channel_bandwidth0= tx_power0= channel_freq1=
channel_bandwidth1= tx_power1= @endverbatim Note: num_channels=2 means the alternate channel switching. Channel switching is only supported on devices that are capable of feeding the Pulse Per Second signal to the WLAN processor. Check with your platform configuration whether this support exists. Example - To set a channel 5900 on wlanocb0 with 10 MHz (default) bandwidth, @verbatim dsrc_set_chan -c 5900 @endverbatim - To set a channel 5875 on wlanocb0, with 20 MHz bandwidth and a maximu Tx power of 17 dbm, @verbatim dsrc_set_chan -c num_channels=1,channel_freq0=5875,channel_bandwidth0=20,tx_power0=34 @endverbatim - To set two channels alternating, @verbatim 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 @endverbatim @subsection transmit_app Transmit Application Usage: @verbatim Usage: dsrc_tx [-i ] [-c ] [-d] [-h] [-n] [-p ] [-m ] [-r ] [-t ] [-s ] [-a ] [-o ] [-x ] [-p ] [-k ] [-l ] -f 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. @endverbatim Example To transmit 10 packets of 500 bytes each 100 milliseconds apart, at 2.5 dbm transmit power at 6 mbps data rate (assume 10 Mhz channel bandwidth set by dsrc_set_chan): @verbatim dsrc_tx -m 2 -p 5 -k 10 -l 500 -x 100 @endverbatim If two channels have been configured to alternate according to a schedule, the -c option is used to specify on which channel to transmit. 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: @verbatim dsrc_tx -c 5860 -p 10 @endverbatim If the device has been configured for two channels but the -c option is not provided, the packet may be transmitted on either channel. @subsection receive_app Receive Application Usage: @verbatim dsrc_rx [-i ] [-d] [-f Defaults: interface wlanocb0, no dump -d : dump raw packet -i : 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. @endverbatim @subsection configuration_app Configuration Application Usage: @verbatim dsrc_config [-i ] -c Defaults: interface wlanocb0 -i : interface name as found in listing by ifconfig -c : command name as specified in the list of commands @endverbatim Each command will have a separate list of additional parameters. @subsubsection commands_list List of commands set_config Description: Sets the complete OCB configuration, including DCC paramters. The DCC parameters are read from the dcc.dat file, which should be in the same folder as the dsrc_config executable. Usage: @verbatim dsrc_config -c set_config [-i ] [-o ] -o : 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=
channel_bandwidth0= tx_power0= duration0= guard0= disable_rx_stats0={0|1} : when 0 (default) RX stats headers are added. when 1 RX stats headers are not added. channel_freq1=
channel_bandwidth1= tx_power1= duration1= guard1= 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. @endverbatim For example, to configure channel 5860: @verbatim dsrc_config -c set_config -o channel_freq0=5860 @endverbatim To configure channel 5875 with a 20 MHz bandwidth: @verbatim dsrc_config -c set_config -o channel_freq0=5875,channel_bandwidth0=20 @endverbatim 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: @verbatim dsrc_config -c set_config -o num_channels=2,channel_freq0=5860,duration0=100, guard0=15,channel_freq1=5900,duration1=100,guard1=15 @endverbatim Note: The guard interval is included in the duration. 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 get_stats Description: Reads the DCC statistics and displays them. Usage: dsrc_config -c get_stats stats_event Description: Listens for DCC statistics events. The WLAN driver sends periodic updates of the DCC statistics and they are displayed in the terminal. Usage: @verbatim dsrc_config -c stats_event -o -o : num_channels={1|2} : channel_freq0=
channel_freq1=
@endverbatim Note: There must not be any spaces between the suboptions provided for -o. clear_stats Description: Resets the DCC statistics to their initial state. This clears all DCC statistics. Usage: dsrc_config -c clear_stats 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. 1, 1958. Usage: dsrc_config -c set_utc start_ta Description: Starts sending timing advertisement (TA) frames on a specified channel and at a specified repeat rate. The repeat rate is defined as the number of times the TA frame will be sent during a 5-second interval. The set_utc command must be executed before this command. Usage: dsrc_config -c start_ta -o channel_freq0=\ -r \ For example, to configure the device to transmit the timing advertisement frame once per second on channel 5860: @verbatim 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 @endverbatim stop_ta Description: Stops sending timing advertisement frames on a specified channel. Usage: dsrc_config -c stop_ta -o channel_freq0=\ get_tsf Description: Gets the timing synchronization function (TSF) timer value and displays it as a 64-bit integer. Usage: dsrc_config -c get_tsf rx_vsa Description: Receive and display Vendor Specific Action frames. Usage: dsrc_config -c rx_vsa @section example_use_cases Example Use Cases @subsection multi-channel_operation Multi-channel operation using 3 devices (DUTs) A 1pps signal must be present at GPIO1. @subsubsection tx_multi-channel Tx multi-channel, Rx single channel DUT 1 -- Tx multi-channel, channels 5870 and 5900: @verbatim ./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 @endverbatim @newpage DUT 2 -- Rx single channel, channel 5870: @verbatim ./dsrc_set_chan -c 5870 ./dsrc_rx @endverbatim DUT 3 -- Rx single channel, channel 5900: @verbatim ./dsrc_set_chan -c 5900 ./dsrc_rx @endverbatim @subsubsection tx_multi-channel Tx multi-channel, Rx multi-channel DUT 1 -- Tx multi-channel, channels 5870 and 5900: @verbatim ./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 @endverbatim DUT 2 -- Rx multi-channel, channels 5870 and 5900: @verbatim ./dsrc_set_chan -c num_channels=2,channel_freq0=5870,channel_bandwidth0=10, channel_freq1=5900,channel_bandwidth1=10 ./dsrc_rx @endverbatim DUT 3 -- Rx multi-channel, channels 5870 and 5900: @verbatim ./dsrc_set_chan -c num_channels=2,channel_freq0=5870,channel_bandwidth0=10, channel_freq1=5900,channel_bandwidth1=10 ./dsrc_rx @endverbatim @subsubsection timing_advertisement Timing Advertisement DUT 1 -- Tx @verbatim 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 @endverbatim DUT 2 -- Rx @verbatim ./dsrc_set_chan -c 5870 @endverbatim */