1 // Copyright (C) 2022 Beken Corporation 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 16 #pragma once 17 18 #include <common/bk_include.h> 19 #include <driver/dma_types.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 /** 26 * @brief Init the DMA driver 27 * 28 * This API init the resoure common to all dma channels: 29 * - Init dma driver control memory 30 * 31 * This API should be called before any other dma APIs. 32 * 33 * @return 34 * - BK_OK: succeed 35 * - others: other errors. 36 */ 37 bk_err_t bk_dma_driver_init(void); 38 39 /** 40 * @brief Deinit the DMA driver 41 * 42 * This API free all resource related to dma and power down all dma channels. 43 * 44 * @return 45 * - BK_OK: succeed 46 * - others: other errors. 47 */ 48 bk_err_t bk_dma_driver_deinit(void); 49 50 /** 51 * @brief Allocate a DMA channel 52 * 53 * @attention: This API can only be called in task context, 54 * - and can't be called in context that interrupt is disabled. 55 * 56 * This API should be called before any other dma channel APIs. 57 * 58 * @param user_id DMA channel applicant 59 * 60 * @return DMA channel id. 61 * - > DMA_ID_MAX: no free DMA channel. 62 */ 63 dma_id_t bk_dma_alloc(u16 user_id); 64 65 /** 66 * @brief Free the DMA channel 67 * 68 * @attention: This API can only be called in task context, 69 * - and can't be called in context that interrupt is disabled. 70 * 71 * @param user_id DMA channel applicant, the same as in bk_dma_alloc. 72 * @param id DMA channel 73 * 74 * @return 75 * - BK_OK: succeed 76 * - others: other errors. 77 */ 78 bk_err_t bk_dma_free(u16 user_id, dma_id_t id); 79 80 /** 81 * @brief get the user of DMA channel 82 * 83 * @param id DMA channel 84 * 85 * @return DMA channel user_id. 86 * - u32: high u16 is the CPU_ID, low 16 bits is the applicant_id. 87 */ 88 uint32_t bk_dma_user(dma_id_t id); 89 90 /** 91 * @brief Init the DMA channel 92 * 93 * @attention 1. the higher channel priority value, the higher the priority 94 * 95 * @param id DMA channel 96 * @param config DMA configuration 97 * 98 * @return 99 * - BK_OK: succeed 100 * - BK_ERR_DMA_NOT_INIT: DMA driver not init 101 * - BK_ERR_NULL_PARAM: config is NULL 102 * - BK_ERR_DMA_ID: invalid DMA channel 103 * - BK_ERR_DMA_INVALID_ADDR: invalid DMA address 104 * - others: other errors. 105 */ 106 bk_err_t bk_dma_init(dma_id_t id, const dma_config_t *config); 107 108 /** 109 * @brief Deinit a DMA channel 110 * 111 * This API deinit the DMA channel: 112 * - Stop the DMA channel 113 * - Reset all configuration of DMA channel to default value 114 * 115 * @return 116 * - BK_OK: succeed 117 * - others: other errors. 118 */ 119 bk_err_t bk_dma_deinit(dma_id_t id); 120 121 /** 122 * @brief Start a DMA channel 123 * 124 * @param id DMA channel 125 * 126 * @return 127 * - BK_OK: succeed 128 * - others: other errors. 129 */ 130 bk_err_t bk_dma_start(dma_id_t id); 131 132 /** 133 * @brief Stop a DMA channel 134 * 135 * @param id DMA channel 136 * 137 * @return 138 * - BK_OK: succeed 139 * - others: other errors. 140 */ 141 bk_err_t bk_dma_stop(dma_id_t id); 142 143 /** 144 * @brief Transfer data from memory to peripheral 145 * 146 * @param id DMA channel 147 * @param data DMA transfer data 148 * @param size data size 149 * 150 * @return 151 * - BK_OK: succeed 152 * - others: other errors. 153 */ 154 bk_err_t bk_dma_write(dma_id_t id, const uint8_t *data, uint32_t size); 155 156 /** 157 * @brief Transfer data from peripheral to memory 158 * 159 * @param id DMA channel 160 * @param data DMA transfer data 161 * @param size data size 162 * 163 * @return 164 * - BK_OK: succeed 165 * - others: other errors. 166 */ 167 bk_err_t bk_dma_read(dma_id_t id, uint8_t *data, uint32_t size); 168 169 /** 170 * @brief Enable DMA finish intterrup 171 * 172 * @param id DMA channel 173 * 174 * @return 175 * - BK_OK: succeed 176 * - others: other errors. 177 */ 178 bk_err_t bk_dma_enable_finish_interrupt(dma_id_t id); 179 180 /** 181 * @brief Disable DMA finish intterrup 182 * 183 * @param id DMA channel 184 * 185 * @return 186 * - BK_OK: succeed 187 * - others: other errors. 188 */ 189 bk_err_t bk_dma_disable_finish_interrupt(dma_id_t id); 190 191 /** 192 * @brief Enable DMA half finish intterrup 193 * 194 * @param id DMA channel 195 * 196 * @return 197 * - BK_OK: succeed 198 * - others: other errors. 199 */ 200 bk_err_t bk_dma_enable_half_finish_interrupt(dma_id_t id); 201 202 /** 203 * @brief Disable DMA half finish intterrup 204 * 205 * @param id DMA channel 206 * 207 * @return 208 * - BK_OK: succeed 209 * - others: other errors. 210 */ 211 bk_err_t bk_dma_disable_half_finish_interrupt(dma_id_t id); 212 213 /** 214 * @brief Register the interrupt service routine for DMA channel 215 * 216 * This API regist dma isr callback function. 217 * 218 * @param id DMA channel 219 * @param half_finish_isr DMA half finish callback 220 * @param finish_isr DMA finish callback 221 * 222 * @return 223 * - BK_OK: succeed 224 * - others: other errors. 225 */ 226 bk_err_t bk_dma_register_isr(dma_id_t id, dma_isr_t half_finish_isr, dma_isr_t finish_isr); 227 228 /** 229 * @brief Set DMA transfer length 230 * 231 * @param id DMA channel 232 * @param tran_len DMA transfer length 233 * 234 * @return 235 * - BK_OK: succeed 236 * - others: other errors. 237 */ 238 bk_err_t bk_dma_set_transfer_len(dma_id_t id, uint32_t tran_len); 239 240 /** 241 * @brief Set DMA source address 242 * 243 * @attention 1. address should be zero when there is no value, e.g. bk_dma_set_src_addr(1, 0x80210C, 0) 244 * 245 * @param id DMA channel 246 * @param start_addr DMA source start address 247 * @param end_addr DMA source end address 248 * 249 * @return 250 * - BK_OK: succeed 251 * - others: other errors. 252 */ 253 bk_err_t bk_dma_set_src_addr(dma_id_t id, uint32_t start_addr, uint32_t end_addr); 254 255 /** 256 * @brief Set DMA source start address 257 * 258 * @param id DMA channel 259 * @param start_addr DMA source start address 260 * 261 * @return 262 * - BK_OK: succeed 263 * - others: other errors. 264 */ 265 bk_err_t bk_dma_set_src_start_addr(dma_id_t id, uint32_t start_addr); 266 267 /** 268 * @brief Set DMA dest address 269 * 270 * @attention 1. address should be zero when there is no value, e.g. bk_dma_set_dest_addr(1, 0x80210C, 0) 271 * 272 * @param id DMA channel 273 * @param start_addr DMA dest start address 274 * @param end_addr DMA dest end address 275 * 276 * @return 277 * - BK_OK: succeed 278 * - others: other errors. 279 */ 280 bk_err_t bk_dma_set_dest_addr(dma_id_t id, uint32_t start_addr, uint32_t end_addr); 281 282 /** 283 * @brief Set DMA dest start address 284 * 285 * @param id DMA channel 286 * @param start_addr DMA dest start address 287 * 288 * @return 289 * - BK_OK: succeed 290 * - others: other errors. 291 */ 292 bk_err_t bk_dma_set_dest_start_addr(dma_id_t id, uint32_t start_addr); 293 294 /** 295 * @brief Enable DMA source address increase 296 * 297 * @param id DMA channel 298 * 299 * @return 300 * - BK_OK: succeed 301 * - others: other errors. 302 */ 303 bk_err_t bk_dma_enable_src_addr_increase(dma_id_t id); 304 305 /** 306 * @brief Disable DMA source address increase 307 * 308 * @param id DMA channel 309 * 310 * @return 311 * - BK_OK: succeed 312 * - others: other errors. 313 */ 314 bk_err_t bk_dma_disable_src_addr_increase(dma_id_t id); 315 316 /** 317 * @brief Enable DMA source address loop 318 * 319 * @param id DMA channel 320 * 321 * @return 322 * - BK_OK: succeed 323 * - others: other errors. 324 */ 325 bk_err_t bk_dma_enable_src_addr_loop(dma_id_t id); 326 327 /** 328 * @brief Disable DMA source address loop 329 * 330 * @param id DMA channel 331 * 332 * @return 333 * - BK_OK: succeed 334 * - others: other errors. 335 */ 336 bk_err_t bk_dma_disable_src_addr_loop(dma_id_t id); 337 338 /** 339 * @brief Enable DMA dest address increase 340 * 341 * @param id DMA channel 342 * 343 * @return 344 * - BK_OK: succeed 345 * - others: other errors. 346 */ 347 bk_err_t bk_dma_enable_dest_addr_increase(dma_id_t id); 348 349 /** 350 * @brief Disable DMA dest address increase 351 * 352 * @param id DMA channel 353 * 354 * @return 355 * - BK_OK: succeed 356 * - others: other errors. 357 */ 358 bk_err_t bk_dma_disable_dest_addr_increase(dma_id_t id); 359 360 /** 361 * @brief Enable DMA dest address loop 362 * 363 * @param id DMA channel 364 * 365 * @return 366 * - BK_OK: succeed 367 * - others: other errors. 368 */ 369 bk_err_t bk_dma_enable_dest_addr_loop(dma_id_t id); 370 371 /** 372 * @brief Disable DMA dest address loop 373 * 374 * @param id DMA channel 375 * 376 * @return 377 * - BK_OK: succeed 378 * - others: other errors. 379 */ 380 bk_err_t bk_dma_disable_dest_addr_loop(dma_id_t id); 381 382 /** 383 * @brief Get DMA transfer remain length 384 * 385 * @param id DMA channel 386 * 387 * @return DMA transfer remain length 388 */ 389 uint32_t bk_dma_get_remain_len(dma_id_t id); 390 391 /** 392 * @brief Gets the current DMA channel working status 393 * 394 * @param id DMA channel 395 * 396 * @return 397 * - 0: Channel idle state 398 * - others: Channel busy state. 399 */ 400 uint32_t bk_dma_get_enable_status(dma_id_t id); 401 402 #ifdef __cplusplus 403 } 404 #endif 405 406