Local Traffic Generator (LTG)¶

The High MAC Framework implements a Local Traffic Generator (LTG) which can be configured to create packets for wireless transmission. LTG packets are intended for experiments where predictable traffic patterns are required. The LTG framework has three components: the LTG Configuration, the LTG Schedule and the LTG Payload.

LTG Configuration¶

The LTG Configuration subsystem handles parameters universal to all LTGs. These parameters tell the framework when an LTG should start and how long it should run.

Parameter	Description
`u32 duration_usec`	Number of microseconds an LTG will execute after being started. An argument of `LTG_DURATION_FOREVER` will instruct the framework to run the LTG forever or until it is explicitly stopped by the high MAC application.
`u32 start_delay_usec`	Number of microseconds the framework will wait before starting an LTG.
`function_ptr_t remove_callback`	Pointer to a function provided by the framework or high MAC application that will be executed when an LTG is removed. This is typically used to clean up any dynamic memory that the LTG might be using outside of the context of the LTG framework.
`void* callback_argument`	Pointer to an argument that is provided to the `remove_callback`

These arguments are passed to the ltg_sched_create() function as an ltg_config_t struct.

LTG Schedule¶

The LTG Schedule subsystem handles the timing of the generation of packets. Once configured and started, it will execute a callback that is provided by the high MAC application. A high MAC application can define whatever LTG schedule it requires. The reference LTG code defines two LTG schedule types:

Periodic¶

The periodic LTG scheduler executes the LTG event callback at a regular interval that specified by the following parameters:

Parameter	Description
`ltg_sched_type_t type`	Must be `LTG_SCHED_TYPE_PERIODIC`
`u32 interval_usec`	Number of microseconds between invocations of the LTG event callback. A value of `0` will effectively backlog the flow to attempt transmissions as fast as possible.

The periodic LTG scheduler can be used by filling in the ltg_sched_periodic_params_t union member of the ltg_sched_spec_t argument passed to the ltg_sched_create() function.

Uniform Random¶

The uniform random LTG scheduler executes the LTG event callback at a uniform random interval specified by the following parameters:

Parameter	Description
`ltg_sched_type_t type`	Must be `LTG_SCHED_TYPE_UNIFORM_RAND`
`u32 min_interval_usec`	Minimum number of microseconds between invocations of the LTG event callback.
`u32 max_interval_usec`	Maximum number of microseconds between invocations of the LTG event callback.

The framework will choose a random value uniformly distributed over the range of [min_interval_usec, max_interval_usec] as the interval between executions of the LTG event callback. The uniform random LTG scheduler can be used by filling in the ltg_sched_uniform_rand_params_t union member of the ltg_sched_spec_t argument passed to the ltg_sched_create() function.

LTG Payload¶

The LTG Payload subsystem defines the contents of each packet created by the framework. The high MAC application is responsible for creating LTG packet payloads via a callback function registered with the framework.

MAC Service Data Unit Payloads (MSDU)¶

LTG MSDU payloads are injected into the portal subsystem. They can be thought of as virtual Ethernet receptions. At a minimum, each LTG MSDU payload contains the following:

Parameter	Description
`u64 unique_seq`	LTG frames contain a larger-than-standard sequence number so they can be uniquely identified in logs without having to deal with duplicates.
`u32 ltg_id`	Identification of the LTG that created this packet.

The MAC application can append whatever additional payload it needs to this minimum LTG payload. The reference LTG framework defines two MSDU LTG payload types:

Fixed Length Payload¶

A fixed length payload results an enqueued packet with a fixed length on each invocation of the LTG event callback. The parameters for a fixed length payload are the following:

Parameter	Description
`ltg_pyld_type_t type`	Must be `LTG_PYLD_TYPE_FIXED`
`u8 addr_da[MAC_ADDR_LEN];`	The destination MAC address for this LTG.
`u16 length`	Length of the payload in bytes. Acceptable range is `[12, 1500]` bytes.

The resulting payload will be equivalent to an Ethernet reception with a destination address of addr_da. How this address maps onto the 802.11 header depends on the encapsulation rules of the particular application.

The fixed length LTG payload can be used by filling in the ltg_pyld_fixed_t union member of the ltg_pyld_spec_t argument passed to the ltg_sched_create() function.

Uniform Random Length Payload¶

A uniform random length payload results an enqueued packet with a random length chosen uniformly over a specified range. This length is indepedently drawn on each invocation of the LTG event callback. The parameters for a uniform random length payload are the following:

Parameter	Description
`ltg_pyld_type_t type`	Must be `LTG_PYLD_TYPE_UNIFORM_RAND`
`u8 addr_da[MAC_ADDR_LEN];`	The destination MAC address for this LTG.
`u16 min_length`	Minimum length of the payload in bytes. Acceptable range is `[12, 1500]` bytes.
`u16 max_length`	Maximum length of the payload in bytes. Acceptable range is `[12, 1500]` bytes.

The uniform random length payload can be used by passing an ltg_pyld_uniform_rand struct to the ltg_sched_create() function.

The resulting payload will be equivalent to an Ethernet reception with a destination address of addr_da. How this address maps onto the 802.11 header depends on the encapsulation rules of the particular application.

The uniform random length payload can be used by passing an ltg_pyld_uniform_rand struct to the ltg_sched_create() function.

The fixed length LTG payload can be used by filling in the ltg_pyld_uniform_rand_t union member of the ltg_pyld_spec_t argument passed to the ltg_sched_create() function.

Raw Payloads¶

The LTG framework is capable of generating packets of completely arbitrary bytes that need not adhere to any standard 802.11 framing. These “raw” payloads bypass the portal subsystem and are enqueued directly to a WLAN transmission queue.

Parameter	Description
`ltg_pyld_type_t type`	Must be `LTG_PYLD_TYPE_RAW`
`u8 mcs`	The MCS that should be used for the WLAN transmission.
`u8 phy_mode`	`PHY_MODE_NONHT` or `PHY_MODE_HTMF`
`u16 length`	Length of raw frame. This is the total length of the transmitted frame and must include 4 bytes for FCS
`u8* payload`	Pointer to the payload bytes that should be sent.

The fixed length LTG payload can be used by filling in the ltg_pyld_raw_t union member of the ltg_pyld_spec_t argument passed to the ltg_sched_create() function.

Example Usage¶

To create a backlogged LTG destined to the address 00:01:02:03:04:05 with each payload being 1500 bytes, the following code snippet can be used:

u8 addr_da[] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05};

ltg_config_t ltg_config;
ltg_config.duration_usec = LTG_DURATION_FOREVER;
ltg_config.start_delay_usec = 0;
ltg_config.remove_callback = (function_ptr_t)wlan_null_callback;

ltg_pyld_spec_t ltg_pyld;
ltg_pyld.type = LTG_PYLD_TYPE_FIXED;
memcpy(ltg_pyld.fixed.addr_da, addr_da, 6);
ltg_pyld.fixed.length = 1500;

ltg_sched_spec_t ltg_sched;
ltg_sched.type = LTG_SCHED_TYPE_PERIODIC;
ltg_sched.periodic.interval_usec = 0;

u32 ltg_id = ltg_create(&ltg_config, &ltg_sched, &ltg_pyld);
ltg_start(ltg_id);