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

Last change on this file was 6319, checked in by chunter, 6 years ago

1.8.0 release wlan-mac-se
File size: 15.2 KB
Line 
1/** @file wlan_mac_high.h
2 *  @brief Top-level WLAN MAC High Framework
3 *
4 *  This contains the top-level code for accessing the WLAN MAC High Framework.
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 *  This file is part of the Mango 802.11 Reference Design (https://mangocomm.com/802.11)
12 */
13
14
15/*************************** Constant Definitions ****************************/
16#ifndef WLAN_MAC_HIGH_H_
17#define WLAN_MAC_HIGH_H_
18
19#include "wlan_mac_high_sw_config.h"
20#include "xil_types.h"
21#include "wlan_common_types.h"
22#include "wlan_high_types.h"
23
24// Forward declarations
25struct mac_header_80211_common;
26struct wlan_ipc_msg_t;
27struct beacon_txrx_configure_t;
28struct network_info_t;
29enum userio_input_mask_t;
30struct station_info_t;
31struct tx_queue_buffer_t;
32
33/********************************************************************
34 * Auxiliary (AUX) BRAM and DRAM (DDR) Memory Maps
35
36 * The 802.11 Reference Design hardware includes a 64 KB BRAM block named
37 * AUX BRAM. This block is mapped into the address space of CPU High
38 * and provides a low-latency memory block for data storage beyond the
39 * DLMB. The AUX BRAM is also accessible by the Ethernet DMAs and CDMA (the
40 * DMAs cannot access the MicroBlaze DLMB memory area).
41 *
42 * The reference code uses the AUX BRAM to store various data structures
43 * that provides references to larger blocks in DRAM. These data structures
44 * benefit from the low-latency access of the BRAM block.
45 *
46 * For example, the doubly-linked list of Tx Queue entries is stored in the
47 * AUX BRAM. Each list entry points to a dedicated 4KB buffer in DRAM. The C code
48 * can manage a queue with quick list operations in BRAM while the queued packets
49 * themselves are stored in the slower but *much* larger DRAM.
50 *
51 * The 64 KB AUX BRAM block is divided as follows:
52 *
53 * ***************************** AUX BRAM Map *********************************************
54 * Description                                            | Size
55 * -------------------------------------------------------------------------------------------------
56 * Tx Queue list entries (entry.data points to DRAM)      | 40960 B (QUEUE_DL_ENTRY_MEM_SIZE)
57 * BSS Info list entries (entry.data points to DRAM)      |  2560 B (BSS_INFO_DL_ENTRY_MEM_SIZE)
58 * Station Info list entries (entry.data points to DRAM)  |  6656 B (STATION_INFO_DL_ENTRY_MEM_SIZE)
59 * Space for wlan_platform_ethernet use                   | 15360 B (ETH_MEM_SIZE)
60 * -------------------------------------------------------------------------------------------------
61 *
62 * DRAM is mapped into the address space of CPU High.
63 * This memory space is used as follows:
64 *
65 * ******************************* DRAM Map *********************************************************
66 * Description                      | Size
67 * --------------------------------------------------------------------------------------------------
68 * wlan_exp Eth buffers             |    1024 KB (WLAN_EXP_ETH_BUFFERS_SECTION_SIZE)
69 * Tx queue buffers                 |    1400 KB (QUEUE_BUFFER_SIZE)
70 * BSS Info buffers                 |      27 KB (BSS_INFO_BUFFER_SIZE)
71 * Station Info buffers             |      69 KB (STATION_INFO_BUFFER_SIZE)
72 * User scratch space               |   10000 KB (USER_SCRATCH_SIZE)
73 * Event log                        | 1036056 KB (EVENT_LOG_SIZE)
74 * --------------------------------------------------------------------------------------------------
75 *
76 * Platform must define:
77 *  AUX_BRAM_BASEADDR - base address of AUX BRAM
78 *  AUX_BRAM_HIGHADDR - high address of AUX BRAM
79 *
80 *  DRAM_BASEADDR - base address of DRAM
81 *  DRAM_HIGHADDR - high address of DRAM
82 *
83 *  The per-section macros below are derived from these AUX_BRAM and DRAM address macros.
84 *
85 ************************************************************************************************/
86
87
88/********************************************************************
89 * wlan_exp and IP/UDP library Ethernet buffers
90 *
91 * The wlan_exp Ethernet handling code uses large buffers for constructing packets
92 * for transmission and for processing received packets. The IP/UDP library uses
93 * multiple buffers to pipeline Ethernet operations. The library also supports jumbo
94 * frames. As a result the wlan_exp and IP/UDP library Ethernet buffers are too large
95 * to store in on-chip BRAM. Instead the first 1MB of the DRAM is reserved for use
96 * by the wlan_exp Ethernet code.
97 *
98 * The linker script for CPU High *must* include a dedicated section allocated at the
99 * base of the DRAM address range. The macros below assume this section exist and
100 * are used to verify the wlan_exp and IP/UDP library code does not overflow the
101 * DRAM allocation.
102 *
103 ********************************************************************/
104#define WLAN_EXP_ETH_BUFFERS_SECTION_BASE   (platform_high_dev_info.dram_baseaddr)
105#define WLAN_EXP_ETH_BUFFERS_SECTION_SIZE   (1024 * 1024)
106#define WLAN_EXP_ETH_BUFFERS_SECTION_HIGH   CALC_MEM_HIGH_ADDR(WLAN_EXP_ETH_BUFFERS_SECTION_BASE, WLAN_EXP_ETH_BUFFERS_SECTION_SIZE)
107
108
109/********************************************************************
110 * TX Queue
111 *
112 * The Tx Queue consists of two pieces:
113 *     (1) dl_entry structs that live in the AUX BRAM
114 *     (2) Data buffers for the packets themselves than live in DRAM
115 *
116 * The definitions below reserve memory for these two pieces.  The default
117 * value of 40 kB do the dl_entry memory space was chosen. Because each dl_entry has a
118 * size of 12 bytes, this space allows for a potential of 3413 dl_entry structs describing
119 * Tx queue elements.
120 *
121 * As far as the actual payload space in DRAM, 14000 kB was chosen because this is enough
122 * to store each of the 3413 Tx queue elements. Each queue element points to a unique 4KB-sized
123 * buffer.
124 *
125 ********************************************************************/
126
127#define QUEUE_DL_ENTRY_MEM_BASE         (platform_high_dev_info.aux_bram_baseaddr)
128#define QUEUE_DL_ENTRY_MEM_SIZE         (40 * 1024)
129#define TX_QUEUE_DL_ENTRY_MEM_HIGH          CALC_MEM_HIGH_ADDR(QUEUE_DL_ENTRY_MEM_BASE, QUEUE_DL_ENTRY_MEM_SIZE)
130
131#define QUEUE_BUFFER_BASE               (WLAN_EXP_ETH_BUFFERS_SECTION_HIGH + 1)
132#define QUEUE_BUFFER_SIZE               (14000 * 1024)
133#define TX_QUEUE_BUFFER_HIGH                CALC_MEM_HIGH_ADDR(QUEUE_BUFFER_BASE, QUEUE_BUFFER_SIZE)
134
135
136
137/********************************************************************
138 * BSS Info
139 *
140 * The BSS Info storage consists of two pieces:
141 *     (1) dl_entry structs that live in the aux. BRAM and
142 *     (2) network_info_t buffers with the actual content that live in DRAM
143 *
144 ********************************************************************/
145#define BSS_INFO_DL_ENTRY_MEM_BASE         (QUEUE_DL_ENTRY_MEM_BASE + QUEUE_DL_ENTRY_MEM_SIZE)
146#define BSS_INFO_DL_ENTRY_MEM_SIZE         (2560)
147#define BSS_INFO_DL_ENTRY_MEM_HIGH          CALC_MEM_HIGH_ADDR(BSS_INFO_DL_ENTRY_MEM_BASE, BSS_INFO_DL_ENTRY_MEM_SIZE)
148
149#define BSS_INFO_BUFFER_BASE               (TX_QUEUE_BUFFER_HIGH + 1)
150#define BSS_INFO_BUFFER_SIZE               ((BSS_INFO_DL_ENTRY_MEM_SIZE/sizeof(dl_entry))*sizeof(network_info_t))
151#define BSS_INFO_BUFFER_HIGH                CALC_MEM_HIGH_ADDR(BSS_INFO_BUFFER_BASE, BSS_INFO_BUFFER_SIZE)
152
153
154/********************************************************************
155 * Station Info
156 *
157 * The Station Info storage consists of two pieces:
158 *     (1) dl_entry structs that live in the aux. BRAM and
159 *     (2) station_info_t buffers with the actual content that live in DRAM
160 *
161 ********************************************************************/
162#define STATION_INFO_DL_ENTRY_MEM_BASE     (BSS_INFO_DL_ENTRY_MEM_HIGH + 1)
163#define STATION_INFO_DL_ENTRY_MEM_SIZE     (6656)
164#define STATION_INFO_DL_ENTRY_MEM_NUM      (STATION_INFO_DL_ENTRY_MEM_SIZE/sizeof(dl_entry))
165#define STATION_INFO_DL_ENTRY_MEM_HIGH      CALC_MEM_HIGH_ADDR(STATION_INFO_DL_ENTRY_MEM_BASE, STATION_INFO_DL_ENTRY_MEM_SIZE)
166
167#define STATION_INFO_BUFFER_BASE          (BSS_INFO_BUFFER_HIGH + 1)
168#define STATION_INFO_BUFFER_SIZE          ((STATION_INFO_DL_ENTRY_MEM_SIZE/sizeof(dl_entry))*sizeof(station_info_t))
169#define STATION_INFO_BUFFER_HIGH           CALC_MEM_HIGH_ADDR(STATION_INFO_BUFFER_BASE, STATION_INFO_BUFFER_SIZE)
170
171/********************************************************************
172 * User Scratch Space
173 *
174 * We have set aside 10MB of space for users to use the DRAM in their applications.
175 * We do not use the below definitions in any part of the reference design.
176 *
177 ********************************************************************/
178#define USER_SCRATCH_BASE                  (STATION_INFO_BUFFER_HIGH + 1)
179#define USER_SCRATCH_SIZE                  (10000 * 1024)
180#define USER_SCRATCH_HIGH                   CALC_MEM_HIGH_ADDR(USER_SCRATCH_BASE, USER_SCRATCH_SIZE)
181
182
183/********************************************************************
184 * Event Log
185 *
186 * The remaining space in DRAM is used for the WLAN Experiment Framework event log. The above
187 * sections in DRAM are much smaller than the space set aside for the event log. In the current
188 * implementation, the event log is ~995 MB.
189 *
190 ********************************************************************/
191#define EVENT_LOG_BASE                     (USER_SCRATCH_HIGH + 1)
192#define EVENT_LOG_SIZE                     ((CALC_MEM_HIGH_ADDR(platform_high_dev_info.dram_baseaddr, platform_high_dev_info.dram_size)) - EVENT_LOG_BASE + 1) // log occupies all remaining DRAM
193#define EVENT_LOG_HIGH                      CALC_MEM_HIGH_ADDR(EVENT_LOG_BASE, EVENT_LOG_SIZE)
194
195//-----------------------------------------------
196// WLAN Constants
197//
198#define SW_INTR_ID_PORTAL_ETH_RX    0x00000001
199#define SW_INTR_ID_PORTAL_ETH_TX    0x00000002
200#define SW_INTR_ID_WLAN_EXP_ETH_TX  0x00000004
201
202
203//-----------------------------------------------
204// Callback Return Flags
205//
206#define MAC_RX_CALLBACK_RETURN_FLAG_DUP                         0x00000001
207#define MAC_RX_CALLBACK_RETURN_FLAG_NO_COUNTS                   0x00000002
208#define MAC_RX_CALLBACK_RETURN_FLAG_NO_LOG_ENTRY                0x00000004
209
210
211
212/************************** Global Type Definitions **************************/
213
214
215
216/******************** Global Structure/Enum Definitions **********************/
217
218/***************************** Global Constants ******************************/
219
220extern const  u8 bcast_addr[MAC_ADDR_LEN];
221extern const  u8 zero_addr[MAC_ADDR_LEN];
222
223
224/*************************** Function Prototypes *****************************/
225void               wlan_mac_high_init();
226
227int                wlan_mac_high_interrupt_init();
228void                         wlan_mac_high_uart_rx_callback(u8 rxByte);
229int                wlan_mac_high_interrupt_restore_state(interrupt_state_t new_interrupt_state);
230interrupt_state_t  wlan_mac_high_interrupt_stop();
231
232void               wlan_mac_high_userio_inputs_callback(u32 userio_state, enum userio_input_mask_t userio_delta);
233void               wlan_mac_high_sw_intr_callback(u32 intr_state);
234
235void               wlan_mac_high_set_press_pb_0_callback(function_ptr_t callback);
236void               wlan_mac_high_set_release_pb_0_callback(function_ptr_t callback);
237void               wlan_mac_high_set_press_pb_1_callback(function_ptr_t callback);
238void               wlan_mac_high_set_release_pb_1_callback(function_ptr_t callback);
239void               wlan_mac_high_set_press_pb_2_callback(function_ptr_t callback);
240void               wlan_mac_high_set_release_pb_2_callback(function_ptr_t callback);
241
242void               wlan_mac_high_set_uart_rx_callback(function_ptr_t callback);
243void               wlan_mac_high_set_mpdu_tx_high_done_callback(function_ptr_t callback);
244void               wlan_mac_high_set_mpdu_tx_low_done_callback(function_ptr_t callback);
245void               wlan_mac_high_set_beacon_tx_done_callback(function_ptr_t callback);
246void               wlan_mac_high_set_mpdu_rx_callback(function_ptr_t callback);
247void               wlan_mac_high_set_poll_tx_queues_callback(function_ptr_t callback);
248void               wlan_mac_high_set_mpdu_dequeue_callback(function_ptr_t callback);
249void               wlan_mac_high_set_cpu_low_reboot_callback(function_ptr_t callback);
250void               wlan_mac_high_set_tx_queue_state_change_callback(function_ptr_t callback);
251
252void*              wlan_mac_high_malloc(u32 size);
253void*              wlan_mac_high_calloc(u32 size);
254void*              wlan_mac_high_realloc(void* addr, u32 size);
255void               wlan_mac_high_free(void* addr);
256void               wlan_mac_high_display_mallinfo();
257
258int                wlan_mac_high_memory_test();
259int                wlan_mac_high_right_shift_test();
260
261int                wlan_mac_high_cdma_start_transfer(void* dest, void* src, u32 size);
262void               wlan_mac_high_cdma_finish_transfer();
263
264void               wlan_mac_high_mpdu_transmit(struct tx_queue_buffer_t* tx_80211_queue_buffer, int tx_pkt_buf);
265
266void               wlan_mac_high_process_ipc_msg(struct wlan_ipc_msg_t* msg, u32* ipc_msg_from_low_payload);
267
268void               wlan_mac_high_set_srand(u32 seed);
269u8                 wlan_mac_high_bss_channel_spec_to_radio_chan(chan_spec_t chan_spec);
270void               wlan_mac_high_set_radio_channel(u32 mac_channel);
271void               wlan_mac_high_enable_mcast_buffering(u8 enable);
272
273void               wlan_mac_high_config_txrx_beacon(struct beacon_txrx_configure_t* beacon_txrx_configure);
274void               wlan_mac_high_set_rx_ant_mode(u8 ant_mode);
275void               wlan_mac_high_set_tx_ctrl_power(s8 pow);
276void               wlan_mac_high_set_radio_tx_power(s8 pow);
277void               wlan_mac_high_set_rx_filter_mode(u32 filter_mode);
278void               wlan_mac_high_set_dsss(u32 dsss_value);
279
280int                wlan_mac_high_write_low_mem(u32 num_words, u32* payload);
281int                wlan_mac_high_read_low_mem(u32 num_words, u32 baseaddr, u32* payload);
282int                wlan_mac_high_write_low_param(u32 num_words, u32* payload);
283
284void               wlan_mac_high_request_low_state();
285int                wlan_mac_high_is_cpu_low_initialized();
286u8                 wlan_mac_num_tx_pkt_buf_available(pkt_buf_group_t pkt_buf_group);
287int                wlan_mac_high_get_empty_tx_packet_buffer();
288u8                 wlan_mac_high_is_pkt_ltg(void* mac_payload, u16 length);
289
290int wlan_mac_high_configure_beacon_tx_template(u8* addr1,
291                                               u8* addr2,
292                                               u8* addr3,
293                                               struct network_info_t* network_info,
294                                               tx_params_t* tx_params_ptr,
295                                               u8 flags);
296int                wlan_mac_high_update_beacon_tx_params(tx_params_t* tx_params_ptr);
297void               wlan_mac_sanitize_tx_params(struct station_info_t* station_info, tx_params_t* tx_params);
298void               wlan_mac_poll();
299int                wlan_mac_enqueue_wireless_tx(u16 queue_id, dl_entry* queue_entry);
300void               wlan_mac_transmit_wireless(dl_entry* queue_entry);
301void               wlan_mac_purge_wireless_tx(u16 queue_id);
302
303
304
305
306// Common functions that must be implemented by users of the framework
307// TODO: Make these into callback. We should not require these implementations
308dl_list*     get_network_member_list();
309
310#endif /* WLAN_MAC_HIGH_H_ */
Note: See TracBrowser for help on using the repository browser.