1 /* 2 * Copyright (c) 2025 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /** 8 * @file hal_api.h 9 * 10 * @brief Header containing API declarations for the HAL Layer of the Wi-Fi driver. 11 */ 12 13 #ifndef __HAL_API_COMMON_H__ 14 #define __HAL_API_COMMON_H__ 15 16 #include "osal_api.h" 17 #include "rpu_if.h" 18 #include "bal_api.h" 19 #include "hal_structs_common.h" 20 #include "hal_mem.h" 21 #include "hal_reg.h" 22 #include "hal_fw_patch_loader.h" 23 24 #define NRF_WIFI_ADDR_REG_NAME_LEN 16 25 26 /** 27 * @brief Structure containing information about the firmware address. 28 */ 29 struct nrf70_fw_addr_info { 30 /** RPU process type. */ 31 enum RPU_PROC_TYPE rpu_proc; 32 /** Name of the address register. */ 33 char name[NRF_WIFI_ADDR_REG_NAME_LEN]; 34 /** Destination address. */ 35 unsigned int dest_addr; 36 }; 37 38 extern const struct nrf70_fw_addr_info nrf70_fw_addr_info[]; 39 40 /** 41 * @brief Initialize the HAL layer. 42 * 43 * @param cfg_params Parameters needed to configure the HAL for WLAN operation. 44 * @param intr_callbk_fn Pointer to the callback function which the user of this 45 * layer needs to implement to handle events from the RPU. 46 * @param rpu_recovery_callbk_fn Pointer to the callback function which the user of 47 * this layer needs to implement to handle RPU recovery. 48 * 49 * This API is used to initialize the HAL layer and is expected to be called 50 * before using the HAL layer. This API returns a pointer to the HAL context 51 * which might need to be passed to further API calls. 52 * 53 * @return Pointer to instance of HAL layer context. 54 */ 55 struct nrf_wifi_hal_priv * 56 nrf_wifi_hal_init(struct nrf_wifi_hal_cfg_params *cfg_params, 57 enum nrf_wifi_status (*intr_callbk_fn)(void *dev_ctx, 58 void *event_data, 59 unsigned int len), 60 enum nrf_wifi_status (*rpu_recovery_callbk_fn)(void *mac_ctx, 61 void *event_data, 62 unsigned int len)); 63 64 /** 65 * @brief Deinitialize the HAL layer. 66 * 67 * @param hpriv Pointer to the HAL context returned by the nrf_wifi_hal_init API. 68 * 69 * This API is used to deinitialize the HAL layer and is expected to be called 70 * after done using the HAL layer. 71 */ 72 void nrf_wifi_hal_deinit(struct nrf_wifi_hal_priv *hpriv); 73 74 void nrf_wifi_hal_dev_rem(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 75 76 enum nrf_wifi_status nrf_wifi_hal_dev_init(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 77 78 void nrf_wifi_hal_dev_deinit(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 79 80 void nrf_wifi_hal_enable(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 81 void nrf_wifi_hal_disable(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 82 enum NRF_WIFI_HAL_STATUS nrf_wifi_hal_status_unlocked(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 83 84 /** 85 * @brief Send a control command to the RPU. 86 * 87 * @param hal_ctx Pointer to HAL context. 88 * @param cmd Pointer to command data. 89 * @param cmd_size Size of the command data pointed to by @p cmd. 90 * 91 * This function takes care of sending a command to the RPU. It does the 92 * following: 93 * 94 * - Fragments a command into smaller chunks if the size of a command is 95 * greater than %MAX_CMD_SIZE. 96 * - Queues up the command(s) to the HAL command queue. 97 * - Calls a function to further process the commands queued up in the HAL 98 * command queue which handles it by: 99 * 100 * - Waiting for the RPU to be ready to handle a command. 101 * - Copies the command to the GRAM memory and indicates to the RPU 102 * that a command has been posted 103 * 104 * @return The status of the operation. 105 */ 106 enum nrf_wifi_status nrf_wifi_hal_ctrl_cmd_send(struct nrf_wifi_hal_dev_ctx *hal_ctx, 107 void *cmd, 108 unsigned int cmd_size); 109 110 111 /** 112 * @brief Process events from the RPU. 113 * 114 * @param hal_ctx Pointer to HAL context. 115 * 116 * This function processes the events which have been queued into the event 117 * queue by an ISR. It does the following: 118 * 119 * - Dequeues an event from the event queue. 120 * - Calls hal_event_process to further process the event. 121 * 122 * @return The status of the operation. 123 */ 124 enum nrf_wifi_status hal_rpu_eventq_process(struct nrf_wifi_hal_dev_ctx *hal_ctx); 125 126 127 /** 128 * @brief Set the processing context for the Wi-Fi HAL. 129 * 130 * This function sets the processing context for the Wi-Fi HAL device context. 131 * 132 * @param hal_ctx Pointer to the Wi-Fi HAL device context. 133 * @param proc The processing type. 134 */ 135 void nrf_wifi_hal_proc_ctx_set(struct nrf_wifi_hal_dev_ctx *hal_ctx, 136 enum RPU_PROC_TYPE proc); 137 138 /** 139 * @brief Reset the processing context for the Wi-Fi HAL. 140 * 141 * This function resets the processing context for the Wi-Fi HAL device context. 142 * 143 * @param hal_ctx Pointer to the Wi-Fi HAL device context. 144 * @param rpu_proc The RPU processing type. 145 * 146 * @return The status of the operation. 147 */ 148 enum nrf_wifi_status nrf_wifi_hal_proc_reset(struct nrf_wifi_hal_dev_ctx *hal_ctx, 149 enum RPU_PROC_TYPE rpu_proc); 150 151 /** 152 * @brief Check the boot status of the firmware for the Wi-Fi HAL. 153 * 154 * This function checks the boot status of the firmware for the Wi-Fi HAL device context. 155 * 156 * @param hal_ctx Pointer to the Wi-Fi HAL device context. 157 * @param rpu_proc The RPU processing type. 158 * 159 * @return The status of the operation. 160 */ 161 enum nrf_wifi_status nrf_wifi_hal_fw_chk_boot(struct nrf_wifi_hal_dev_ctx *hal_ctx, 162 enum RPU_PROC_TYPE rpu_proc); 163 164 #if defined(NRF_WIFI_LOW_POWER) || defined(__DOXYGEN__) 165 /** 166 * @brief Wake up the RPU power save mode for the Wi-Fi HAL. 167 * 168 * This function wakes up the RPU power save mode for the Wi-Fi HAL device context. 169 * 170 * @param hal_dev_ctx Pointer to the Wi-Fi HAL device context. 171 * 172 * @return The status of the operation. 173 */ 174 enum nrf_wifi_status hal_rpu_ps_wake(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 175 176 /** 177 * @brief Get the RPU power save state for the Wi-Fi HAL. 178 * 179 * This function gets the RPU power save state for the Wi-Fi HAL device context. 180 * 181 * @param hal_dev_ctx Pointer to the Wi-Fi HAL device context. 182 * @param rpu_ps_ctrl_state Pointer to the RPU power save control state. 183 * 184 * @return The status of the operation. 185 */ 186 enum nrf_wifi_status nrf_wifi_hal_get_rpu_ps_state(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx, 187 int *rpu_ps_ctrl_state); 188 #endif /* NRF_WIFI_LOW_POWER */ 189 190 /** 191 * @brief Get the OTP information for the Wi-Fi HAL. 192 * 193 * This function gets the OTP (One-Time Programmable) information for the Wi-Fi HAL device context. 194 * 195 * @param hal_dev_ctx Pointer to the Wi-Fi HAL device context. 196 * @param otp_info Pointer to the OTP information structure. 197 * @param otp_flags Pointer to the OTP flags. 198 * 199 * @return The status of the operation. 200 */ 201 enum nrf_wifi_status nrf_wifi_hal_otp_info_get(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx, 202 struct host_rpu_umac_info *otp_info, 203 unsigned int *otp_flags); 204 205 /** 206 * @brief Get the OTP firmware programming version for the Wi-Fi HAL. 207 * 208 * This function gets the OTP firmware programming version for the Wi-Fi HAL device context. 209 * 210 * @param hal_dev_ctx Pointer to the Wi-Fi HAL device context. 211 * @param ft_prog_ver Pointer to the firmware programming version. 212 * 213 * @return The status of the operation. 214 */ 215 enum nrf_wifi_status nrf_wifi_hal_otp_ft_prog_ver_get(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx, 216 unsigned int *ft_prog_ver); 217 218 /** 219 * @brief Get the OTP package information for the Wi-Fi HAL. 220 * 221 * This function gets the OTP package information for the Wi-Fi HAL device context. 222 * 223 * @param hal_dev_ctx Pointer to the Wi-Fi HAL device context. 224 * @param package_info Pointer to the package information. 225 * 226 * @return The status of the operation. 227 */ 228 enum nrf_wifi_status nrf_wifi_hal_otp_pack_info_get(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx, 229 unsigned int *package_info); 230 231 enum nrf_wifi_status hal_rpu_ps_init(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx); 232 233 enum nrf_wifi_status nrf_wifi_hal_irq_handler(void *data); 234 235 enum nrf_wifi_status hal_rpu_msg_post(struct nrf_wifi_hal_dev_ctx *hal_dev_ctx, 236 enum NRF_WIFI_HAL_MSG_TYPE msg_type, 237 unsigned int queue_id, 238 unsigned int msg_addr); 239 #endif /* __HAL_API_COMMON_H__ */ 240
