1 /*
2 * Copyright (c) 2024 Nordic Semiconductor ASA
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7 /**
8 * @file hal_structs.h
9 *
10 * @brief Header containing structure declarations for the HAL Layer of the Wi-Fi driver.
11 */
12
13 #ifndef __HAL_STRUCTS_COMMON_H__
14 #define __HAL_STRUCTS_COMMON_H__
15
16 #include "lmac_if_common.h"
17 #include "host_rpu_common_if.h"
18 #include "osal_api.h"
19 #include "bal_api.h"
20
21 /** 1 sec */
22 #define MAX_HAL_RPU_READY_WAIT (1 * 1000 * 1000)
23
24 #if defined(NRF_WIFI_LOW_POWER) || defined(__DOXYGEN__)
25 #define RPU_PS_WAKE_INTERVAL_MS 1
26 #define RPU_PS_WAKE_TIMEOUT_S 1
27 #endif /* NRF_WIFI_LOW_POWER */
28
29 /**
30 * @brief Enumeration of RPU processor types.
31 */
32 enum RPU_PROC_TYPE {
33 /** MCU LMAC processor type */
34 RPU_PROC_TYPE_MCU_LMAC = 0,
35 /** MCU UMAC processor type */
36 RPU_PROC_TYPE_MCU_UMAC,
37 /** Maximum number of processor types */
38 RPU_PROC_TYPE_MAX
39 };
40
41 /**
42 * @brief Convert RPU_PROC_TYPE enum to string.
43 *
44 * @param proc The RPU_PROC_TYPE enum value.
45 * @return The string representation of the RPU_PROC_TYPE.
46 */
rpu_proc_to_str(enum RPU_PROC_TYPE proc)47 static inline const char *rpu_proc_to_str(enum RPU_PROC_TYPE proc)
48 {
49 switch (proc) {
50 case RPU_PROC_TYPE_MCU_LMAC:
51 return "LMAC";
52 case RPU_PROC_TYPE_MCU_UMAC:
53 return "UMAC";
54 default:
55 return "UNKNOWN";
56 }
57 };
58 /**
59 * @brief Enumeration of NRF Wi-Fi region types.
60 */
61 enum NRF_WIFI_REGION_TYPE {
62 /** GRAM region type */
63 NRF_WIFI_REGION_TYPE_GRAM,
64 /** PKTRAM region type */
65 NRF_WIFI_REGION_TYPE_PKTRAM,
66 /** SYSBUS region type */
67 NRF_WIFI_REGION_TYPE_SYSBUS,
68 /** PBUS region type */
69 NRF_WIFI_REGION_TYPE_PBUS,
70 };
71
72 /**
73 * @brief Enumeration of NRF Wi-Fi HAL message types.
74 */
75 enum NRF_WIFI_HAL_MSG_TYPE {
76 /** Command control message type */
77 NRF_WIFI_HAL_MSG_TYPE_CMD_CTRL,
78 /** Event message type */
79 NRF_WIFI_HAL_MSG_TYPE_EVENT,
80 /** Command data RX message type */
81 NRF_WIFI_HAL_MSG_TYPE_CMD_DATA_RX,
82 /** Command data management message type */
83 NRF_WIFI_HAL_MSG_TYPE_CMD_DATA_MGMT,
84 /** Command data TX message type */
85 NRF_WIFI_HAL_MSG_TYPE_CMD_DATA_TX,
86 /** Maximum number of message types */
87 NRF_WIFI_HAL_MSG_TYPE_MAX,
88 };
89
90 #if defined(NRF_WIFI_LOW_POWER) || defined(__DOXYGEN__)
91 /**
92 * @brief Enumeration of RPU power states.
93 */
94 enum RPU_PS_STATE {
95 /** RPU is asleep */
96 RPU_PS_STATE_ASLEEP,
97 /** RPU is awake */
98 RPU_PS_STATE_AWAKE,
99 /** Maximum number of power states */
100 RPU_PS_STATE_MAX
101 };
102 #endif /* NRF_WIFI_LOW_POWER */
103
104 /**
105 * @brief Enumeration of NRF WiFi HAL status.
106 */
107 enum NRF_WIFI_HAL_STATUS {
108 /** HAL is enabled */
109 NRF_WIFI_HAL_STATUS_ENABLED,
110 /** HAL is disabled */
111 NRF_WIFI_HAL_STATUS_DISABLED,
112 };
113
114 /**
115 * @brief Structure to hold RPU information.
116 */
117 struct nrf_wifi_hal_info {
118 /** Host RPU HPQM information */
119 struct host_rpu_hpqm_info hpqm_info;
120 /** RX command base */
121 unsigned int rx_cmd_base;
122 /** TX command base */
123 unsigned int tx_cmd_base;
124 };
125
126 /**
127 * @brief Structure to hold buffer mapping information for the HAL layer.
128 */
129 struct nrf_wifi_hal_buf_map_info {
130 /** Flag indicating if the buffer is mapped */
131 bool mapped;
132 /** Virtual address of the buffer */
133 unsigned long virt_addr;
134 /** Physical address of the buffer */
135 unsigned long phy_addr;
136 /** Length of the buffer */
137 unsigned int buf_len;
138 };
139
140 /**
141 * @brief Structure to hold configuration parameters for the HAL layer
142 * in all modes of operation.
143 */
144 struct nrf_wifi_hal_cfg_params {
145 /** Maximum command size */
146 unsigned int max_cmd_size;
147 /** Maximum event size */
148 unsigned int max_event_size;
149 /** RX buffer headroom size */
150 unsigned char rx_buf_headroom_sz;
151 /** TX buffer headroom size */
152 unsigned char tx_buf_headroom_sz;
153 #if defined(NRF70_DATA_TX) || defined(__DOXYGEN__)
154 /** Maximum TX frames */
155 unsigned int max_tx_frms;
156 #endif /* CONFIG_NRF70_DATA_TX */
157 /** RX buffer pool parameters */
158 struct rx_buf_pool_params rx_buf_pool[MAX_NUM_OF_RX_QUEUES];
159 /** Maximum TX frame size */
160 unsigned int max_tx_frm_sz;
161 /** Maximum AMPDU length per token */
162 unsigned int max_ampdu_len_per_token;
163 };
164
165
166 /**
167 * @brief Structure to hold context information for the HAL layer.
168 */
169 struct nrf_wifi_hal_priv {
170 /** Pointer to BAL private data */
171 struct nrf_wifi_bal_priv *bpriv;
172 /** Number of devices */
173 unsigned char num_devs;
174 /** Additional device callback data */
175 void *add_dev_callbk_data;
176 /** Add device callback function */
177 void *(*add_dev_callbk_fn)(void *add_dev_callbk_data,
178 void *hal_dev_ctx);
179 /** Remove device callback function */
180 void (*rem_dev_callbk_fn)(void *mac_ctx);
181 /** Initialize device callback function */
182 enum nrf_wifi_status (*init_dev_callbk_fn)(void *mac_ctx);
183 /** Deinitialize device callback function */
184 void (*deinit_dev_callbk_fn)(void *mac_ctx);
185 /** Interrupt callback function */
186 enum nrf_wifi_status (*intr_callbk_fn)(void *mac_ctx,
187 void *event_data,
188 unsigned int len);
189 /** RPU recovery callback function */
190 enum nrf_wifi_status (*rpu_recovery_callbk_fn)(void *mac_ctx,
191 void *event_data,
192 unsigned int len);
193 struct nrf_wifi_hal_cfg_params cfg_params;
194 /** PKTRAM base address */
195 unsigned long addr_pktram_base;
196 };
197
198
199 /**
200 * @brief Structure to hold per device context information for the HAL layer.
201 */
202 struct nrf_wifi_hal_dev_ctx {
203 /** Pointer to HAL private data */
204 struct nrf_wifi_hal_priv *hpriv;
205 /** MAC device context */
206 void *mac_dev_ctx;
207 /** BAL device context */
208 void *bal_dev_ctx;
209 /** Device index */
210 unsigned char idx;
211 /** RPU information */
212 struct nrf_wifi_hal_info rpu_info;
213 /** Number of commands */
214 unsigned int num_cmds;
215 /** Command queue */
216 void *cmd_q;
217 /** Event queue */
218 void *event_q;
219 /** Current RPU processor type:
220 * This is only used during FW loading where we need the information
221 * about the processor whose core memory the code/data needs to be
222 * loaded into (since the FW image parser does not have the processor
223 * information coded into it). Necessitated due to FullMAC
224 * configuration where the RPU has 2 MCUs.
225 */
226 enum RPU_PROC_TYPE curr_proc;
227 /** HAL lock */
228 void *lock_hal;
229 /** Event tasklet */
230 void *event_tasklet;
231 /** RX lock */
232 void *lock_rx;
233 /** RX buffer information */
234 struct nrf_wifi_hal_buf_map_info *rx_buf_info[MAX_NUM_OF_RX_QUEUES];
235 /** TX buffer information */
236 struct nrf_wifi_hal_buf_map_info *tx_buf_info;
237 /** RPU PKTRAM base address */
238 unsigned long addr_rpu_pktram_base;
239 /** RPU PKTRAM base address for TX */
240 unsigned long addr_rpu_pktram_base_tx;
241 /** RPU PKTRAM base address for RX */
242 unsigned long addr_rpu_pktram_base_rx;
243 /** RPU PKTRAM base address for RX pool */
244 unsigned long addr_rpu_pktram_base_rx_pool[MAX_NUM_OF_RX_QUEUES];
245 /** TX frame offset */
246 unsigned long tx_frame_offset;
247 #if defined(NRF_WIFI_RPU_RECOVERY) || defined(__DOXYGEN__)
248 /** RPU wake up now asserted flag */
249 bool is_wakeup_now_asserted;
250 /** RPU wake up now asserted time */
251 unsigned long last_wakeup_now_asserted_time_ms;
252 /** RPU wake up now asserted time */
253 unsigned long last_wakeup_now_deasserted_time_ms;
254 /** RPU sleep opp time */
255 unsigned long last_rpu_sleep_opp_time_ms;
256 /** Number of watchdog timer interrupts received */
257 int wdt_irq_received;
258 /** Number of watchdog timer interrupts ignored */
259 int wdt_irq_ignored;
260 #endif /* NRF_WIFI_RPU_RECOVERY */
261 #if defined(NRF_WIFI_LOW_POWER) || defined(__DOXYGEN__)
262 /** RPU power state */
263 enum RPU_PS_STATE rpu_ps_state;
264 /** RPU power state timer */
265 void *rpu_ps_timer;
266 /** RPU power state lock */
267 void *rpu_ps_lock;
268 /** Debug enable flag */
269 bool dbg_enable;
270 /** IRQ context flag */
271 bool irq_ctx;
272 /** RPU firmware booted flag */
273 bool rpu_fw_booted;
274 #endif /* NRF_WIFI_LOW_POWER */
275 /** Event data */
276 char *event_data;
277 /** Current event data */
278 char *event_data_curr;
279 /** Event data length */
280 unsigned int event_data_len;
281 /** Pending event data */
282 unsigned int event_data_pending;
283 /** Event resubmit flag */
284 unsigned int event_resubmit;
285 /** HAL status */
286 enum NRF_WIFI_HAL_STATUS hal_status;
287 /** Recovery tasklet */
288 void *recovery_tasklet;
289 /** Recovery lock */
290 void *lock_recovery;
291 };
292
293 /**
294 * @brief Structure to hold information about a HAL message.
295 */
296 struct nrf_wifi_hal_msg {
297 /** Length of the message */
298 unsigned int len;
299 /** Message data */
300 char data[0];
301 };
302 #endif /* __HAL_STRUCTS_COMMON_H__ */
303
