wiki:802.11/wlan_exp/log/entry_types

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:

Name Value
AP_DCF 0x10101
AP_NOMAC 0x10102
IBSS_DCF 0x10301
STA_NOMAC 0x10202
IBSS_NOMAC 0x10302
STA_DCF 0x10201

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:

Name Value
SYSTEM 0x0
WLAN_EXP_SET_TIME 0x1
WLAN_EXP_ADD_LOG 0x2

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:

Name Value
NONHT 0x1
HTMF 0x2
DSSS 0x0

ant_mode

uint8

Antenna mode: [1,2,3,4] for SISO Rx on RF [A,B,C,D]

Constants defined for this field:

Name Value
RF_A 0x1
RF_C 0x3
RF_B 0x2
RF_D 0x4

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

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:

Name Value
FCS_GOOD 0x1
DUPLICATE 0x2
LTG_PYLD 0x40
LTG 0x80
UNEXPECTED_RESPONSE 0x4

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:

Name Value
NONHT 0x1
HTMF 0x2
DSSS 0x0

ant_mode

uint8

Antenna mode: [1,2,3,4] for SISO Rx on RF [A,B,C,D]

Constants defined for this field:

Name Value
RF_A 0x1
RF_C 0x3
RF_B 0x2
RF_D 0x4

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

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:

Name Value
FCS_GOOD 0x1
DUPLICATE 0x2
LTG_PYLD 0x40
LTG 0x80
UNEXPECTED_RESPONSE 0x4

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:

16LSB: LTG instance ID 48MSB: Destination MAC address


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:

Name Value
NONHT 0x1
HTMF 0x2
DSSS 0x0

ant_mode

uint8

Antenna mode: [1,2,3,4] for SISO Rx on RF [A,B,C,D]

Constants defined for this field:

Name Value
RF_A 0x1
RF_C 0x3
RF_B 0x2
RF_D 0x4

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

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:

Name Value
FCS_GOOD 0x1
DUPLICATE 0x2
LTG_PYLD 0x40
LTG 0x80
UNEXPECTED_RESPONSE 0x4

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

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:

Name Value
SUCCESSFUL 0x1
LTG_PYLD 0x40
LTG 0x80

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

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:

Name Value
SUCCESSFUL 0x1
LTG_PYLD 0x40
LTG 0x80

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:

16LSB: LTG instance ID 48MSB: Destination MAC address


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:

Name Value
NONHT 0x1
HTMF 0x2
DSSS 0x0

ant_mode

uint8

PHY antenna mode in [0x10, 0x20, 0x30, 0x40]

Constants defined for this field:

Name Value
RF_A 0x10
RF_C 0x30
RF_B 0x20
RF_D 0x40

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

flags

uint8

1-bit Flags

Constants defined for this field:

Name Value
RECEIVED_RESPONSE 0x1
LTG_PYLD 0x80
LTG 0x40

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:

Name Value
NONHT 0x1
HTMF 0x2
DSSS 0x0

ant_mode

uint8

PHY antenna mode in [0x10, 0x20, 0x30, 0x40]

Constants defined for this field:

Name Value
RF_A 0x10
RF_C 0x30
RF_B 0x20
RF_D 0x40

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:

Name Value
DEAUTH 0xC0
BLOCK_ACK 0x94
CTS 0xC4
ACK 0xD4
AUTH 0xB0
BEACON 0x80
DISASSOC 0xA0
NULLDATA 0x48
REASSOC_REQ 0x20
DATA 0x8
BLOCK_ACK_REQ 0x84
PROBE_REQ 0x40
PROBE_RESP 0x50
QOSDATA 0x88
REASSOC_RESP 0x30
ASSOC_RESP 0x10
ASSOC_REQ 0x0
RTS 0xB4
ACTION 0xD0

flags

uint8

1-bit Flags

Constants defined for this field:

Name Value
RECEIVED_RESPONSE 0x1
LTG_PYLD 0x80
LTG 0x40

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:

16LSB: LTG instance ID 48MSB: Destination MAC address

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:

  1. 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)
    
  2. 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'))
Last modified 7 years ago Last modified on Jan 12, 2017, 1:58:20 PM