Local Traffic Generators

The 802.11 MAC code in CPU High implements a Local Traffic Generator framework. The LTG framework supports creating packets with arbitrary payloads at arbitrary intervals, then injecting the packets into the Tx packet flow in the upper MAC application.

An LTG is parameterized by its Schedule and Payload. The schedule and payload options implemented in the reference code are listed below.

Operations & States

The high MAC code supports an arbitrary number of simultaneous LTGs. Each LTG uses a small amount of memory from the heap, so the upper limit depends on overall heap usage. If Python attempts to create too many LTGs the C code will return an error indicating memory has been exhausted.

LTGs are created, started, stopped, and removed using the ltg_create(), ltg_start(), ltg_stop() and ltg_remove() node methods.

An LTG is in one of three states:

  • STOPPED: LTG will not be evaluated by the LTG scheduler
  • START_PENDING: LTG start has been scheduled for start_dly in the future
  • RUNNING: LTG is running and will be evaluated by the LTG scheduler

An LTG continues to use memory even when stopped. Remove LTGs with ltg_remove() or ltg_remove_all() to free the occupied heap memory.

For an LTG with a zero start_dly:

  • n.ltg_start() triggers the STOPPED -> RUNNING state transition
  • The duration interval starts at the STOPPED -> RUNNING state transition

For an LTG with nonzero start_dly:

  • The STOPPED -> START_PENDING transition is triggered by n.ltg_start() or ltg_create(..., start=True)
  • The start_dly interval starts at the STOPPED -> START_PENDING state transition
  • The START_PENDING -> RUNNING transition occurs after start_dly interval
  • The duration interval starts at the START_PENDING -> RUNNING transition

The start_dly and duration intervals occur every time the LTG is started.

Examples

import wlan_exp.ltg as ltg

# Assume n is a wlan_exp node object connected to a board running the 802.11 MAC/PHY design

# Create a simple constant-bit-rate LTG with:
#  destination address of FF-FF-FF-FF-FF-FF (broadcast address)
#  100msec packet creation interval
#  Payload length of 100 bytes
#  Starts immediately, runs forever
sched = ltg.SchedulePeriodic(interval=0.1)
pyld  = ltg.PayloadMSDU(dest_addr=0xFFFFFFFFFFFF, length=100)
ltg_id1 = n.ltg_create(sched, pyld, start=True)

# Create another LTG with the same payload/schedule,
#  but waits 5 seconds before starting then runs for 10 seconds
ltg_id2 = n.ltg_create(sched, pyld, start=True, start_delay=5, duration=10)

# Create an LTG with:
#  destination address of FF-FF-FF-FF-FF-FF (broadcast address)
#  Random packet creation interval between 10msec and 250msec
#  Random payload length between 50 and 350 bytes
#  Starts immediately, runs forever
sched = ltg.ScheduleRandom(min_interval=0.01, max_interval=0.25)
pyld  = ltg.PayloadRandLengthMSDU(dest_addr=0xFFFFFFFFFFFF, min_length=50, max_length=350)
ltg_id3 = n.ltg_create(sched, pyld, start=True)

# Stop and restart an LTG
n.ltg_stop(ltg_id2)
n.ltg_start(ltg_id2)

# Remove all LTGs - recovers all heap memory used by LTG framework
n.ltg_remove_all()

Schedules

class SchedulePeriodic(interval)[source]

Generates a new packet every interval seconds.

Args:

interval (float): Interval between packet creation in float seconds; actual packet
creation interval will be quantized to the LTG polling interval in CPU High (typically 64 usec).
class ScheduleRandom(min_interval, max_interval)[source]

Generates a packet at a uniformaly-distributed random interval.

Parameters:
  • min_interval (numeric) – Minimum interval between packets in seconds
  • max_interval (numeric) – Maximum interval between packets in seconds

Payloads

class PayloadMSDU(dest_addr, length)[source]

LTG payload of a fixed-length MSDU with the sepcified destination address. On each execution this LTG payload will create a single pseudo-Ethernet packet and inject the packet into the high MAC framework at the same point as real Ethernet receptions.

The pseudo-Ethernet packet has contents:

  • header.da = dest_addr
  • header.sa = MAC address of the transmittig node
  • header.ethertype = 0x9090
  • payload = <LTG ID, uniq_seq, arbitrary bytes>

The pseudo-Ethernet packet will be passed to the high MAC framework’s Ethernet encapsulation functions. The behavior of the encapsulation flow depends on the MAC application.

  • AP: if the dest_addr matches the MAC address of an associated node, the new packet will be enqueued for transmission to that node. If the dest_addr is a multicast address the new packet will be enqueued in the dedicated multicast queue. Any other dest_addr will cause the packet to be discarded.
  • STA: the new packet will be enqueued for transmission to the associated AP, like all other data packets
  • IBSS: the new packet will be enqueued for transmission to the specified address

The payload of the LTG MSDU contains the packet’s uniq_seq (64-bit unique sequence number) and the integer ID of the LTG. The remainder of the payload (up to length bytes) is random.

Parameters:
  • dest_addr (u64 int) – MSDU Destination MAC address
  • length (int) – MSDU payload length in bytes
class PayloadRandLengthMSDU(dest_addr, min_length, max_length)[source]
LTG payload of an MSDU with the sepcified destination address and uniform
random payload length. This LTG payload has the same behavior as PayloadMSDU but with random payload length.
Parameters:
  • dest_addr (u64 int) – MSDU Destination MAC address
  • min_length (int) – Minimum length of the MSDU payload in bytes
  • max_length (int) – Maximum length of the MSDU payload in bytes
class PayloadRawMPDU(payload, mcs=None, phy_mode=None)[source]

LTG payload of an arbitrary MPDU. The MPDU payload can be any byte sequence.

The Raw MPDU LTG flow creates packets with arbitrary contents and enqueues the packets for transmission without any further proecssing. Raw MPDUs bypass all high MAC framework functions (i.e. matching destination addresses to known stations (AP), Tx/Rx counts, source MAC address substitution (STA/IBSS), etc.).

Packets created by a Raw MPDU LTG also bypass robustness functions in the lower MAC (no RTS/CTS, no retranmissions).

The Raw MPDU LTG is useful for creating arbitrary transmissions of 802.11 control packets. It can also be used to transmit packets as 802.11 waveforms which contain invalid 802.11 header/payloads.

Parameters:payload (byte array) – MPDU payload, must be iterable of numeric values; each value is cast to a u8. The length of this argument defines the MPDU length. The actual MPDU will be 4 bytes longer than this argument due to the FCS appended before transmission.