802.11 Reference Design
802.11 Reference Design: Event Log Entry Types
The 802.11 Reference Design logging framework is designed to record log entries of arbitrary length and type. The MAC code in CPU High is responsible for defining the log entry types and populating each log entry at run time.
The reference code for CPU High defines a number of useful log entry types and implements logging of many run time events, including all Tx and Rx activity. The entry types defined in the reference implementation are listed below.
Users can define new log entry types or modify existing types to support their experiment. The requirements for this are documented below.
Pre-Defined Constants
The values for some log entry fields are drawn from a pre-defined set of constants. For example, the phy_mode fields in Tx/Rx entries have integer values in [0..2] representing DSSS, NONHT or HTMF PHY modes.
The log entry type definitions in Python include lists of the pre-defined constants for each field. You can access these pre-defined constants with the get_entry_constants('Entry_Type') method. This method returns an object with an attribute for each field with constant definitions; each per-field attribute has an attribute per constant. For example:
import wlan_exp.log.util as log_util # Retrieve constants for TX_LOW entries TX_CONSTS = log_util.get_entry_constants('TX_LOW') # Filter an array of TX_LOW entries by pkt_type # Assumes tx_low is numpy array of TX_HIGH entries tx_low_idx = (tx_low['pkt_type'] == TX_CONSTS.pkt_type.BEACON) tx_low_beacons = tx_low[tx_low_idx]
Here TX_CONSTS.pkt_type.BEACON encodes the constant value for the pkt_type field indicating the TX_LOW entry contains a Beacon packet.
The entry type documentation below includes the full list of pre-defined constant names and values.
wlan_exp v1.7.4 Log Entry Types
Entry Type NODE_INFO
Details about the node hardware and its configuration. Node info values are static after boot.
Entry type ID: 1
Field Name | Data Type | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when log entry created | ||||||||||||||
node_type | uint32 | Code identifying applications in CPU High and CPU Low Constants defined for this field:
| ||||||||||||||
node_id | uint32 | Node ID, as set during wlan_exp init | ||||||||||||||
platform_id | uint32 | Hardware generation (always 3 for Mango WARP v3) | ||||||||||||||
serial_num | uint32 | Node serial number | ||||||||||||||
fpga_dna | uint64 | DNA value of node FPGA | ||||||||||||||
version | uint32 | wlan_exp version, as packed values [(u8)major (u8)minor (u16)rev] | ||||||||||||||
scheduler_resolution | uint32 | Minimum interval in microseconds of the WLAN scheduler | ||||||||||||||
wlan_mac_addr | uint64 | Node MAC address, 6 bytes in lower 48-bits of u64 | ||||||||||||||
max_tx_power_dbm | int32 | Maximum transmit power | ||||||||||||||
min_tx_power_dbm | int32 | Minimum transmit power | ||||||||||||||
cpu_high_compilation_date | 12S | CPU High Compilation Date string | ||||||||||||||
cpu_high_compilation_time | 12S | CPU High Compilation Time string | ||||||||||||||
cpu_low_compilation_date | 12S | CPU Low Compilation Date string | ||||||||||||||
cpu_low_compilation_time | 12S | CPU Low Compilation Time string | ||||||||||||||
Entry Type EXP_INFO
Header for generic experiment info entries created by the user application. The payload of the EXP_INFO entry is not described by the Python entry type. User code must access the payload in the binary log data directly.
Entry type ID: 2
Field Name | Data Type | Description |
|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when log entry created |
info_type | uint16 | Exp info type - arbitrary value supplied by application |
info_len | uint16 | Exp info length - length (in byte) of info_payload |
info_payload | uint32 | Exp info payload |
Entry Type NODE_TEMPERATURE
Record of the FPGA system monitor die temperature. This entry is only created when directed by a wlan_exp command. Temperature values are stored as 32-bit unsigned integers. To convert to degrees Celcius, apply (((float)temp_u32)/(65536.0*0.00198421639)) - 273.15
Entry type ID: 4
Field Name | Data Type | Description |
|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when log entry created |
temp_current | uint32 | Current FPGA die temperature (deg C) |
temp_min | uint32 | Minimum FPGA die temperature (deg C) since FPGA configuration or sysmon reset |
temp_max | uint32 | Maximum FPGA die temperature (deg C) since FPGA configuration or sysmon reset |
Entry Type TIME_INFO
Record of a time base event at the node. This log entry is used to enable parsing of log data recorded before and after changes to the node's microsecond MAC timer. This entry also allows a wlan_exp controler to write the current host time to the node log without affecting the node's MAC timer value. This enables adjustment of log entry timestamps to real timestamps in post-proessing.
Entry type ID: 6
Field Name | Data Type | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when log entry created (before any time change is applied) | ||||||||
time_id | uint32 | Random ID value included in wlan_exp TIME_INFO command; used to find common entries across nodes | ||||||||
reason | uint32 | Reason code for TIME_INFO log entry creation Constants defined for this field:
| ||||||||
mac_timestamp | uint64 | New value of MAC Time in microseconds | ||||||||
system_timestamp | uint64 | Value of System Time in microseconds | ||||||||
host_timestamp | uint64 | Host time in microseconds-since-epoch; 0xFFFFFFFFFFFFFFFF if unknown | ||||||||
Entry Type RX_OFDM
Rx events from OFDM PHY. These log entries will only be created for packets that are passed to the high-level MAC code in CPU High. If the low-level MAC filter drops the packet, it will not be logged. For full "monitor mode" ensure the low-level MAC filter is configured to pass all receptions up to CPU High.
Entry type ID: 10
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds at PHY RX_START | ||||||||||||||||||||||||||||||||||||||||
timestamp_frac | uint8 | Fractional part of timestamp (units of 6.25ns) | ||||||||||||||||||||||||||||||||||||||||
phy_samp_rate | uint8 | PHY sampling rate in MSps | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length of payload in bytes | ||||||||||||||||||||||||||||||||||||||||
cfo_est | int32 | Time-domain CFO estimate from Rx PHY; Fix32_31 value, CFO as fraction of sampling frequency | ||||||||||||||||||||||||||||||||||||||||
mcs | uint8 | MCS index, in [0:7] | ||||||||||||||||||||||||||||||||||||||||
phy_mode | uint8 | PHY mode index, in [0:2] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
ant_mode | uint8 | Antenna mode: [1,2,3,4] for SISO Rx on RF [A,B,C,D] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
power | int8 | Rx power in dBm | ||||||||||||||||||||||||||||||||||||||||
padding0 | uint8 | |||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, first frame control byte of 802.11 header Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
channel | uint8 | Channel (center frequency) index | ||||||||||||||||||||||||||||||||||||||||
padding1 | uint8 | |||||||||||||||||||||||||||||||||||||||||
rx_gain_index | uint8 | Radio Rx gain index; larger values mean larger Rx gains, mapping to absolute dB is radio-dependent | ||||||||||||||||||||||||||||||||||||||||
padding2 | uint8 | |||||||||||||||||||||||||||||||||||||||||
flags | uint16 | 1-bit flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
chan_est | (64,2)i2 | OFDM Rx channel estimates, packed as [(uint16)I (uint16)Q] values, one per subcarrier | ||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 24uint8 | First 24 bytes of MAC payload, typically the 802.11 MAC header | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
Entry Type RX_OFDM_LTG
LTG Rx events from OFDM PHY. These log entries will only be created for packets that are passed to the high-level MAC code in CPU High. If the low-level MAC filter drops the packet, it will not be logged. For full "monitor mode" ensure the low-level MAC filter is configured to pass all receptions up to CPU High.
Entry type ID: 11
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds at PHY RX_START | ||||||||||||||||||||||||||||||||||||||||
timestamp_frac | uint8 | Fractional part of timestamp (units of 6.25ns) | ||||||||||||||||||||||||||||||||||||||||
phy_samp_rate | uint8 | PHY sampling rate in MSps | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length of payload in bytes | ||||||||||||||||||||||||||||||||||||||||
cfo_est | int32 | Time-domain CFO estimate from Rx PHY; Fix32_31 value, CFO as fraction of sampling frequency | ||||||||||||||||||||||||||||||||||||||||
mcs | uint8 | MCS index, in [0:7] | ||||||||||||||||||||||||||||||||||||||||
phy_mode | uint8 | PHY mode index, in [0:2] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
ant_mode | uint8 | Antenna mode: [1,2,3,4] for SISO Rx on RF [A,B,C,D] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
power | int8 | Rx power in dBm | ||||||||||||||||||||||||||||||||||||||||
padding0 | uint8 | |||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, first frame control byte of 802.11 header Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
channel | uint8 | Channel (center frequency) index | ||||||||||||||||||||||||||||||||||||||||
padding1 | uint8 | |||||||||||||||||||||||||||||||||||||||||
rx_gain_index | uint8 | Radio Rx gain index; larger values mean larger Rx gains, mapping to absolute dB is radio-dependent | ||||||||||||||||||||||||||||||||||||||||
padding2 | uint8 | |||||||||||||||||||||||||||||||||||||||||
flags | uint16 | 1-bit flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
chan_est | (64,2)i2 | OFDM Rx channel estimates, packed as [(uint16)I (uint16)Q] values, one per subcarrier | ||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 44uint8 | First 44 bytes of MAC payload: the 802.11 MAC header, LLC header, Packet ID, LTG ID | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
ltg_uniq_seq | uint64 | Unique sequence number for LTG packet |
ltg_flow_id | uint64 | LTG Flow ID, calculated as:
|
Entry Type RX_DSSS
Rx events from DSSS PHY. These log entries will only be created for packets that are passed to the high-level MAC code in CPU High. If the low-level MAC filter drops the packet, it will not be logged. For full "monitor mode" ensure the low-level MAC filter is configured to pass all receptions up to CPU High.
Entry type ID: 15
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds at PHY RX_START | ||||||||||||||||||||||||||||||||||||||||
timestamp_frac | uint8 | Fractional part of timestamp (units of 6.25ns) | ||||||||||||||||||||||||||||||||||||||||
phy_samp_rate | uint8 | PHY sampling rate in MSps | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length of payload in bytes | ||||||||||||||||||||||||||||||||||||||||
cfo_est | int32 | Time-domain CFO estimate from Rx PHY; Fix32_31 value, CFO as fraction of sampling frequency | ||||||||||||||||||||||||||||||||||||||||
mcs | uint8 | MCS index, in [0:7] | ||||||||||||||||||||||||||||||||||||||||
phy_mode | uint8 | PHY mode index, in [0:2] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
ant_mode | uint8 | Antenna mode: [1,2,3,4] for SISO Rx on RF [A,B,C,D] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
power | int8 | Rx power in dBm | ||||||||||||||||||||||||||||||||||||||||
padding0 | uint8 | |||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, first frame control byte of 802.11 header Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
channel | uint8 | Channel (center frequency) index | ||||||||||||||||||||||||||||||||||||||||
padding1 | uint8 | |||||||||||||||||||||||||||||||||||||||||
rx_gain_index | uint8 | Radio Rx gain index; larger values mean larger Rx gains, mapping to absolute dB is radio-dependent | ||||||||||||||||||||||||||||||||||||||||
padding2 | uint8 | |||||||||||||||||||||||||||||||||||||||||
flags | uint16 | 1-bit flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 24uint8 | First 24 bytes of MAC payload, typically the 802.11 MAC header | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
Entry Type TX_HIGH
Tx events in CPU High, logged for each data and management frame created and enqueued in CPU High. See TX_LOW for log entries of actual Tx events, including re-transmissions. The time values in this log entry can be used to determine time in queue (time_to_accept), time taken by CPU Low for all Tx attempts (time_to_done) and total time from creation to completion (time_to_accept+time_to_done).
Entry type ID: 20
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when packet was created, immediately before it was enqueued | ||||||||||||||||||||||||||||||||||||||||
time_to_accept | uint32 | Time duration in microseconds between packet creation and acceptance by frame_transmit() in CPU Low | ||||||||||||||||||||||||||||||||||||||||
time_to_done | uint32 | Time duration in microseconds between packet acceptance by CPU Low and completion of all transmissions by CPU Low | ||||||||||||||||||||||||||||||||||||||||
uniq_seq | uint64 | Unique sequence number for Tx packet; 12 LSB of this used for 802.11 MAC header sequence number | ||||||||||||||||||||||||||||||||||||||||
padding0 | uint32 | |||||||||||||||||||||||||||||||||||||||||
num_tx | uint16 | Number of Tx attempts that were made for this packet | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length in bytes of MPDU; includes MAC header, payload and FCS | ||||||||||||||||||||||||||||||||||||||||
padding1 | uint8 | |||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, first frame control byte of 802.11 header Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
queue_id | uint16 | Tx queue ID from which the packet was retrieved | ||||||||||||||||||||||||||||||||||||||||
queue_occupancy | uint16 | Occupancy of the Tx queue immediately after this packet was enqueued | ||||||||||||||||||||||||||||||||||||||||
flags | uint16 | 1-bit flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 24uint8 | First 24 bytes of MAC payload, typically the 802.11 MAC header | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
Entry Type TX_HIGH_LTG
Tx events in CPU High, logged for each data and management frame created and enqueued in CPU High. See TX_LOW for log entries of actual Tx events, including re-transmissions. The time values in this log entry can be used to determine time in queue (time_to_accept), time taken by CPU Low for all Tx attempts (time_to_done) and total time from creation to completion (time_to_accept+time_to_done).
Entry type ID: 21
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when packet was created, immediately before it was enqueued | ||||||||||||||||||||||||||||||||||||||||
time_to_accept | uint32 | Time duration in microseconds between packet creation and acceptance by frame_transmit() in CPU Low | ||||||||||||||||||||||||||||||||||||||||
time_to_done | uint32 | Time duration in microseconds between packet acceptance by CPU Low and completion of all transmissions by CPU Low | ||||||||||||||||||||||||||||||||||||||||
uniq_seq | uint64 | Unique sequence number for Tx packet; 12 LSB of this used for 802.11 MAC header sequence number | ||||||||||||||||||||||||||||||||||||||||
padding0 | uint32 | |||||||||||||||||||||||||||||||||||||||||
num_tx | uint16 | Number of Tx attempts that were made for this packet | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length in bytes of MPDU; includes MAC header, payload and FCS | ||||||||||||||||||||||||||||||||||||||||
padding1 | uint8 | |||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, first frame control byte of 802.11 header Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
queue_id | uint16 | Tx queue ID from which the packet was retrieved | ||||||||||||||||||||||||||||||||||||||||
queue_occupancy | uint16 | Occupancy of the Tx queue immediately after this packet was enqueued | ||||||||||||||||||||||||||||||||||||||||
flags | uint16 | 1-bit flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 44uint8 | First 44 bytes of MAC payload: the 802.11 MAC header, LLC header, Packet ID, LTG ID | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
ltg_uniq_seq | uint64 | Unique sequence number for LTG packet |
ltg_flow_id | uint64 | LTG Flow ID, calculated as:
|
Entry Type TX_LOW
Record of actual PHY transmission. At least one TX_LOW will be logged for every TX_HIGH entry. Multiple TX_LOW entries may be created for the same TX_HIGH entry if the low-level MAC re-transmitted the frame. Use the uniq_seq fields to match TX_HIGH and TX_LOW entries to find records common to the same MPDU.
Entry type ID: 25
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when packet transmission actually started (PHY TX_START time) | ||||||||||||||||||||||||||||||||||||||||
uniq_seq | uint64 | Unique sequence number of original MPDU | ||||||||||||||||||||||||||||||||||||||||
mcs | uint8 | MCS index in [0:7] | ||||||||||||||||||||||||||||||||||||||||
phy_mode | uint8 | PHY mode index, in [1:2] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
ant_mode | uint8 | PHY antenna mode in [0x10, 0x20, 0x30, 0x40] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
tx_power | int8 | Tx power in dBm | ||||||||||||||||||||||||||||||||||||||||
reserved0 | uint8 | |||||||||||||||||||||||||||||||||||||||||
channel | uint8 | Channel (center frequency) index | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length in bytes of MPDU; includes MAC header, payload and FCS | ||||||||||||||||||||||||||||||||||||||||
num_slots | int16 | Number of backoff slots allotted prior to this transmission; may not have been used for initial Tx (attempt_number==1); A value of -1 in this field means no backoff occured | ||||||||||||||||||||||||||||||||||||||||
cw | uint16 | Contention window value at time of this Tx | ||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, (first frame control byte of 802.11 header) Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
flags | uint8 | 1-bit Flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
timestamp_frac | uint8 | Fractional part of Tx timestamp (units of 6.25ns) | ||||||||||||||||||||||||||||||||||||||||
phy_samp_rate | uint8 | PHY Sampling Rate Mode | ||||||||||||||||||||||||||||||||||||||||
attempt_number | uint16 | Transmission index for this attempt, starting at 1 (1 = first Tx) | ||||||||||||||||||||||||||||||||||||||||
reserved1 | uint16 | |||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 24uint8 | First 24 bytes of MAC payload, typically the 802.11 MAC header | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
Entry Type TX_LOW_LTG
Record of actual PHY transmission. At least one TX_LOW will be logged for every TX_HIGH entry. Multiple TX_LOW entries may be created for the same TX_HIGH entry if the low-level MAC re-transmitted the frame. Use the uniq_seq fields to match TX_HIGH and TX_LOW entries to find records common to the same MPDU.
Entry type ID: 26
Field Name | Data Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
timestamp | uint64 | Value of MAC Time in microseconds when packet transmission actually started (PHY TX_START time) | ||||||||||||||||||||||||||||||||||||||||
uniq_seq | uint64 | Unique sequence number of original MPDU | ||||||||||||||||||||||||||||||||||||||||
mcs | uint8 | MCS index in [0:7] | ||||||||||||||||||||||||||||||||||||||||
phy_mode | uint8 | PHY mode index, in [1:2] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
ant_mode | uint8 | PHY antenna mode in [0x10, 0x20, 0x30, 0x40] Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
tx_power | int8 | Tx power in dBm | ||||||||||||||||||||||||||||||||||||||||
reserved0 | uint8 | |||||||||||||||||||||||||||||||||||||||||
channel | uint8 | Channel (center frequency) index | ||||||||||||||||||||||||||||||||||||||||
length | uint16 | Length in bytes of MPDU; includes MAC header, payload and FCS | ||||||||||||||||||||||||||||||||||||||||
num_slots | int16 | Number of backoff slots allotted prior to this transmission; may not have been used for initial Tx (attempt_number==1); A value of -1 in this field means no backoff occured | ||||||||||||||||||||||||||||||||||||||||
cw | uint16 | Contention window value at time of this Tx | ||||||||||||||||||||||||||||||||||||||||
pkt_type | uint8 | Packet type, (first frame control byte of 802.11 header) Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
flags | uint8 | 1-bit Flags Constants defined for this field:
| ||||||||||||||||||||||||||||||||||||||||
timestamp_frac | uint8 | Fractional part of Tx timestamp (units of 6.25ns) | ||||||||||||||||||||||||||||||||||||||||
phy_samp_rate | uint8 | PHY Sampling Rate Mode | ||||||||||||||||||||||||||||||||||||||||
attempt_number | uint16 | Transmission index for this attempt, starting at 1 (1 = first Tx) | ||||||||||||||||||||||||||||||||||||||||
reserved1 | uint16 | |||||||||||||||||||||||||||||||||||||||||
mac_payload_len | uint32 | Length in bytes of MAC payload recorded in log for this packet | ||||||||||||||||||||||||||||||||||||||||
mac_payload | 44uint8 | First 44 bytes of MAC payload: the 802.11 MAC header, LLC header, Packet ID, LTG ID | ||||||||||||||||||||||||||||||||||||||||
The following fields are populated when the log entry is part of a numpy array generated via the generate_numpy_array method. These fields are calculated from the underlying bytes in the raw log entries and are stored in more convenient formats tha the raw log fields. For example, these MAC address fields are 48-bit values stored in 64-bit integers. These integer addresses are much easier to use when filtering Tx/Rx log entries using numpy and pandas.
Field Name | Data Type | Description |
|---|---|---|
addr1 | uint64 | MAC Header Address 1 |
addr2 | uint64 | MAC Header Address 2 |
addr3 | uint64 | MAC Header Address 3 |
mac_seq | uint16 | MAC Header Sequence Number |
ltg_uniq_seq | uint64 | Unique sequence number for LTG packet |
ltg_flow_id | uint64 | LTG Flow ID, calculated as:
|
Defining New Entry Types
New log entry formats can be defined to suit a research application. In order to both create log entries and process log data containing the entries, matching log entry type definitions must be added to both the C and Python code.
Entry Types in C
The wlan_exp C code impose simple requirements on log entry formats:
- Each entry type must have a unique ID
- Each use of the entry type should be a multiple of 4 bytes long (32-bit aligned at start and end)
By convention we use C struct definitions to describe the format of entry types. This isn't required, but is very convenient. The reference entry types are defined in wlan_mac_high_framework/include/wlan_mac_entries.h. You can add additional types to this file or elsewhere in the C code. Always ensure new types use entry type IDs that do not conflict with the existing #define ENTRY_TYPE_... values in wlan_mac_entries.h.
After defining your entry type format, new log entries can be created with the void* entry_ptr event_log_get_next_empty_entry( u16 entry_type, u16 entry_size ) function. This function returns a pointer to a memory location dedicated to the new log entry. The calling code must stay within the requested entry_size. This function may return NULL if the log entry cannot be created.
See below for an example custom log entry type.
Entry Types in Python
Log entry types are fully described in Python using instances of the WlanExpLogEntryType class. The reference log entry types are defined in the entry_types.py module. You can add custom entry types to this file or elsewhere in your Python code. The WlanExpLogEntryType constructor will automatically add your custom types to the global dictionary of types.
Defining a new log entry type in Python requires two steps:
- Create an instance of the WlanExpLogEntryType with a unique ID and name:
import wlan_exp.log.entry_types as entry_types my_new_entry_type = entry_types.WlanExpLogEntryType(name='MY_NEW_ENTRY', entry_type_id=1001)
- Add field definitions which describe the log entry format:
my_new_entry_type.append_field_defs([ ('timestamp', 'Q', 'uint64', 'Microsecond timer value at time of log entry creation'), ('val_A', 'I', 'uint32', 'Data Value A'), ('val_B', 'I', 'uint32', 'Data Value B')])
The argument to the append_field_defs method must be a list of 4-tuples. Each 4-tuple must have the format field_name, data_type_struct, data_type_np, description, where:
- field_name: A short string name for the field, preferably all lower case with only letters and underscores
- data_type_struct: String specifying the format for the field using the Python struct module format codes
- data_type_np: String specifying the format for the field using the numpy dtype module format codes
- description: String describing the field, used when auto-generating documentation. Set to empty string ('') to ignore
Common values for the data_type_struct and data_type_np fields are listed below.
| C type | struct type | numpy type |
|---|---|---|
| u8 / unsigned char | B | uint8 |
| u16 / unsigned short | H | uint16 |
| u32 / unsigned int | I | uint32 |
| u64 / unsigned long long | Q | uint64 |
| s8 / signed char | b | int8 |
| s16 / signed short | h | int16 |
| s32 / signed int | i | int32 |
Reference Design Entry Types
The list of log entry types above is auto-generated from the entry_types.py source code in the wlan_exp Python package. You can generate a text version of the entry type list with this code:
from wlan_exp.log.entry_types import log_entry_types as log_entry_types for tid in log_entry_types.keys(): if(type(tid) is int and tid != 0): #only take int type IDs and skip NULL print(log_entry_types[tid].generate_entry_doc(fmt='txt'))
