1 /* 2 * Copyright (c) 2024 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /** 8 * @brief Header containing the API declarations for the Bus Abstraction Layer 9 * (BAL) of the Wi-Fi driver. 10 */ 11 12 #ifndef __BAL_API_H__ 13 #define __BAL_API_H__ 14 15 #include "osal_api.h" 16 #include "bal_structs.h" 17 18 /** 19 * @brief Initialize the BAL layer. 20 * 21 * @param cfg_params Pointer to the configuration parameters for the BAL layer. 22 * @param intr_callbk_fn Pointer to the callback function which the user of this 23 * layer needs to implement to handle interrupts from the RPU. 24 * 25 * This API is used to initialize the BAL layer and is expected to be called 26 * before using the BAL layer. This API returns a pointer to the BAL context 27 * which might need to be passed to further API calls. 28 * 29 * @return Pointer to instance of BAL layer context. 30 */ 31 struct nrf_wifi_bal_priv *nrf_wifi_bal_init(struct nrf_wifi_bal_cfg_params *cfg_params, 32 enum nrf_wifi_status (*intr_callbk_fn)(void *hal_ctx)); 33 34 35 /** 36 * @brief Deinitialize the BAL layer. 37 * 38 * This API is used to deinitialize the BAL layer and is expected to be called 39 * after done using the BAL layer. 40 * 41 * @param bpriv Pointer to the BAL layer context returned by the 42 * @ref nrf_wifi_bal_init API. 43 */ 44 void nrf_wifi_bal_deinit(struct nrf_wifi_bal_priv *bpriv); 45 46 /** 47 * @brief Add a device context to the BAL layer. 48 * 49 * @param bpriv Pointer to the BAL layer context returned by the 50 * @ref nrf_wifi_bal_init API. 51 * @param hal_dev_ctx Pointer to the HAL device context. 52 * 53 * @return Pointer to the added device context. 54 */ 55 struct nrf_wifi_bal_dev_ctx *nrf_wifi_bal_dev_add(struct nrf_wifi_bal_priv *bpriv, 56 void *hal_dev_ctx); 57 58 /** 59 * @brief Remove a device context from the BAL layer. 60 * 61 * @param bal_dev_ctx Pointer to the device context returned by the 62 * @ref nrf_wifi_bal_dev_add API. 63 */ 64 void nrf_wifi_bal_dev_rem(struct nrf_wifi_bal_dev_ctx *bal_dev_ctx); 65 66 /** 67 * @brief Initialize a device context in the BAL layer. 68 * 69 * @param bal_dev_ctx Pointer to the device context returned by the 70 * @ref nrf_wifi_bal_dev_add API. 71 * 72 * @return Status of the device initialization. 73 */ 74 enum nrf_wifi_status nrf_wifi_bal_dev_init(struct nrf_wifi_bal_dev_ctx *bal_dev_ctx); 75 76 /** 77 * @brief Deinitialize a device context in the BAL layer. 78 * 79 * @param bal_dev_ctx Pointer to the device context returned by the 80 * @ref nrf_wifi_bal_dev_add API. 81 */ 82 void nrf_wifi_bal_dev_deinit(struct nrf_wifi_bal_dev_ctx *bal_dev_ctx); 83 84 /** 85 * @brief Read a word from a specific address offset. 86 * 87 * @param ctx Pointer to the context. 88 * @param addr_offset Address offset to read from. 89 * 90 * @return The read word. 91 */ 92 unsigned int nrf_wifi_bal_read_word(void *ctx, unsigned long addr_offset); 93 94 /** 95 * @brief Write a word to a specific address offset. 96 * 97 * @param ctx Pointer to the context. 98 * @param addr_offset Address offset to write to. 99 * @param val Value to write. 100 */ 101 void nrf_wifi_bal_write_word(void *ctx, 102 unsigned long addr_offset, 103 unsigned int val); 104 105 /** 106 * @brief Read a block of data from a specific address offset. 107 * 108 * @param ctx Pointer to the context. 109 * @param dest_addr Pointer to the destination address. 110 * @param src_addr_offset Source address offset to read from. 111 * @param len Length of the data to read. 112 */ 113 void nrf_wifi_bal_read_block(void *ctx, 114 void *dest_addr, 115 unsigned long src_addr_offset, 116 size_t len); 117 118 /** 119 * @brief Write a block of data to a specific address offset. 120 * 121 * @param ctx Pointer to the context. 122 * @param dest_addr_offset Destination address offset to write to. 123 * @param src_addr Pointer to the source address. 124 * @param len Length of the data to write. 125 */ 126 void nrf_wifi_bal_write_block(void *ctx, 127 unsigned long dest_addr_offset, 128 const void *src_addr, 129 size_t len); 130 131 /** 132 * @brief Map a virtual address to a physical address for DMA transfer. 133 * 134 * @param ctx Pointer to the context. 135 * @param virt_addr Virtual address to map. 136 * @param len Length of the data to map. 137 * @param dma_dir DMA direction. 138 * 139 * @return The mapped physical address. 140 */ 141 unsigned long nrf_wifi_bal_dma_map(void *ctx, 142 unsigned long virt_addr, 143 size_t len, 144 enum nrf_wifi_osal_dma_dir dma_dir); 145 146 /** 147 * @brief Unmap a physical address for DMA transfer. 148 * 149 * @param ctx Pointer to the context. 150 * @param phy_addr Physical address to unmap. 151 * @param len Length of the data to unmap. 152 * @param dma_dir DMA direction. 153 */ 154 unsigned long nrf_wifi_bal_dma_unmap(void *ctx, 155 unsigned long phy_addr, 156 size_t len, 157 enum nrf_wifi_osal_dma_dir dma_dir); 158 159 /** 160 * @brief Enable bus access recording. 161 * 162 * @param ctx Pointer to the context. 163 */ 164 void nrf_wifi_bal_bus_access_rec_enab(void *ctx); 165 166 /** 167 * @brief Disable bus access recording. 168 * 169 * @param ctx Pointer to the context. 170 */ 171 void nrf_wifi_bal_bus_access_rec_disab(void *ctx); 172 173 /** 174 * @brief Print bus access count. 175 * 176 * @param ctx Pointer to the context. 177 */ 178 void nrf_wifi_bal_bus_access_cnt_print(void *ctx); 179 180 #if defined(NRF_WIFI_LOW_POWER) || defined(__DOXYGEN__) 181 /** 182 * @brief Put the RPU to sleep. 183 * 184 * @param ctx Pointer to the context. 185 */ 186 void nrf_wifi_bal_rpu_ps_sleep(void *ctx); 187 188 /** 189 * @brief Wake up the RPU from sleep. 190 * 191 * @param ctx Pointer to the context. 192 */ 193 void nrf_wifi_bal_rpu_ps_wake(void *ctx); 194 195 /** 196 * @brief Get the power-saving status of the RPU. 197 * 198 * @param ctx Pointer to the context. 199 * 200 * @return Power-saving status. 201 */ 202 int nrf_wifi_bal_rpu_ps_status(void *ctx); 203 #endif /* NRF_WIFI_LOW_POWER */ 204 #endif /* __BAL_API_H__ */ 205
