Above figure shows software and hardware/FPGA modules that compose the openwifi design. The module name is equal/similar to the source code file name. Driver module source codes are in openwifi/driver/. FPGA module source codes are in openwifi-hw repository. The user space tool sdrctl source code are in openwifi/user_space/sdrctl_src/. [Sysfs](https://man7.org/linux/man-pages/man5/sysfs.5.html) is another channel that is offered to do userspace-driver communication by mapping driver variables to virtual files. Check [this app note](app_notes/driver_stat.md#Sysfs-explanation) for further explanation.
[Linux mac80211 subsystem](https://www.kernel.org/doc/html/v4.16/driver-api/80211/mac80211.html), as a part of [Linux wireless](https://wireless.wiki.kernel.org/en/developers/documentation/mac80211), defines a set of APIs ([ieee80211_ops](https://www.kernel.org/doc/html/v4.9/80211/mac80211.html#c.ieee80211_ops)) to rule the Wi-Fi chip driver behavior. SoftMAC Wi-Fi chip driver implements (subset of) those APIs. That is why Linux can support so many Wi-Fi chips of different chip vendors. Different mode (AP/Client/ad-hoc/mesh) might need different set of APIs
Above APIs are called by upper layer (Linux mac80211 subsystem). When they are called, the driver (sdr.c) will do necessary job via openwifi FPGA implementation. If necessary, the driver will call other component drivers, like tx_intf_api/rx_intf_api/openofdm_tx_api/openofdm_rx_api/xpu_api, for help.
After receiving a packet from the air, FPGA will raise interrupt (if the frame filtering rule allows) to Linux, then the function openwifi_rx_interrupt() of openwifi driver (sdr.c) will be triggered. In that function, ieee80211_rx_irqsafe() API is used to give the packet and related information (timestamp, rssi, etc) to upper layer.
The packet sending is initiated by upper layer towards openwifi driver. After the packet is sent by the driver over FPGA to the air, the upper layer will expect a sending report from the driver. Each time FPGA sends a packet, an interrupt will be raised to Linux and trigger openwifi_tx_interrupt(). This function will report the sending result (failed? succeeded? number of retransmissions, etc.) to upper layer via ieee80211_tx_status_irqsafe() API.
Besides the Linux native Wi-Fi control programs, such as ifconfig/iw/iwconfig/iwlist/wpa_supplicant/hostapd/etc, openwifi offers a user space tool sdrctl to access openwifi specific functionalities, such as time sharing of the interface between two network slices, arbitrary Tx/Rx frequency, Tx attenuation, etc. you may find more details of the slicing mechanism [here](https://doc.ilabt.imec.be/ilabt/wilab/tutorials/openwifi.html#sdr-tx-time-slicing).
sdrctl is implemented as nl80211 testmode command and communicates with openwifi driver (function openwifi_testmode_cmd() in sdrctl_intf.c) via Linux nl80211--cfg80211--mac80211 path
slice_idx|the slice that will be set/get|0 to 3. After finishing all slice config, **set slice_idx to 4** to synchronize all slices. Otherwise the start/end of different slices have different actual time
module_name **drv_rx**/**drv_tx**/**drv_xpu**/**rf** refers to the corresponding driver functionality. Related registers are defined in sdr.h. Search drv_rx_reg_val/drv_tx_reg_val/drv_xpu_reg_val/rf_reg_val to see their functionalities.
module_name **rx_intf**/**tx_intf**/**rx**/**tx**/**xpu** FPGA modules (rx_intf/tx_intf/openofdm_rx/openofdm_tx/xpu). Related register addresses are defined in hw_def.h and mapped to slv_regX in .v file (X is the register index). Check rx_intf/tx_intf/openofdm_rx/openofdm_tx/xpu.c and .v files to see their functionalities.
0|receiver action threshold|receiver will not react (short preamble search and further) if the signal strength is less than this threshold. N means -NdBm
4|rx antenna selection|0:rx1, 1:rx2
7|dmesg print control|please check Debug methods section in this page
(In the **comment** column, you may get a list of **decimalvalue(0xhexvalue):explanation** for a register, only use the **decimalvalue** in the sdrctl command)
0|override Linux rate control of non-ht TX unicast data packet|0:auto by Linux, 4:6M, 5:9M, 6:12M, 7:18M, 8:24M, 9:36M, 10:48M, 11:54M
1|override Linux rate control of ht TX unicast data packet|0:auto by Linux, 4:6.5M, 5:13M, 6:19.5M,7:26M, 8:39M, 9:52M, 10:58.5M, 11:65M (add 16 to these values for short GI rate)
2|override Linux rate control of vht (11ac)|not implemented yet
3|override Linux rate control of he (11ax)|not implemented yet
4|tx antenna selection|0:tx1, 1:tx2
7|dmesg print control|please check Debug methods section in this page
4|baseband clock and IQ fifo in/out control|no use anymore -- for old bb rf independent mode
5|control/config dma to cpu|check rx_intf.v slv_reg5
6|abnormal packet length threshold|bit31-16 to store the threshold. if the packet length is not in the range of 14 to threshold, terminate the dma to cpu
7|source selection of rx dma to cpu|check rx_intf.v slv_reg7
8|reserved|reserved
9|number of dma symbol to cpu|only valid in manual mode (slv_reg5[5]==1). normally the dma is set automatically by the received packet length
0|reset|each bit is connected to tx_intf.v internal sub-module. 1 -- reset; 0 -- normal
1|DUC config or tx arbitrary IQ write port|DUC is removed already. Now it is used to write arbitrary IQ to tx_intf for test purpose
2|phy tx auto start config|check tx_intf.v slv_reg2
4|CTS to Self config|auto set by cts_reg in openwifi_tx of sdr.c. bit31: enable/disable, bit30: rate selection: 1: use traffic rate, 0: manual rate in bit7-4, bit23-8: duration field
11|threshold for FPGA fifo almost full|driver(sdr.c) read 1bit flag in slv_reg21 (4bit in total for 4 queue) to know the FPGA fifo/queue is almost full.
21|queue almost full flag|4bit for 4 queue. criteria is the threshold in slv_reg11. check by tx_intf_api->TX_INTF_REG_S_AXIS_FIFO_NO_ROOM_read() in sdr.c
0|reset|each bit is connected to openofdm_rx.v internal sub-module. 1 -- reset; 0 -- normal
1|channel estimation subcarrier smoothing control|bit0: 1--force smoothing; 0--auto by ht header. bit4: 1--disable all smoothing; 0--let bit0 decide
2|power trigger and dc detection threshold|bit10-0: signal level below this threshold won't trigger demodulation. the unit is rssi_half_db, check rssi_half_db_to_rssi_dbm()/rssi_dbm_to_rssi_half_db() in sdr.c to see the relation to rssi dBm. bit23-16: threshold to prevent dc (or low frequency interference) triggered demodulation
3|minimum plateau used for short preamble detection|initialized by openofdm_rx.c: openofdm_rx_api->OPENOFDM_RX_REG_MIN_PLATEAU_write
4|soft decoding flag and abnormal packet length threshold|bit0 for soft decoding: 0 -- hard, 1 -- soft. bit31-16: if the packet length is not in the range of 14 to this threshold, terminate demodulation.
0|reset|each bit is connected to xpu.v internal sub-module. 1 -- reset; 0 -- normal
1|rx packet and I/Q config when tx|bit0 0: auto control (auto self-rx-IQ-mute when tx), 1:manual control by bit31 (1 self-IQ-mute; 0 unmute). bit2 0: rx packet filtering is configured by Linux, 1: no rx packet filtering, send all to Linux
3|TSF timer high 31bit write|falling edge of register MSB will trigger the TSF timer reload, which means write '1' then '0' to bit31 (bit30-0 for TSF)
4|band, channel and ERP short slot setting|for CSMA engine config. set automatically by Linux. manual set could be overrided unless you change sdr.c
5|DIFS and backoff advance (us), abnormal pkt length threshold|advance (us) for tx preparation before the end of DIFS/backoff. bit7-0:DIFS advance, bit15-8: backoff advance. bit31-16: if the packet length is not in the range of 14 to this threshold, terminate pkt filtering procedure
6|multi purpose CSMA settings|bit7-0: forced channel idle (us) after decoding done to avoid false alarm caused by strong "AGC tail" signal. bit31: NAV disable, bit30: DIFS disable, bit29: EIFS disable, bit28: dynamic CW disable (when disable, CW is taken from bit19-16). (value 1 -- forced disable; 0 -- normal/enable)
7|RSSI and ad9361 gpio/gain delay setting (sync with IQ rssi)|bit26-16: offset for rssi report to Linux; bit6-0 delay (number of sample) of ad9361 gpio/gain to sync with IQ sample rssi/amplitude
8|RSSI threshold for CCA (channel idle/busy)|set by ad9361_rf_set_channel automatically. the unit is rssi_half_db, check rssi_half_db_to_rssi_dbm()/rssi_dbm_to_rssi_half_db() in sdr.c to see the relation to rssi dBm
9|some low MAC time setting|bit31 0:auto, 1:manual. When manual, bit6-0: PHY rx delay, bit13-7: SIFS, bit18-14: slot time, bit23-19: ofdm symbol time, bit30-24: preamble+SIG time. unit us. check xpu.v (search slv_reg9)
10|BB RF delay setting|unit 0.1us. bit7-0: BB RF delay, bit14-8: RF end extended time on top of the delay. bit22-16: delay between bb tx start to RF tx on (lo or port control via spi). bit30-24: delay between bb tx end to RF tx off. check xpu.v (search slv_reg10)
11|ACK control and max num retransmission|bit4: 0:normal ACK, 1:disable auto ACK reply in FPGA. bit3-0: if bit3==0, the number of retransmission is decided by Linux. if bit3==1, the max num retransmission is taken from bit2-0
12|AMPDU control|bit0: indicate low MAC start to receive AMPDU. bit4-1: tid. bit31: tid enable (by default, tid is not enabled and we decode AMPDU of all tid)
13|spi controller config|1: disable spi control and Tx RF is always on; 0: enable spi control and Tx RF only on (lo/port) when pkt sending
16|setting when wait for ACK in 2.4GHz|unit 0.1us. bit14-0: OFDM decoding timeout (after detect PHY header), bit30-16: timeout for PHY header detection, bit31: 0: FCS valid is not needed for ACK packet, 1: FCS valid is needed for ACK packet
17|setting when wait for ACK in 5GHz|unit 0.1us. bit14-0: OFDM decoding timeout (after detect PHY header), bit30-16: timeout for PHY header detection, bit31: 0: FCS valid is not needed for ACK packet, 1: FCS valid is needed for ACK packet
19|CW min and max setting for 4 FPGA queues|bit3-0: CW min for queue 0, bit7-4: CW max for queue 0, bit11-8: CW min for queue 1, bit15-12: CW max for queue 1, bit19-16: CW min for queue 2, bit23-20: CW max for queue 2, bit27-24: CW min for queue 3, bit31-28: CW max for queue 3. automatically decided by Linux via openwifi_conf_tx of sdr.c
20|slice/queue-tx-gate total cycle length|bit21-20: queue selection. bit19-0: total cycle length in us
21|slice/queue-tx-gate start time in the cycle|bit21-20: queue selection. bit19-0: start time in us
22|slice/queue-tx-gate end time in the cycle|bit21-20: queue selection. bit19-0: end time in us
After FPGA receives a packet, no matter the FCS/CRC is correct or not it will raise interrupt to Linux if the frame filtering rule allows (See also [mac80211 frame filtering](https://www.kernel.org/doc/html/v4.9/80211/mac80211.html#frame-filtering)). openwifi_rx_interrupt() function in sdr.c serves the interrupt and gives the necessary information to upper layer (Linux mac80211 subsystem) via ieee80211_rx_irqsafe.
The FPGA frame filtering configuration is done by function openwifi_configure_filter() in sdr.c. The filter_flag together with **HIGH_PRIORITY_DISCARD_FLAG** finally go to pkt_filter_ctl.v of xpu module in FPGA, and control how FPGA does frame filtering. Openwifi has the capability to capture all received packets even if the CRC is wrong. You just need to set the NIC to monitor mode by iwconfig command (check monitor_ch.sh in user_space directory). In monitor mode, all received packets (including control packet, like ACK) will be given to Linux mac80211.
- should a sequence number be inserted to the packet at the driver/chip level?
- maintain sequence number (ring->bd_wr_idx) for internal use (cross check between FPGA, openwifi_tx and openwifi_tx_interrupt)
- config FPGA register according to the above information to help FPGA do correct actions (generate PHY header, etc) according to the packet specific requirement.
- fire DMA transmission from Linux to one of FPGA tx queues. The packet may not be sent immediately if there are still some packets in FPGA tx queue (FPGA does the queue packet transmission according to channel and low MAC CSMA state)
Each time when FPGA sends a packet, an interrupt will be raised to Linux reporting the packet sending result. This interrupt handler is openwifi_tx_interrupt().
- packet sending result: packet is sent successfully (FPGA receives ACK for this packet) or not. How many retransmissions have been done (in case FPGA doesn't receive ACK in time, FPGA will do retransmission according to CSMA/CA low MAC state)
SDR is a powerful tool for research. It is the user's responsibility to align with local spectrum regulation when doing OTA (Over The Air) test, or do the test via cable (conducted test), or in a chamber to avoid any potential interference.
This section explains how openwifi config the frequency/channel range and change it driven by Linux. The frequency overriding method is also offered by openwifi to allow the system working in any frequency in 70MHz-6GHz.
The supported channel list is defined in openwifi_2GHz_channels and openwifi_5GHz_channels in sdr.h. If you change the number of supported channels, make sure you also change the frequency range in sdr_regd accordingly and also array size of the following two fields in the struct openwifi_priv:
Linux mac80211 (struct ieee80211_ops openwifi_ops in sdr.c) uses the "config" API to configure channel frequency and some other parameters in real-time (such as during scanning or channel setting by iwconfig). It is hooked to openwifi_config() in sdr.c, and supports only frequency setting currently. The real execution of frequency setting falls to ad9361_rf_set_channel() via the "set_chan" field of struct openwifi_rf_ops ad9361_rf_ops in sdr.c. Besides tuning RF front-end (AD9361), the ad9361_rf_set_channel() also handles AD9361 calibration (if the tuning step size >= 100MHz), RSSI compensation for different frequencies and FPGA configurations (SIFS, etc) for different bands.
If you don't want openwifi node to change the channel anymore (even the Linux asks to do so), use the script user_space/set_restrict_freq.sh to limit the frequency.
```
./set_restrict_freq abcd
```
Above will limit the frequency to abcdMHz. For instance, after you setup the working system in channel 44 and you don't want the node to tune to other channel (occasionally driven by Linux scanning for example), input 5220 as argument to the script.
```
./set_restrict_freq 0
```
Above will remove the limitation. Linux driven channel tuning will be recovered.
### Let openwifi work at arbitrary frequency
Before setting a non-WiFi frequency to the system, a normal working system should be setup in normal WiFi frequency. After this, you can set it to any frequency in 70MHz-6GHz.
Openwifi has adopted a new RF/baseband frequency and sampling design instead of the original "offset tuning" to achieve better EVM, spectrum mask conformance, sensitivity and RSSI measurement accuracy. The AD9361 is set to FDD working mode with the same Tx and Rx frequency. Realtime AD9361 Tx chain control is done via FPGA SPI interface (openwifi-hw/ip/xpu/src/spi.v) to achieve self-interference free (when Rx) and fast Tx/Rx turn around time (0.6us). The AD9361 Tx lo (local oscillator) or RF switch is turned on before the Tx packet and turned off after the Tx packet. so that there isn't any Tx lo noise leakage during Rx period. The IQ sampling rate between AD9361 and FPGA is 40Msps. It is converted to 20Msps via decimation/interpolation inside FPGA to WiFi baseband transceiver.
The openwifi FPGA baseband clock is driven by AD9361 clock, so there won't be any clock drifting/slight-mismatching between RF and baseband as shown in the following picture.
and use **dmesg** command in Linux to see those messages. Regular printing includes tx/rx packet information when a packet is sent or received. Error printing has WARNING information if something abnormal happens. You can search "printk" in sdr.c to see all the printing points.
- RC0: rate of the packet. enum mac80211_rate_control_flags in Linux kernel mac80211.h
- 10M: rate 1Mbps. This 802.11b rate will be converted to 6Mbps, because openwifi supports only OFDM rate.
- FC0040: Frame Control field. Example: FC0208 means type data, subtype data, to DS 0, from DS 1 (a packet from AP to client)
- DI0000: Duration/ID field
- ADDR: address fields addr1/2/3. Target MAC address ffffffffffff (broadcast), source MAC address 6655443322aa (openwifi)
- flag4001201e: flags field from Linux mac80211 struct ieee80211_tx_info (first fragment? need ACK? need sequence number insertion? etc.)
- QoS00: QoS control byte related to the packet (from Linux mac80211)
- SC20_1: sequence number 20 is set to the header of the packet. 1 means that it is set by driver (under request of Linux mac80211)
- retr1: retr1 means no retransmission is needed. retr6 means the maximum number of transmissions for this packet is 6 (set by Linux mac80211)
- ack0: ack0 means the packet doesn't need ACK; ack1 means the packet needs ACK. (set by Linux mac80211)
- prio0: priority queue 0 for this packet (0:VO voice, 1:VI video, 2:BE best effort and 3:BK background). check prio in openwifi_tx() of sdr.c (set by Linux mac80211)
- q0: the packet goes to FPGA queue 0. (You can change the mapping between Linux priority and FPGA queue in sdr.c)
- wr19 rd18: the write/read index of buffer (shared buffer between the active openwifi_tx and background openwifi_tx_interrupt/FPGA)
- hwq len: the current FPGA queue length (number of pkt left in the queue).8bit per queue. see tx_intf register 26 (https://github.com/open-sdr/openwifi/blob/master/doc/README.md)
- no_room_flag: the DMA room of FPGA queue is almost run out. 1bit per queue. see tx_intf register 21 (https://github.com/open-sdr/openwifi/blob/master/doc/README.md)
- ht0: ht0 means 11a/g (legacy); ht1 means 11n (ht)
- aggr0/0: the 1st digit means the packet is from a AMPDU packet (1) or not (0). the 2nd digit means the packet is the last packet of a AMPDU packet (1) or not (0)
- sgi0: 0 means normal GI (Guard Interval); 1 means short GI
- 240M: rate 24Mbps
- FC0080: Frame Control field. Example: FC0108 means type data, subtype data, to DS 1, from DS 0 (a packet client to openwifi AP)
- DI0000: Duration/ID field
- ADDR: address fields addr1/2/3. Target MAC address ffffffffffff (broadcast), source MAC address 00c88b113f5f
- SC2133: sequence number 2133 from the header of the packet
For FPGA itself, FPGA developer could use Xilinx ILA tools to analyze FPGA signals (https://github.com/open-sdr/openwifi-hw/issues/39). Spying on those state machines in xpu/tx_intf/rx_intf would be very helpful for understanding/debugging Wi-Fi low level functionalities.
## Test mode driver
While loading the openwifi driver by "insmod sdr.ko", a test_mode argument can be specified (You can also specify the test_mode value to wgd.sh or fosdem.sh). It will enable some experimental feataures (such as AMPDU aggregation):
```
insmod sdr.ko test_mode=value
```
It is implemented by the global static variable test_mode in sdr.c.
