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

Last change on this file was 6225, checked in by chunter, 11 months ago

updated year in comments

File size: 16.7 KB
Line 
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-2018, 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 was designed to work easily with the WLAN Exp Tag
112//       Parameters.  The order and size of the fields match the corresponding
113//       Tag Parameter so that population of this structure is easy.  Please see
114//       "Node Info Structure for Tag Parameter Information" in wlan_exp_node.h
115//       for the corresponding structure that populates this entry.
116//
117//   NOTE:  This structure is always at the start of the event log.  There is
118//       the methods to add this entry type to the log are in wlan_mac_event_log.*
119//
120typedef struct node_info_entry{
121    u64                     timestamp;                         // Timestamp of the node info
122                                                               //   - This will reflect the oldest time of an
123                                                               //     entry for a given log wrap
124    u32                     node_type;                         // Node type
125    u32                     node_id;                           // Node ID
126    u32                     hw_generation;                     // Node hardware generation
127    u32                     serial_number;                     // Node serial number
128    u64                     fpga_dna;                          // Node FPGA DNA
129    u32                     wlan_exp_version;                  // WLAN Exp Version
130    u32                     wlan_scheduler_resolution;         // Minimum Scheduler resolution (microseconds)
131    u32                     wlan_mac_addr[2];                  // WLAN MAC Address
132    int                     wlan_max_tx_power_dbm;             // WLAN maximum transmit power (in dBm)
133    int                     wlan_min_tx_power_dbm;             // WLAN minimum transmit power (in dBm)
134    compilation_details_t   cpu_high_compilation_details;
135    compilation_details_t   cpu_low_compilation_details;
136} node_info_entry;
137
138
139
140//-----------------------------------------------
141// Experiment Info Entry
142//
143// NOTE:  When creating this entry, you need to allocate the size of the entry
144//   plus the (info_length - 4).  For example:
145//
146//    (exp_info_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_EXP_INFO, (sizeof(exp_info_entry) + size - 4))
147//
148// NOTE:  The longest Experiment Info is:  ((2^16 - 1) - (sizeof(exp_info_entry) - 4)) bytes
149//
150typedef struct exp_info_entry{
151    u64                 timestamp;               // Timestamp of the log entry
152    u16                 info_type;               // Type of Experiment Info
153    u16                 info_length;             // Length of the experiment info data (in bytes)
154    u8                  info_payload[4];         // Reference to payload contents for easy access in C
155                                                 //   You can treat this array as the first 4 bytes of
156                                                 //   the info payload but the array is actually valid
157                                                 //   for info_length bytes.
158} exp_info_entry;
159
160
161
162//-----------------------------------------------
163// Temperature Entry
164//   NOTE: The temperature values are copied directly from the system monitor and need
165//         to be converted to Celsius:
166//           celsius = ((double(temp)/65536.0)/0.00198421639) - 273.15;
167//
168// Example request for a new temperature entry:
169//
170//     (temperature_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TEMPERATURE, sizeof(temperature_entry))
171//
172typedef struct temperature_entry{
173    u64                 timestamp;               // Timestamp of the log entry
174    u32                 curr_temp;               // Current Temperature of the node
175    u32                 min_temp;                // Minimum recorded temperature of the node
176    u32                 max_temp;                // Maximum recorded temperature of the node
177} temperature_entry;
178
179
180
181//-----------------------------------------------
182// Time Info Entry
183//
184// Example request for a new Time info entry:
185//
186//     (time_info_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TIME_INFO, sizeof(time_info_entry))
187//
188typedef struct time_info_entry{
189    u64                 timestamp;               // Timestamp of the log entry (Timestamp of MAC time of old timebase)
190    u32                 time_id;                 // ID of the time info entry so that these entries
191                                                 //   can be synced across multiple nodes
192    u32                 reason;                  // Reason code for log entry:
193                                                 //     0 - SYSTEM (system added time info entry; eg beacon update)
194                                                 //     1 - WLAN_EXP_SET_TIME
195                                                 //     2 - WLAN_EXP_ADD_LOG
196    u64                 mac_timestamp;           // Timestamp of MAC time (new timebase)
197    u64                 system_timestamp;        // Timestamp of System time
198    u64                 host_timestamp;          // Timestamp of Host time          (0xFFFFFFFF_FFFFFFFF if not known)
199} time_info_entry;
200
201
202#define TIME_INFO_ENTRY_SYSTEM                   0
203#define TIME_INFO_ENTRY_WLAN_EXP_SET_TIME        1
204#define TIME_INFO_ENTRY_WLAN_EXP_ADD_LOG         2
205
206#define TIME_INFO_ENTRY_BASE_SYSTEM_TIME_ID      0x80000000
207
208#define TIME_INFO_ENTRY_TIME_RSVD_VAL_64         0xFFFFFFFFFFFFFFFFULL
209
210
211
212//-----------------------------------------------
213// Common Receive Entry
214//
215typedef struct rx_common_entry{
216    u64                 timestamp;               // Timestamp of the log entry
217    u8                  timestamp_frac;          // Additional fractional timestamp (160MHz clock units)
218    u8                  phy_samp_rate;           // PHY Sampling Rate Mode
219    u16                 length;                  // Length of the received packet
220    u32                 cfo_est;                 // CFO Estimate
221    u8                  mcs;                     // MCS rate at which the packet was received
222    u8                  phy_mode;                // Mode of the PHY when the packet was received
223    u8                  ant_mode;                // Antenna mode of the received packet
224    s8                  power;                   // Power of the received packet
225    u8                  reserved0;
226    u8                  pkt_type;                // Type of packet
227    u8                  chan_num;                // Channel on which the packet was received
228    u8                  reserved1;
229    u8                  rx_gain_index;           // Radio Rx gain index of the received packet
230    u8                  reserved2;
231    u16                 flags;                   // 1-bit flags
232} rx_common_entry;
233#define RX_FLAGS_FCS_GOOD               0x0001
234#define RX_FLAGS_DUPLICATE              0x0002
235#define RX_FLAGS_UNEXPECTED_RESPONSE    0x0004
236#define RX_FLAGS_LTG_PYLD               0x0040
237#define RX_FLAGS_LTG                    0x0080
238
239
240
241
242
243//-----------------------------------------------
244// Receive OFDM Entry
245//
246//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
247//
248// Example request for a new receive OFDM entry:
249//
250//     (rx_ofdm_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_RX_OFDM, sizeof(rx_ofdm_entry) + extra_payload)
251//
252typedef struct rx_ofdm_entry{
253    rx_common_entry     rx_entry;
254
255#ifdef WLAN_MAC_ENTRIES_LOG_CHAN_EST
256    u32                 channel_est[64];         // Channel estimates for the packet
257#endif
258
259    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
260    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
261} rx_ofdm_entry;
262
263
264
265//-----------------------------------------------
266// Receive DSSS Entry
267//
268//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
269//
270// Example request for a new receive DSSS entry:
271//
272//     (rx_dsss_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_RX_DSSS, sizeof(rx_dsss_entry) + extra_payload)
273//
274typedef struct rx_dsss_entry{
275    rx_common_entry     rx_entry;
276    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
277    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
278} rx_dsss_entry;
279
280
281
282//-----------------------------------------------
283// High-level Transmit Entry
284//   NOTE:  padding field is to have a 32-bit aligned struct.  That way sizeof()
285//          accurately reflects the number of bytes in the struct.
286//
287//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
288//
289// Example request for a new high-level transmit entry:
290//
291//     (tx_high_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TX_HIGH, sizeof(tx_high_entry) + extra_payload)
292//
293typedef struct tx_high_entry{
294    u64                 timestamp_create;        // Timestamp of the log entry creation
295    u32                 delay_accept;            // Delay from timestamp_create to when accepted by CPU Low
296    u32                 delay_done;              // Delay from delay_accept to when CPU Low was done
297    u64                 unique_seq;              // Unique packet sequence number
298    u32                 padding0;
299    u16                 num_tx;                  // Number of Transmissions that it took to send the packet
300    u16                 length;                  // Length of the packet
301    u8                  padding1;
302    u8                  pkt_type;                // Type of packet
303    u16                 queue_id;                // Queue ID this packet was sent from
304    u16                 queue_occupancy;         // Occupancy of queue (includes itself)
305    u16                 flags;                   // 1-bit flags
306    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
307    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
308} tx_high_entry;
309
310#define TX_HIGH_FLAGS_SUCCESSFUL 0x0001
311#define TX_HIGH_FLAGS_LTG_PYLD   0x0040
312#define TX_HIGH_FLAGS_LTG        0x0080
313
314//-----------------------------------------------
315// Low-level Transmit Entry
316//   NOTE:  rsvd field is to have a 32-bit aligned struct.  That way sizeof()
317//          accurately reflects the number of bytes in the struct.
318//
319//   NOTE:  Entry mac_payload stored as u32 array to preserve alignment.
320//
321// Example request for a new low-level transmit entry:
322//
323//     (tx_low_entry *) wlan_exp_log_create_entry(ENTRY_TYPE_TX_LOW, sizeof(tx_low_entry))
324//
325typedef struct tx_low_entry{
326    u64                 timestamp_send;          // Timestamp of when packet was sent
327    u64                 unique_seq;              // Unique packet sequence number
328    phy_tx_params_t     phy_params;              // Transmission parameters
329    u8                  reserved0;
330    u8                  chan_num;                // Channel on which this packet was sent
331    u16                 length;                  // Length of the packet
332    s16                 num_slots;               // Number of backoff slots
333    u16                 cw;                      // Contention Window
334    u8                  pkt_type;                // Type of packet
335    u8                  flags;                   // Misc. flags
336    u8                  timestamp_send_frac;     // Additional fractional timestamp (160MHz clock units)
337    u8                  phy_samp_rate;           // PHY Sampling Rate Mode
338    u16                 transmission_count;      // What transmission was this packet
339    u16                 reserved1;
340    u32                 mac_payload_log_len;     // Number of payload bytes actually recorded in log entry
341    u32                 mac_payload[MIN_MAC_PAYLOAD_LOG_LEN/4];
342} tx_low_entry;
343#define TX_LOW_FLAGS_RECEIVED_RESPONSE      0x01
344#define TX_LOW_FLAGS_LTG_PYLD               0x40
345#define TX_LOW_FLAGS_LTG                    0x80
346
347
348
349
350
351/*************************** Function Prototypes *****************************/
352
353u8 wlan_exp_log_get_entry_en_mask();
354void wlan_exp_log_set_entry_en_mask(u8 mask);
355
356void wlan_exp_log_reset_system_time_id();
357
358//-----------------------------------------------
359// Method to get / set the global variable mac_payload_log_len
360//
361u32 wlan_exp_log_get_mac_payload_len();
362void wlan_exp_log_set_mac_payload_len(u32 payload_len);
363
364
365//-----------------------------------------------
366// Wrapper method to get an entry
367//
368void* wlan_exp_log_create_entry(u16 entry_type_id, u16 entry_size);
369
370
371//-----------------------------------------------
372// Methods to create an entry
373//
374tx_high_entry* wlan_exp_log_create_tx_high_entry(struct tx_frame_info_t* tx_frame_info);
375tx_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);
376
377rx_common_entry* wlan_exp_log_create_rx_entry(struct rx_frame_info_t* rx_frame_info);
378
379//-----------------------------------------------
380// Print function for all entries
381//
382#ifdef _DEBUG_
383void               print_entry(u32 entry_number, u32 entry_type, void * entry);
384#endif
385
386
387//-----------------------------------------------
388// Methods to add entries to the log
389//
390void add_node_info_entry();
391
392void add_time_info_entry(u64 timestamp, u64 mac_time, u64 system_time, u64 host_time, u32 reason, u32 time_id, u8 use_time_id);
393
394u32 add_temperature_to_log();
395
396#endif /* WLAN_MAC_ENTRIES_H_ */
Note: See TracBrowser for help on using the repository browser.