source: ReferenceDesigns/w3_802.11/c/wlan_mac_high_framework/include/wlan_mac_entries.h

Last change on this file was 6319, checked in by chunter, 3 months ago

1.8.0 release wlan-mac-se

File size: 16.4 KB
RevLine 
[6319]1/** @file wlan_mac_entries.h
2 *  @brief Event log
3 *
4 *  This contains the code for accessing event log.
5 *
6 *  @copyright Copyright 2014-2019, Mango Communications. All rights reserved.
7 *          Distributed under the Mango Communications Reference Design License
8 *              See LICENSE.txt included in the design archive or
9 *              at http://mangocomm.com/802.11/license
10 *
11 *  @note
12 *  This is the only code that the user should modify in order to add entries
13 *  to the event log.  To add a new entry, please follow the template provided
14 *  and create:
15 *    1) A new entry type in wlan_mac_entries.h
16 *    2) Wrapper function:  get_next_empty_*_entry()
17 *    3) Update the print function so that it is easy to print the log to the
18 *    terminal
19 *
20 *  This file is part of the Mango 802.11 Reference Design (https://mangocomm.com/802.11)
21 */
22
23/***************************** Include Files *********************************/
24
25
26
27/*************************** Constant Definitions ****************************/
28#ifndef WLAN_MAC_ENTRIES_H_
29#define WLAN_MAC_ENTRIES_H_
30
31#include "wlan_common_types.h"
32#include "xil_types.h"
33
34#define WLAN_MAC_ENTRIES_LOG_CHAN_EST
35
36// ****************************************************************************
37// Define Entry Constants
38//
39
40//-----------------------------------------------
41// Entry Enable Masks
42
43#define ENTRY_EN_MASK_TXRX_CTRL                            0x01
44#define ENTRY_EN_MASK_TXRX_MPDU                            0x02
45
46//------------------------------------------------------------------------
47// Entry Types
48//
49//     NOTE:  These values must match the definitions in Python WLAN Exp framework.
50//
51
52//-----------------------------------------------
53// Management Entries
54
55#define ENTRY_TYPE_NODE_INFO                               1
56#define ENTRY_TYPE_EXP_INFO                                2
57
58#define ENTRY_TYPE_TEMPERATURE                             4
59
60#define ENTRY_TYPE_TIME_INFO                               6
61
62//-----------------------------------------------
63// Receive Entries
64
65#define ENTRY_TYPE_RX_OFDM                                 10
66#define ENTRY_TYPE_RX_OFDM_LTG                             11
67
68#define ENTRY_TYPE_RX_DSSS                                 15
69
70//-----------------------------------------------
71// Transmit Entries
72
73#define ENTRY_TYPE_TX_HIGH                                 20
74#define ENTRY_TYPE_TX_HIGH_LTG                             21
75
76#define ENTRY_TYPE_TX_LOW                                  25
77#define ENTRY_TYPE_TX_LOW_LTG                              26
78
79
80
81
82//------------------------------------------------------------------------
83// MAC payload length
84//
85//    NOTE:  For normal packets, the minimum payload length must include the MAC header (ie 24 bytes)
86//        so that the log entry is complete.  For LTG packets, the minimum payload length must include
87//        the MAC header, LLC header, and LTG specific fields (ie 44 bytes).  The maximum number of
88//        bytes that should be logged is a standard MTU (ie 1500 bytes).
89//
90#define MIN_MAC_PAYLOAD_LOG_LEN                            24
91#define MIN_MAC_PAYLOAD_LTG_LOG_LEN                        44
92#define MAX_MAC_PAYLOAD_LOG_LEN                            1500
93
94// To never record payloads, you can set the min / max defines as follows:
95//
96//#define MAX_MAC_PAYLOAD_LOG_LEN                          MIN_MAC_PAYLOAD_LOG_LEN
97
98
99
100
101
102/*********************** Global Structure Definitions ************************/
103
104// Forward declarations
105struct tx_frame_info_t;
106struct rx_frame_info_t;
107struct wlan_mac_low_tx_details_t;
108
109//-----------------------------------------------
110// Node Info Entry
111//   NOTE:  This structure is always at the start of the event log.  There is
112//       the methods to add this entry type to the log are in wlan_mac_event_log.*
113//
114//FIXME: I've made changes to this struct that need to be reflected in the Python entry
115typedef struct node_info_entry {
116    u64                     timestamp;                         // Timestamp of the node info
117                                                               //   - This will reflect the oldest time of an
118                                                               //     entry for a given log wrap
119    u64                     wlan_mac_addr;                     // WLAN MAC Address
120    u8                      high_sw_id;                        // ID of CPU_HIGH
121    u8                      low_sw_id;                         // ID of CPU_LOW
122    u16                     padding;
123    u32                     high_sw_config;                    // Configuration of CPU_HIGH
124    u32                     low_sw_config;                     // Configuration of CPU_LOW
125    u32                     node_id;                           // Node ID
126    u32                     platform_id;                       // Platform ID
127    u32                     serial_number;                     // Node serial number
128    u32                     wlan_exp_version;                  // WLAN Exp Version
129    s16                     wlan_max_tx_power_dbm;             // WLAN maximum transmit power (in dBm)
130    s16                     wlan_min_tx_power_dbm;             // WLAN minimum transmit power (in dBm)
131    char                    high_compilation_date[12];
132    char                    high_compilation_time[12];
133    char                    low_compilation_date[12];
134    char                    low_compilation_time[12];
135} __attribute__((__packed__)) node_info_entry;
136ASSERT_TYPE_SIZE(node_info_entry, 96);
137
138//-----------------------------------------------
139// Experiment Info Entry
140//
141// exp_info entries are created by the Python script as needed and provide a
142//  way for the log to contain arbitrary, timestamped messages the Python script
143//  wants to store during an experiment. exp_info entry creation has no affect on
144//  the node configuration or behavior
145typedef struct exp_info_entry {
146    u64                 timestamp;               // Timestamp of the log entry
147    u32                 info_type;               // Type of Experiment Info
148    u32                 msg_len;                 // Length of the experiment info data (in bytes)
149} __attribute__((__packed__)) exp_info_entry;
150ASSERT_TYPE_SIZE(exp_info_entry, 16);
151
152//-----------------------------------------------
153// Temperature Entry
154//   NOTE: The temperature values are copied directly from the system monitor and need
155//         to be converted to Celsius:
156//           celsius = ((double(temp)/65536.0)/0.00198421639) - 273.15;
157//
158// Example request for a new temperature entry:
159//
160//     (temperature_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TEMPERATURE, sizeof(temperature_entry))
161//
162typedef struct temperature_entry {
163    u64                 timestamp;               // Timestamp of the log entry
164    u32                 curr_temp;               // Current Temperature of the node
165    u32                 min_temp;                // Minimum recorded temperature of the node
166    u32                 max_temp;                // Maximum recorded temperature of the node
167} __attribute__((__packed__)) temperature_entry;
168ASSERT_TYPE_SIZE(temperature_entry, 20);
169
170
171
172//-----------------------------------------------
173// Time Info Entry
174//
175// Example request for a new Time info entry:
176//
177//     (time_info_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TIME_INFO, sizeof(time_info_entry))
178//
179typedef struct time_info_entry {
180    u64                 timestamp;               // Timestamp of the log entry (Timestamp of MAC time of old timebase)
181    u32                 time_id;                 // ID of the time info entry so that these entries
182                                                 //   can be synced across multiple nodes
183    u32                 reason;                  // Reason code for log entry:
184                                                 //     0 - SYSTEM (system added time info entry; eg beacon update)
185                                                 //     1 - WLAN_EXP_SET_TIME
186                                                 //     2 - WLAN_EXP_ADD_LOG
187    u64                 mac_timestamp;           // Timestamp of MAC time (new timebase)
188    u64                 system_timestamp;        // Timestamp of System time
189    u64                 host_timestamp;          // Timestamp of Host time          (0xFFFFFFFF_FFFFFFFF if not known)
190} __attribute__((__packed__)) time_info_entry;
191ASSERT_TYPE_SIZE(time_info_entry, 40);
192
193
194#define TIME_INFO_ENTRY_SYSTEM                   0
195#define TIME_INFO_ENTRY_WLAN_EXP_SET_TIME        1
196#define TIME_INFO_ENTRY_WLAN_EXP_ADD_LOG         2
197
198#define TIME_INFO_ENTRY_BASE_SYSTEM_TIME_ID      0x80000000
199
200#define TIME_INFO_ENTRY_TIME_RSVD_VAL_64         0xFFFFFFFFFFFFFFFFULL
201
202
203
204//-----------------------------------------------
205// Common Receive Entry
206//
207typedef struct rx_common_entry {
208    u64                 timestamp;               // Timestamp of the log entry
209    u8                  timestamp_frac;          // Additional fractional timestamp (160MHz clock units)
210    u8                  phy_samp_rate;           // PHY Sampling Rate Mode
211    u16                 length;                  // Length of the received packet
212    u32                 cfo_est;                 // CFO Estimate
213    u8                  mcs;                     // MCS rate at which the packet was received
214    u8                  phy_mode;                // Mode of the PHY when the packet was received
215    u8                  ant_mode;                // Antenna mode of the received packet
216    s8                  power;                   // Power of the received packet
217    u8                  reserved0;
218    u8                  pkt_type;                // Type of packet
219    u8                  chan_num;                // Channel on which the packet was received
220    u8                  reserved1;
221    u8                  rx_gain_index;           // Radio Rx gain index of the received packet
222    u8                  reserved2;
223    u16                 flags;                   // 1-bit flags
224} __attribute__((__packed__)) rx_common_entry;
225ASSERT_TYPE_SIZE(rx_common_entry, 28);
226
227#define RX_FLAGS_FCS_GOOD               0x0001
228#define RX_FLAGS_DUPLICATE              0x0002
229#define RX_FLAGS_UNEXPECTED_RESPONSE    0x0004
230#define RX_FLAGS_LTG_PYLD               0x0040
231#define RX_FLAGS_LTG                    0x0080
232
233
234
235
236
237//-----------------------------------------------
238// Receive OFDM Entry
239//
240//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
241//
242// Example request for a new receive OFDM entry:
243//
244//     (rx_ofdm_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_RX_OFDM, sizeof(rx_ofdm_entry) + extra_payload)
245//
246typedef struct rx_ofdm_entry {
247    rx_common_entry     rx_entry;
248
249#ifdef WLAN_MAC_ENTRIES_LOG_CHAN_EST
250    u32                 channel_est[64];         // Channel estimates for the packet
251#endif
252
253    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
254    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
255} __attribute__((__packed__)) rx_ofdm_entry;
256ASSERT_TYPE_SIZE(rx_ofdm_entry, 312);
257
258
259
260//-----------------------------------------------
261// Receive DSSS Entry
262//
263//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
264//
265// Example request for a new receive DSSS entry:
266//
267//     (rx_dsss_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_RX_DSSS, sizeof(rx_dsss_entry) + extra_payload)
268//
269typedef struct rx_dsss_entry {
270    rx_common_entry     rx_entry;
271    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
272    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
273} __attribute__((__packed__)) rx_dsss_entry;
274ASSERT_TYPE_SIZE(rx_dsss_entry, 56);
275
276
277
278//-----------------------------------------------
279// High-level Transmit Entry
280//   NOTE:  padding field is to have a 32-bit aligned struct.  That way sizeof()
281//          accurately reflects the number of bytes in the struct.
282//
283//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
284//
285// Example request for a new high-level transmit entry:
286//
287//     (tx_high_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TX_HIGH, sizeof(tx_high_entry) + extra_payload)
288//
289typedef struct tx_high_entry {
290    u64                 timestamp_create;        // Timestamp of the log entry creation
291    u32                 delay_accept;            // Delay from timestamp_create to when accepted by CPU Low
292    u32                 delay_done;              // Delay from delay_accept to when CPU Low was done
293    u64                 unique_seq;              // Unique packet sequence number
294    u32                 padding0;
295    u16                 num_tx;                  // Number of Transmissions that it took to send the packet
296    u16                 length;                  // Length of the packet
297    u8                  padding1;
298    u8                  pkt_type;                // Type of packet
299    u16                 queue_id;                // Queue ID this packet was sent from
300    u16                 queue_occupancy;         // Occupancy of queue (includes itself)
301    u16                 flags;                   // 1-bit flags
302    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
303    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
304} __attribute__((__packed__)) tx_high_entry;
305ASSERT_TYPE_SIZE(tx_high_entry, 68);
306
307#define TX_HIGH_FLAGS_SUCCESSFUL 0x0001
308#define TX_HIGH_FLAGS_LTG_PYLD   0x0040
309#define TX_HIGH_FLAGS_LTG        0x0080
310
311//-----------------------------------------------
312// Low-level Transmit Entry
313//   NOTE:  rsvd field is to have a 32-bit aligned struct.  That way sizeof()
314//          accurately reflects the number of bytes in the struct.
315//
316//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
317//
318// Example request for a new low-level transmit entry:
319//
320//     (tx_low_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TX_LOW, sizeof(tx_low_entry))
321//
322typedef struct tx_low_entry{
323    u64                 timestamp_send;          // Timestamp of when packet was sent
324    u64                 unique_seq;              // Unique packet sequence number
325    phy_tx_params_t     phy_params;              // Transmission parameters
326    u8                  reserved0;
327    u8                  chan_num;                // Channel on which this packet was sent
328    u16                 length;                  // Length of the packet
329    s16                 num_slots;               // Number of backoff slots
330    u16                 cw;                      // Contention Window
331    u8                  pkt_type;                // Type of packet
332    u8                  flags;                   // Misc. flags
333    u8                  timestamp_send_frac;     // Additional fractional timestamp (160MHz clock units)
334    u8                  phy_samp_rate;           // PHY Sampling Rate Mode
335    u16                 transmission_count;      // What transmission was this packet
336    u16                 reserved1;
337    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
338    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
339} __attribute__((__packed__)) tx_low_entry;
340ASSERT_TYPE_SIZE(tx_low_entry, 64);
341
342#define TX_LOW_FLAGS_RECEIVED_RESPONSE      0x01
343#define TX_LOW_FLAGS_LTG_PYLD               0x40
344#define TX_LOW_FLAGS_LTG                    0x80
345
346
347
348
349
350/*************************** Function Prototypes *****************************/
351
352u8 wlan_exp_log_get_entry_en_mask();
353void wlan_exp_log_set_entry_en_mask(u8 mask);
354
355void wlan_exp_log_reset_system_time_id();
356
357//-----------------------------------------------
358// Method to get / set the global variable mac_payload_log_len
359//
360u32 wlan_exp_log_get_mac_payload_len();
361void wlan_exp_log_set_mac_payload_len(u32 payload_len);
362
363
364//-----------------------------------------------
365// Wrapper method to get an entry
366//
367void* wlan_exp_log_create_entry(u16 entry_type_id, u16 entry_size);
368
369
370//-----------------------------------------------
371// Methods to create an entry
372//
373tx_high_entry* wlan_exp_log_create_tx_high_entry(struct tx_frame_info_t* tx_frame_info);
374tx_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);
375
376rx_common_entry* wlan_exp_log_create_rx_entry(struct rx_frame_info_t* rx_frame_info);
377
378
379//-----------------------------------------------
380// Methods to add entries to the log
381//
382void add_node_info_entry();
383
384void add_time_info_entry(u64 timestamp, u64 mac_time, u64 system_time, u64 host_time, u32 reason, u32 time_id, u8 use_time_id);
385
386u32 add_temperature_to_log();
387
388#endif /* WLAN_MAC_ENTRIES_H_ */
Note: See TracBrowser for help on using the repository browser.