/** @file wlan_mac_entries.h * @brief Event log * * This contains the code for accessing event log. * * @copyright Copyright 2014-2019, Mango Communications. All rights reserved. * Distributed under the Mango Communications Reference Design License * See LICENSE.txt included in the design archive or * at http://mangocomm.com/802.11/license * * @note * This is the only code that the user should modify in order to add entries * to the event log. To add a new entry, please follow the template provided * and create: * 1) A new entry type in wlan_mac_entries.h * 2) Wrapper function: get_next_empty_*_entry() * 3) Update the print function so that it is easy to print the log to the * terminal * * This file is part of the Mango 802.11 Reference Design (https://mangocomm.com/802.11) */ /***************************** Include Files *********************************/ /*************************** Constant Definitions ****************************/ #ifndef WLAN_MAC_ENTRIES_H_ #define WLAN_MAC_ENTRIES_H_ #include "wlan_common_types.h" #include "xil_types.h" #define WLAN_MAC_ENTRIES_LOG_CHAN_EST // **************************************************************************** // Define Entry Constants // //----------------------------------------------- // Entry Enable Masks #define ENTRY_EN_MASK_TXRX_CTRL 0x01 #define ENTRY_EN_MASK_TXRX_MPDU 0x02 //------------------------------------------------------------------------ // Entry Types // // NOTE: These values must match the definitions in Python WLAN Exp framework. // //----------------------------------------------- // Management Entries #define ENTRY_TYPE_NODE_INFO 1 #define ENTRY_TYPE_EXP_INFO 2 #define ENTRY_TYPE_TEMPERATURE 4 #define ENTRY_TYPE_TIME_INFO 6 //----------------------------------------------- // Receive Entries #define ENTRY_TYPE_RX_OFDM 10 #define ENTRY_TYPE_RX_OFDM_LTG 11 #define ENTRY_TYPE_RX_DSSS 15 //----------------------------------------------- // Transmit Entries #define ENTRY_TYPE_TX_HIGH 20 #define ENTRY_TYPE_TX_HIGH_LTG 21 #define ENTRY_TYPE_TX_LOW 25 #define ENTRY_TYPE_TX_LOW_LTG 26 //------------------------------------------------------------------------ // MAC payload length // // NOTE: For normal packets, the minimum payload length must include the MAC header (ie 24 bytes) // so that the log entry is complete. For LTG packets, the minimum payload length must include // the MAC header, LLC header, and LTG specific fields (ie 44 bytes). The maximum number of // bytes that should be logged is a standard MTU (ie 1500 bytes). // #define MIN_MAC_PAYLOAD_LOG_LEN 24 #define MIN_MAC_PAYLOAD_LTG_LOG_LEN 44 #define MAX_MAC_PAYLOAD_LOG_LEN 1500 // To never record payloads, you can set the min / max defines as follows: // //#define MAX_MAC_PAYLOAD_LOG_LEN MIN_MAC_PAYLOAD_LOG_LEN /*********************** Global Structure Definitions ************************/ // Forward declarations struct tx_frame_info_t; struct rx_frame_info_t; struct wlan_mac_low_tx_details_t; //----------------------------------------------- // Node Info Entry // NOTE: This structure is always at the start of the event log. There is // the methods to add this entry type to the log are in wlan_mac_event_log.* // //FIXME: I've made changes to this struct that need to be reflected in the Python entry typedef struct node_info_entry { u64 timestamp; // Timestamp of the node info // - This will reflect the oldest time of an // entry for a given log wrap u64 wlan_mac_addr; // WLAN MAC Address u8 high_sw_id; // ID of CPU_HIGH u8 low_sw_id; // ID of CPU_LOW u16 padding; u32 high_sw_config; // Configuration of CPU_HIGH u32 low_sw_config; // Configuration of CPU_LOW u32 node_id; // Node ID u32 platform_id; // Platform ID u32 serial_number; // Node serial number u32 wlan_exp_version; // WLAN Exp Version s16 wlan_max_tx_power_dbm; // WLAN maximum transmit power (in dBm) s16 wlan_min_tx_power_dbm; // WLAN minimum transmit power (in dBm) char high_compilation_date[12]; char high_compilation_time[12]; char low_compilation_date[12]; char low_compilation_time[12]; } __attribute__((__packed__)) node_info_entry; ASSERT_TYPE_SIZE(node_info_entry, 96); //----------------------------------------------- // Experiment Info Entry // // exp_info entries are created by the Python script as needed and provide a // way for the log to contain arbitrary, timestamped messages the Python script // wants to store during an experiment. exp_info entry creation has no affect on // the node configuration or behavior typedef struct exp_info_entry { u64 timestamp; // Timestamp of the log entry u32 info_type; // Type of Experiment Info u32 msg_len; // Length of the experiment info data (in bytes) } __attribute__((__packed__)) exp_info_entry; ASSERT_TYPE_SIZE(exp_info_entry, 16); //----------------------------------------------- // Temperature Entry // NOTE: The temperature values are copied directly from the system monitor and need // to be converted to Celsius: // celsius = ((double(temp)/65536.0)/0.00198421639) - 273.15; // // Example request for a new temperature entry: // // (temperature_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TEMPERATURE, sizeof(temperature_entry)) // typedef struct temperature_entry { u64 timestamp; // Timestamp of the log entry u32 curr_temp; // Current Temperature of the node u32 min_temp; // Minimum recorded temperature of the node u32 max_temp; // Maximum recorded temperature of the node } __attribute__((__packed__)) temperature_entry; ASSERT_TYPE_SIZE(temperature_entry, 20); //----------------------------------------------- // Time Info Entry // // Example request for a new Time info entry: // // (time_info_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TIME_INFO, sizeof(time_info_entry)) // typedef struct time_info_entry { u64 timestamp; // Timestamp of the log entry (Timestamp of MAC time of old timebase) u32 time_id; // ID of the time info entry so that these entries // can be synced across multiple nodes u32 reason; // Reason code for log entry: // 0 - SYSTEM (system added time info entry; eg beacon update) // 1 - WLAN_EXP_SET_TIME // 2 - WLAN_EXP_ADD_LOG u64 mac_timestamp; // Timestamp of MAC time (new timebase) u64 system_timestamp; // Timestamp of System time u64 host_timestamp; // Timestamp of Host time (0xFFFFFFFF_FFFFFFFF if not known) } __attribute__((__packed__)) time_info_entry; ASSERT_TYPE_SIZE(time_info_entry, 40); #define TIME_INFO_ENTRY_SYSTEM 0 #define TIME_INFO_ENTRY_WLAN_EXP_SET_TIME 1 #define TIME_INFO_ENTRY_WLAN_EXP_ADD_LOG 2 #define TIME_INFO_ENTRY_BASE_SYSTEM_TIME_ID 0x80000000 #define TIME_INFO_ENTRY_TIME_RSVD_VAL_64 0xFFFFFFFFFFFFFFFFULL //----------------------------------------------- // Common Receive Entry // typedef struct rx_common_entry { u64 timestamp; // Timestamp of the log entry u8 timestamp_frac; // Additional fractional timestamp (160MHz clock units) u8 phy_samp_rate; // PHY Sampling Rate Mode u16 length; // Length of the received packet u32 cfo_est; // CFO Estimate u8 mcs; // MCS rate at which the packet was received u8 phy_mode; // Mode of the PHY when the packet was received u8 ant_mode; // Antenna mode of the received packet s8 power; // Power of the received packet u8 reserved0; u8 pkt_type; // Type of packet u8 chan_num; // Channel on which the packet was received u8 reserved1; u8 rx_gain_index; // Radio Rx gain index of the received packet u8 reserved2; u16 flags; // 1-bit flags } __attribute__((__packed__)) rx_common_entry; ASSERT_TYPE_SIZE(rx_common_entry, 28); #define RX_FLAGS_FCS_GOOD 0x0001 #define RX_FLAGS_DUPLICATE 0x0002 #define RX_FLAGS_UNEXPECTED_RESPONSE 0x0004 #define RX_FLAGS_LTG_PYLD 0x0040 #define RX_FLAGS_LTG 0x0080 //----------------------------------------------- // Receive OFDM Entry // // NOTE: Entry mac_payload stored as u32 array to preserve alignment. // // Example request for a new receive OFDM entry: // // (rx_ofdm_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_RX_OFDM, sizeof(rx_ofdm_entry) + extra_payload) // typedef struct rx_ofdm_entry { rx_common_entry rx_entry; #ifdef WLAN_MAC_ENTRIES_LOG_CHAN_EST u32 channel_est[64]; // Channel estimates for the packet #endif u32 mac_payload_log_len; // Number of payload bytes actually recorded in log entry u32 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4]; } __attribute__((__packed__)) rx_ofdm_entry; ASSERT_TYPE_SIZE(rx_ofdm_entry, 312); //----------------------------------------------- // Receive DSSS Entry // // NOTE: Entry mac_payload stored as u32 array to preserve alignment. // // Example request for a new receive DSSS entry: // // (rx_dsss_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_RX_DSSS, sizeof(rx_dsss_entry) + extra_payload) // typedef struct rx_dsss_entry { rx_common_entry rx_entry; u32 mac_payload_log_len; // Number of payload bytes actually recorded in log entry u32 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4]; } __attribute__((__packed__)) rx_dsss_entry; ASSERT_TYPE_SIZE(rx_dsss_entry, 56); //----------------------------------------------- // High-level Transmit Entry // NOTE: padding field is to have a 32-bit aligned struct. That way sizeof() // accurately reflects the number of bytes in the struct. // // NOTE: Entry mac_payload stored as u32 array to preserve alignment. // // Example request for a new high-level transmit entry: // // (tx_high_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TX_HIGH, sizeof(tx_high_entry) + extra_payload) // typedef struct tx_high_entry { u64 timestamp_create; // Timestamp of the log entry creation u32 delay_accept; // Delay from timestamp_create to when accepted by CPU Low u32 delay_done; // Delay from delay_accept to when CPU Low was done u64 unique_seq; // Unique packet sequence number u32 padding0; u16 num_tx; // Number of Transmissions that it took to send the packet u16 length; // Length of the packet u8 padding1; u8 pkt_type; // Type of packet u16 queue_id; // Queue ID this packet was sent from u16 queue_occupancy; // Occupancy of queue (includes itself) u16 flags; // 1-bit flags u32 mac_payload_log_len; // Number of payload bytes actually recorded in log entry u32 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4]; } __attribute__((__packed__)) tx_high_entry; ASSERT_TYPE_SIZE(tx_high_entry, 68); #define TX_HIGH_FLAGS_SUCCESSFUL 0x0001 #define TX_HIGH_FLAGS_LTG_PYLD 0x0040 #define TX_HIGH_FLAGS_LTG 0x0080 //----------------------------------------------- // Low-level Transmit Entry // NOTE: rsvd field is to have a 32-bit aligned struct. That way sizeof() // accurately reflects the number of bytes in the struct. // // NOTE: Entry mac_payload stored as u32 array to preserve alignment. // // Example request for a new low-level transmit entry: // // (tx_low_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TX_LOW, sizeof(tx_low_entry)) // typedef struct tx_low_entry{ u64 timestamp_send; // Timestamp of when packet was sent u64 unique_seq; // Unique packet sequence number phy_tx_params_t phy_params; // Transmission parameters u8 reserved0; u8 chan_num; // Channel on which this packet was sent u16 length; // Length of the packet s16 num_slots; // Number of backoff slots u16 cw; // Contention Window u8 pkt_type; // Type of packet u8 flags; // Misc. flags u8 timestamp_send_frac; // Additional fractional timestamp (160MHz clock units) u8 phy_samp_rate; // PHY Sampling Rate Mode u16 transmission_count; // What transmission was this packet u16 reserved1; u32 mac_payload_log_len; // Number of payload bytes actually recorded in log entry u32 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4]; } __attribute__((__packed__)) tx_low_entry; ASSERT_TYPE_SIZE(tx_low_entry, 64); #define TX_LOW_FLAGS_RECEIVED_RESPONSE 0x01 #define TX_LOW_FLAGS_LTG_PYLD 0x40 #define TX_LOW_FLAGS_LTG 0x80 /*************************** Function Prototypes *****************************/ u8 wlan_exp_log_get_entry_en_mask(); void wlan_exp_log_set_entry_en_mask(u8 mask); void wlan_exp_log_reset_system_time_id(); //----------------------------------------------- // Method to get / set the global variable mac_payload_log_len // u32 wlan_exp_log_get_mac_payload_len(); void wlan_exp_log_set_mac_payload_len(u32 payload_len); //----------------------------------------------- // Wrapper method to get an entry // void* wlan_exp_log_create_entry(u16 entry_type_id, u16 entry_size); //----------------------------------------------- // Methods to create an entry // tx_high_entry* wlan_exp_log_create_tx_high_entry(struct tx_frame_info_t* tx_frame_info); tx_low_entry* wlan_exp_log_create_tx_low_entry(struct tx_frame_info_t* tx_frame_info, struct wlan_mac_low_tx_details_t* tx_low_details); rx_common_entry* wlan_exp_log_create_rx_entry(struct rx_frame_info_t* rx_frame_info); //----------------------------------------------- // Methods to add entries to the log // void add_node_info_entry(); void add_time_info_entry(u64 timestamp, u64 mac_time, u64 system_time, u64 host_time, u32 reason, u32 time_id, u8 use_time_id); u32 add_temperature_to_log(); #endif /* WLAN_MAC_ENTRIES_H_ */