3.2. mango_wlan Kernel Module

The mango_wlan kernel module is a Linux mac80211 driver for the Mango 802.11 MAC/PHY IP. The driver implements all required ops for the mac80211 API.

Supports:

  • Monitor mode (including control and management Rx) with Tx injection
  • STA client mode
  • AP mode
  • RTS/CTS (Request To Send / Clear To Send)
  • CTS-to-self
  • DSSS, NONHT, HTMF, VHT, and HE advertised rates in management frames
  • Virtual interfaces (up to 4)
  • Firmware-supported beaconing for tight TBTT timing
  • Custom statistics reporting through debugfs
  • Compatible with WPA2/WPA3 security (via kernel crypto subsystem)
  • Vendor-specific radiotap metadata for monitor mode receptions
  • Direct driver interaction via mango-wlan-nl Netlink interface
  • Runtime parameter configuration via sysfs interface

MAC Interface

The mango_wlan module communicates with the MAC via a pair of message FIFOs with addresses and interrupt IDs defined in the device tree. These message FIFOs are used primarily for MAC/PHY configuration. Tx/Rx packets are handled by dedicated DMAs and do not transit the message FIFOs.

The mango_wlan exchanges atomic messages with the MAC for all interface configuration commands. The list of message IDs and formats varies between releases. It is essential the mango_wlan driver and MAC software versions match.

debugfs Statistics

Once the module is loaded, /sys/kernel/debug/ieee80211/mango-wlan-phy/netdev:<virtual interface> will be populated with a number of debugfs files. Most are automatically populated with data from the mac80211 framework. mango_wlan provides the following additional files:

stations/<station MAC address>/mango_wlan

This file provides Tx and Rx statistics about the link to a particular station. These statistics are organized according to PHY rate and MCS. It also provides statistics on the number of retries needed in each rate stage of the Minstrel rate control algorithm.

stations/<station MAC address>/mango_wlan_fixed_rate

This file configures a per-station fixed-rate override. Writing four whitespace-separated integers sets phy_mode, mcs, retries, and force_rts.

stations/<station MAC address>/ampdu_stats

This file prints per-station Tx A-MPDU statistics and histograms.

mango_misc_debugfs

This file prints miscellaneous driver statistics, including beacon latency/slack histograms for AP-mode interfaces.

mango_latency_debugfs

This file provides information about important system latencies measured by the driver and MAC at runtime.

Beacon Latency

When operating in AP mode, the MAC firmware handles periodic beaconing in order to abide by the strict Target Beacon Transmission Time (TBTT) requirements from the 802.11 specification, but mac80211 provides the payload of each beacon. To do this, the MAC firmware requests a new beacon payload from the driver. There is a tradeoff in the timing of this request. Too early and the beacon contents may represent stale state by the time it is actually transmitted. Too late and a beacon payload update may not occur in time for the TBTT. The default heuristic used by the mango_wlan driver is that beacon update triggers are sent \(2/3\) of the way through a beacon interval. A typical beacon interval is 100 TU, or 102,400 microseconds. In this case, we anticipate that a new beacon payload will be requested approximately 34,133 microseconds before the beacon must be sent.

An example output from mango_latency_debugfs confirms that beacon payload updates are occurring in a timely manner:

                mango_wlan Latency Statistics
----------------------------------------------------
Beacon Update Slack:
 Min: 23907 usec
 Avg: 34733 usec
 Max: 34754 usec
----------------------------------------------------

/sys/kernel/debug/mango_tx

This file prints global Tx statistics, including the number of completed injected transmissions.

/sys/kernel/debug/mango_multififo

This file prints Multififo occupancy statistics for the MAC/driver FIFO interfaces. The output includes an ASCII bar-graph view of per-FIFO occupancy.

/sys/kernel/debug/mango_hw_rx

This file prints hardware Rx statistics from the MAC/driver Rx interface (for example, waveform metadata / DMA status counters).

Sysfs Interface

The mango_wlan driver provides a sysfs interface at /sys/kernel/mango_wlan/ for runtime configuration and version information. The following parameters are available:

Version Information

version

A read-only parameter that displays the major and minor version number of the Mango WLAN system in decimal format.

driver_build

A read-only parameter that displays the timestamp when the driver was compiled.

driver_git_version

A read-only parameter that displays the git revision identifier of the driver source code, if available.

r5_0_build

A read-only parameter that displays the timestamp when the R5_0 firmware was compiled.

r5_0_git_version

A read-only parameter that displays the git revision identifier of the R5_0 firmware source code, if available.

r5_1_build

A read-only parameter that displays the timestamp when the R5_1 firmware was compiled.

r5_1_git_version

A read-only parameter that displays the git revision identifier of the R5_1 firmware source code, if available.

pl_build

A read-only parameter that displays the timestamp when the XSA file was built in Vivado.

Configuration Parameters

edca_param

Configure Enhanced Distributed Channel Access (EDCA) parameters for each access category queue. The interface accepts five space-separated values in the following format:

echo "<queue> <cwmin> <cwmax> <aifsn> <txop>" > /sys/kernel/mango_wlan/edca_param
Parameters:
  • queue: Access category queue selection (0-3)
  • cwmin: Minimum contention window exponent
  • cwmax: Maximum contention window exponent
  • aifsn: Arbitration Inter-Frame Space Number
  • txop: Transmission Opportunity limit

Example:

# Configure queue 0 with cwmin=4, cwmax=10, aifsn=3, txop=47
echo "0 4 10 3 47" > /sys/kernel/mango_wlan/edca_param

mac_param

A generic interface for sending configuration parameters to the MAC firmware. Accepts a variable number of space-separated values in decimal or hexadecimal format:

echo "<param1> <param2> ..." > /sys/kernel/mango_wlan/mac_param

Example:

# Force tune radio to channel 36
echo "0x00000001 36" > /sys/kernel/mango_wlan/mac_param

Note: The meaning and number of parameters depends on the specific MAC firmware configuration being targeted.

tx_injection_override

The tx_injection_override parameter allows runtime configuration of 802.11 transmission parameters for testing and fine-tuning purposes. It supports three types of overrides:

PHY Mode Override

Set PHY mode and related parameters:

echo "0 phy_mode=<mode> [parameters]" > /sys/kernel/mango_wlan/tx_injection_override

Supported PHY modes:

  • 0x0 (PHY_MODE_DSSS): No additional parameters
  • 0x1 (PHY_MODE_NONHT): No additional parameters
  • 0x2 (PHY_MODE_HTMF): Requires sgi parameter
  • 0x4 (PHY_MODE_VHT): Requires sgi parameter
  • 0x8 (PHY_MODE_HE): Requires multiple parameters:
    • guard_interval: Guard interval (8, 16, 32)
    • ltf_size: LTF training (1, 2, 4)
    • bss_color: BSS color (0-63)
    • txop: Transmission opportunity (0-127)
    • nominal_padding: Nominal padding (0, 8, 16)
    • ul: Uplink flag (0 or 1)

Examples:

# Set PHY_MODE_HTMF with SGI enabled
echo "0 phy_mode=0x2 sgi=1" > /sys/kernel/mango_wlan/tx_injection_override

# Set PHY_MODE_HE with specific parameters
echo "0 phy_mode=0x8 guard_interval=8 ltf_size=1 bss_color=2 txop=5 nominal_padding=0 ul=1" > /sys/kernel/mango_wlan/tx_injection_override

# Clear PHY mode override
echo "0 phy_mode=-1" > /sys/kernel/mango_wlan/tx_injection_override

MCS Override

Set Modulation and Coding Scheme:

echo "1 <mcs_value>" > /sys/kernel/mango_wlan/tx_injection_override

Examples:

# Set MCS to 5
echo "1 5" > /sys/kernel/mango_wlan/tx_injection_override

# Clear MCS override
echo "1 -1" > /sys/kernel/mango_wlan/tx_injection_override

Flags Override

Set transmission flags:

echo "2 <flags_value>" > /sys/kernel/mango_wlan/tx_injection_override

Examples:

# Set flags to 0x1A
echo "2 0x1A" > /sys/kernel/mango_wlan/tx_injection_override

# Clear flags override
echo "2 -1" > /sys/kernel/mango_wlan/tx_injection_override

Note: All numeric inputs accept both decimal and hexadecimal formats.

center_freq_khz

Override the radio center frequency used by the MAC/PHY, in kHz. When an override is enabled, reading the file appends * to the printed value. Write -1 to disable the override and return to the channel-derived value.

Examples:

# Override to 2.412 GHz (channel 1)
echo 2412000 > /sys/kernel/mango_wlan/center_freq_khz

# Disable override
echo -1 > /sys/kernel/mango_wlan/center_freq_khz

rx_freq_report_mode

Controls how the driver reports receive frequency information. Valid values are:

  • 0: true
  • 1: spoofed

Example:

echo 1 > /sys/kernel/mango_wlan/rx_freq_report_mode

ofdm_bw

Set the OFDM bandwidth in MHz. Valid values are 5, 10, and 20. Write -1 to reset to the default (20 MHz). This parameter can only be changed when no wireless interfaces exist.

Example:

echo 10 > /sys/kernel/mango_wlan/ofdm_bw

mac_timing_intervals_100ns

Override MAC timing intervals in units of 100 ns. Readback includes (overridden) tags for any parameters currently overridden. Write reset to clear all overrides. Individual parameters can be overridden or cleared by writing a comma-separated list of key=value pairs; setting a key to -1 clears its override.

Supported keys:

  • sifs
  • eifs_ofdm
  • eifs_dsss
  • slot
  • ofdm_timeout
  • dsss_timeout

Examples:

echo "sifs=16,eifs_ofdm=368,eifs_dsss=1620" > /sys/kernel/mango_wlan/mac_timing_intervals_100ns
echo reset > /sys/kernel/mango_wlan/mac_timing_intervals_100ns

allow_dsss_rx

Enable or disable DSSS receptions in the MAC/PHY. Valid values are 0 and 1.

Example:

echo 1 > /sys/kernel/mango_wlan/allow_dsss_rx

platform_constants

Read or override platform-specific timing constants used for calibration. Reading prints a comma-separated list of key=value fields. Writing accepts a comma-separated list of key=value pairs and sends the updated constants to the MAC.

This interface is intended for hardware bring-up and calibration; it is not typically used in normal operation.

TX Log

The Mango 802.11 MAC/PHY design supports a TX log feature which captures transmitted packets in hardware and forwards the logged packets to Linux. This is useful for recording a ground-truth record of all packets sent over the air.

TX logging is enabled automatically when supported by the loaded FPGA design. The driver prints a kernel log message at boot:

When TX log is enabled, the driver allocates a pool of SKBs which are filled via DMA by the MAC/PHY TX logging hardware. Each logged packet is delivered to local monitor interfaces using Mango’s vendor-specific radiotap metadata. TX log packets can be distinguished from normal Rx monitor captures via a Mango radiotap flag (MANGO_RADIOTAP_FLAGS_TX_LOG).

Notes:

  • The logged payload length may be truncated relative to the total transmitted payload length, depending on the configured TX log buffer size.

Mango Vendor Radiotap

The mango_wlan driver adds Mango vendor-specific radiotap metadata to frames delivered to monitor interfaces. This metadata enables tools like Wireshark to display Mango-specific PHY and hardware details for captured frames.

Mango provides a Wireshark Lua plugin script mango_wlan.lua in the root of the Mango release archive. To use it, copy the file into your Wireshark Lua plugins directory and restart Wireshark. The plugin will decode Mango vendor radiotap fields in monitor captures.