1 /* 2 * Copyright (c) 2024 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /** 8 * @brief File containing declarations for the 9 * OSAL Layer of the Wi-Fi driver. 10 */ 11 12 #ifndef __OSAL_API_H__ 13 #define __OSAL_API_H__ 14 15 #include "osal_structs.h" 16 17 /* Have to match zephyr/include/zephyr/logging/log_core.h */ 18 #define NRF_WIFI_LOG_LEVEL_ERR 1U 19 #define NRF_WIFI_LOG_LEVEL_INF 3U 20 #define NRF_WIFI_LOG_LEVEL_DBG 4U 21 22 #ifndef NRF70_LOG_VERBOSE 23 #define __func__ "<snipped>" 24 #endif /* NRF70_LOG_VERBOSE */ 25 26 /** 27 * @brief Initialize the OSAL layer. 28 * @param ops: Pointer to the OSAL operations structure. 29 * 30 * Initializes the OSAL layer and is expected to be called 31 * before using the OSAL layer. 32 */ 33 void nrf_wifi_osal_init(const struct nrf_wifi_osal_ops *ops); 34 35 /** 36 * @brief Deinitialize the OSAL layer. 37 * 38 * Deinitialize the OSAL layer and is expected to be called after done using 39 * the OSAL layer. 40 */ 41 void nrf_wifi_osal_deinit(void); 42 43 /** 44 * @brief Allocate memory. 45 * @param size Size of the memory to be allocated in bytes. 46 * 47 * Allocates memory of @p size bytes and returns a pointer to the start 48 * of the memory allocated. 49 * 50 * @return Pointer to start of allocated memory on success, NULL on error. 51 */ 52 void *nrf_wifi_osal_mem_alloc(size_t size); 53 54 /** 55 * @brief Allocated zero-initialized memory. 56 * @param size Size of the memory to be allocated in bytes. 57 * 58 * Allocates zero-initialized memory of @p size bytes and returns a pointer to the start 59 * of the memory allocated. 60 * 61 * @return Pointer to start of allocated memory on success, NULL on error. 62 */ 63 void *nrf_wifi_osal_mem_zalloc(size_t size); 64 65 /** 66 * @brief Free previously allocated memory. 67 * @param buf Pointer to the memory to be freed. 68 * 69 * Free up memory which has been allocated using nrf_wifi_osal_mem_alloc or 70 * nrf_wifi_osal_mem_zalloc. 71 */ 72 void nrf_wifi_osal_mem_free(void *buf); 73 74 /** 75 * @brief Copy contents from one memory location to another. 76 * 77 * @param dest Pointer to the memory location where contents are to be copied. 78 * @param src Pointer to the memory location from where contents are to be copied. 79 * @param count Number of bytes to be copied. 80 * 81 * Copies @p count number of bytes from @p src location in memory to @p dest 82 * location in memory. 83 * 84 * @return Pointer to destination memory if successful, NULL otherwise. 85 */ 86 void *nrf_wifi_osal_mem_cpy(void *dest, 87 const void *src, 88 size_t count); 89 90 /** 91 * @brief Fill a block of memory with a particular value. 92 * @param start Pointer to the memory location whose contents are to be set. 93 * @param val Value to be set. 94 * @param size Number of bytes to be set. 95 * 96 * Fills a block of memory of @p size bytes, starting at @p start with a value 97 * specified by @p val. 98 * 99 * @return Pointer to memory location which was set on success, NULL on error. 100 */ 101 void *nrf_wifi_osal_mem_set(void *start, 102 int val, 103 size_t size); 104 105 106 /** 107 * @brief Memory map IO memory into CPU space. 108 * @param addr Address of the IO memory to be mapped. 109 * @param size Size of the IO memory in bytes. 110 * 111 * Maps IO memory of @p size bytes pointed to by @p addr into CPU space. 112 * 113 * @return Pointer to the mapped IO memory on success, NULL on error. 114 */ 115 void *nrf_wifi_osal_iomem_mmap(unsigned long addr, 116 unsigned long size); 117 118 /** 119 * @brief Unmap previously mapped IO memory from CPU space. 120 * @param addr Pointer to mapped IO memory to be unmapped. 121 * 122 * Unmaps IO memory from CPU space that was mapped using nrf_wifi_osal_iomem_mmap. 123 */ 124 void nrf_wifi_osal_iomem_unmap(volatile void *addr); 125 126 /** 127 * @brief Read value from a 32 bit IO memory mapped register. 128 * @param addr Pointer to the IO memory mapped register address. 129 * 130 * @return 32 bit value read from register. 131 */ 132 unsigned int nrf_wifi_osal_iomem_read_reg32(const volatile void *addr); 133 134 /** 135 * @brief Write a 32 bit value to a IO memory mapped register. 136 * @param addr Pointer to the IO memory mapped register address. 137 * @param val Value to be written to the register. 138 * 139 * Writes a 32 bit value (val) to a 32 bit device register using a memory 140 * mapped address (addr). 141 */ 142 void nrf_wifi_osal_iomem_write_reg32(volatile void *addr, 143 unsigned int val); 144 145 /** 146 * @brief Copy data from the memory of a memory mapped IO device to host memory. 147 * @param dest Pointer to the host memory where data is to be copied. 148 * @param src Pointer to the memory of the memory mapped IO device from where data is to be copied. 149 * @param count The size of the data to be copied in bytes. 150 * 151 * Copies a block of data of size count bytes from memory mapped device memory(src) 152 * to host memory(dest). 153 */ 154 void nrf_wifi_osal_iomem_cpy_from(void *dest, 155 const volatile void *src, 156 size_t count); 157 158 /** 159 * @brief Copy data to the memory of a memory mapped IO device from host memory. 160 * @param dest: Pointer to the memory of the memory mapped IO device where data is to be copied. 161 * @param src: Pointer to the host memory from where data is to be copied. 162 * @param count: The size of the data to be copied in bytes. 163 * 164 * Copies a block of data of size count bytes from host memory (src) to memory mapped 165 * device memory(dest). 166 */ 167 void nrf_wifi_osal_iomem_cpy_to(volatile void *dest, 168 const void *src, 169 size_t count); 170 171 172 /** 173 * @brief Allocate a busy lock. 174 * 175 * Allocates a busy lock. 176 * 177 * @return Pointer to the busy lock instance on success, NULL on error. 178 */ 179 void *nrf_wifi_osal_spinlock_alloc(void); 180 181 /** 182 * @brief Free a busy lock. 183 * @param lock Pointer to a busy lock instance. 184 * 185 * Frees a busy lock (lock) allocated by nrf_wifi_osal_spinlock_alloc. 186 */ 187 void nrf_wifi_osal_spinlock_free(void *lock); 188 189 190 /** 191 * @brief Initialize a busy lock. 192 * @param lock Pointer to a busy lock instance. 193 * 194 * Initialize a busy lock (lock) allocated by nrf_wifi_osal_spinlock_alloc. 195 */ 196 void nrf_wifi_osal_spinlock_init(void *lock); 197 198 199 /** 200 * @brief Acquire a busy lock. 201 * @param lock: Pointer to a busy lock instance. 202 * 203 * Acquires a busy lock (lock) allocated by nrf_wifi_osal_spinlock_alloc. 204 */ 205 void nrf_wifi_osal_spinlock_take(void *lock); 206 207 208 /** 209 * @brief Releases a busy lock. 210 * @param lock: Pointer to a busy lock instance. 211 * 212 * Releases a busy lock (lock) acquired by nrf_wifi_osal_spinlock_take. 213 */ 214 void nrf_wifi_osal_spinlock_rel(void *lock); 215 216 217 /** 218 * @brief Acquire a busy lock and disable interrupts. 219 * @param lock Pointer to a busy lock instance. 220 * @param flags Interrupt state flags. 221 * 222 * Saves interrupt states (@p flags), disable interrupts and takes a 223 * busy lock (@p lock). 224 */ 225 void nrf_wifi_osal_spinlock_irq_take(void *lock, 226 unsigned long *flags); 227 228 229 /** 230 * @brief Release a busy lock and enable interrupts. 231 * @param lock Pointer to a busy lock instance. 232 * @param flags Interrupt state flags. 233 * 234 * Restores interrupt states (@p flags) and releases busy lock (@p lock) acquired 235 * using nrf_wifi_osal_spinlock_irq_take. 236 */ 237 void nrf_wifi_osal_spinlock_irq_rel(void *lock, 238 unsigned long *flags); 239 240 241 #if WIFI_NRF70_LOG_LEVEL >= NRF_WIFI_LOG_LEVEL_DBG 242 /** 243 * @brief Log a debug message. 244 * @param fmt: Format string. 245 * @param ...: Variable arguments. 246 * 247 * Logs a debug message. 248 * 249 * @return Number of characters of the message logged. 250 */ 251 int nrf_wifi_osal_log_dbg(const char *fmt, ...); 252 #else 253 #define nrf_wifi_osal_log_dbg(fmt, ...) 254 #endif 255 256 #if WIFI_NRF70_LOG_LEVEL >= NRF_WIFI_LOG_LEVEL_INF 257 /** 258 * @brief Logs an informational message. 259 * @param fmt Format string. 260 * @param ... Variable arguments. 261 * 262 * Logs an informational message. 263 * 264 * @return Number of characters of the message logged. 265 */ 266 int nrf_wifi_osal_log_info(const char *fmt, ...); 267 #else 268 #define nrf_wifi_osal_log_info(fmt, ...) 269 #endif 270 271 #if WIFI_NRF70_LOG_LEVEL >= NRF_WIFI_LOG_LEVEL_ERR 272 /** 273 * @brief Logs an error message. 274 * @param fmt Format string. 275 * @param ... Variable arguments. 276 * 277 * Logs an error message. 278 * 279 * @return Number of characters of the message logged. 280 */ 281 int nrf_wifi_osal_log_err(const char *fmt, ...); 282 #else 283 #define nrf_wifi_osal_log_err(fmt, ...) 284 #endif 285 286 /** 287 * @brief Allocate a linked list node. 288 * 289 * Allocate a linked list node. 290 * 291 * @return Pointer to the linked list node allocated. 292 * NULL if there is an error. 293 */ 294 void *nrf_wifi_osal_llist_node_alloc(void); 295 296 /** 297 * @brief Free a linked list node. 298 * @param node Pointer to a linked list node. 299 * 300 * Frees a linked list node(node) which was allocated by nrf_wifi_osal_llist_node_alloc. 301 */ 302 void nrf_wifi_osal_llist_node_free(void *node); 303 304 /** 305 * @brief Get data stored in a linked list node. 306 * @param node Pointer to a linked list node. 307 * 308 * Get the data from a linked list node. 309 * 310 * @return Pointer to the data stored in the linked list node. 311 * NULL if there is an error. 312 */ 313 void *nrf_wifi_osal_llist_node_data_get(void *node); 314 315 316 /** 317 * @brief Set data in a linked list node. 318 * @param node Pointer to a linked list node. 319 * @param data Pointer to the data to be stored in the linked list node. 320 * 321 * Stores the pointer to the data(data) in a linked list node(node). 322 */ 323 void nrf_wifi_osal_llist_node_data_set(void *node, 324 void *data); 325 326 327 /** 328 * @brief Allocate a linked list. 329 * 330 * Allocate a linked list. 331 * 332 * @return Pointer to the allocated linked list on success, NULL on error. 333 */ 334 void *nrf_wifi_osal_llist_alloc(void); 335 336 /** 337 * @brief Free a linked list. 338 * @param llist Pointer to a linked list. 339 * 340 * Frees a linked list (llist) allocated by nrf_wifi_osal_llist_alloc. 341 */ 342 void nrf_wifi_osal_llist_free(void *llist); 343 344 345 /** 346 * @brief Initialize a linked list. 347 * @param llist Pointer to a linked list. 348 * 349 * Initialize a linked list (llist) allocated by nrf_wifi_osal_llist_alloc. 350 */ 351 void nrf_wifi_osal_llist_init(void *llist); 352 353 354 /** 355 * @brief Add a node to the tail of a linked list. 356 * @param llist Pointer to a linked list. 357 * @param llist_node Pointer to a linked list node. 358 * 359 * Adds a linked list node ( llist_node) allocated by nrf_wifi_osal_llist_node_alloc 360 * to the tail of a linked list (llist) allocated by nrf_wifi_osal_llist_alloc. 361 */ 362 void nrf_wifi_osal_llist_add_node_tail(void *llist, 363 void *llist_node); 364 365 366 /** 367 * @brief Add a node to the head of a linked list. 368 * @param llist Pointer to a linked list. 369 * @param llist_node Pointer to a linked list node. 370 * 371 * Adds a linked list node ( llist_node) allocated by nrf_wifi_osal_llist_node_alloc 372 * to the head of a linked list (llist) allocated by nrf_wifi_osal_llist_alloc. 373 */ 374 void nrf_wifi_osal_llist_add_node_head(void *llist, 375 void *llist_node); 376 /** 377 * @brief Get the head of a linked list. 378 * @param llist Pointer to a linked list. 379 * 380 * Returns the head node from a linked list (llist) while still leaving the 381 * node as part of the linked list. If the linked list is empty, returns NULL. 382 * 383 * @return Pointer to the head of the linked list on success, NULL on error. 384 */ 385 void *nrf_wifi_osal_llist_get_node_head(void *llist); 386 387 388 /** 389 * @brief Get the next node in a linked list. 390 * @param llist Pointer to a linked list. 391 * @param llist_node Pointer to a linked list node. 392 * 393 * Return the node next to the node passed in the @p llist_node parameter. 394 * The node returned is not removed from the linked list. 395 * 396 * @return Pointer to the next node in the linked list if successful, NULL otherwise. 397 */ 398 void *nrf_wifi_osal_llist_get_node_nxt(void *llist, 399 void *llist_node); 400 401 402 /** 403 * @brief Delete node from a linked list. 404 * @param llist Pointer to a linked list. 405 * @param llist_node Pointer to a linked list node. 406 * 407 * Removes the node passed in the @p llist_node parameter from the linked list 408 * passed in the @p llist parameter. 409 */ 410 void nrf_wifi_osal_llist_del_node(void *llist, 411 void *llist_node); 412 413 414 /** 415 * @brief Get length of a linked list. 416 * @param llist Pointer to a linked list. 417 * 418 * Returns the length of the linked list(@p llist). 419 * 420 * @return Linked list length in bytes. 421 */ 422 unsigned int nrf_wifi_osal_llist_len(void *llist); 423 424 425 /** 426 * @brief Allocate a network buffer 427 * @param size Size in bytes of the network buffer to be allocated. 428 * 429 * Allocate a network buffer. 430 * 431 * @return Pointer to the allocated network buffer if successful, NULL otherwise. 432 */ 433 void *nrf_wifi_osal_nbuf_alloc(unsigned int size); 434 435 436 /** 437 * @brief Free a network buffer. 438 * @param nbuf Pointer to a network buffer. 439 * 440 * Frees a network buffer(@p nbuf) which was allocated by 441 * nrf_wifi_osal_nbuf_alloc(). 442 */ 443 void nrf_wifi_osal_nbuf_free(void *nbuf); 444 445 446 /** 447 * @brief Reserve headroom space in a network buffer. 448 * @param nbuf Pointer to a network buffer. 449 * @param size Size in bytes of the headroom to be reserved. 450 * 451 * Reserves headroom of size(@p size) bytes at the beginning of the data area of 452 * a network buffer(@p nbuf). 453 */ 454 void nrf_wifi_osal_nbuf_headroom_res(void *nbuf, 455 unsigned int size); 456 457 458 459 /** 460 * @brief Get the size of the headroom in a network buffer. 461 * @param nbuf Pointer to a network buffer. 462 * 463 * Gets the size of the reserved headroom at the beginning 464 * of the data area of a network buffer(@p nbuf). 465 * 466 * @return Size of the network buffer data headroom in bytes. 467 */ 468 unsigned int nrf_wifi_osal_nbuf_headroom_get(void *nbuf); 469 470 /** 471 * @brief Get the size of data in a network buffer. 472 * @param nbuf Pointer to a network buffer. 473 * 474 * Gets the size of the data area of a network buffer (@p nbuf). 475 * 476 * @return Size of the network buffer data in bytes. 477 */ 478 unsigned int nrf_wifi_osal_nbuf_data_size(void *nbuf); 479 480 481 /** 482 * @brief Get a handle to the data in a network buffer. 483 * @param nbuf Pointer to a network buffer. 484 * 485 * Gets the pointer to the data area of a network buffer(@p nbuf). 486 * 487 * @return Pointer to the data in the network buffer if successful, otherwise NULL. 488 */ 489 void *nrf_wifi_osal_nbuf_data_get(void *nbuf); 490 491 492 /** 493 * @brief Extend the tail portion of the data in a network buffer. 494 * @param nbuf Pointer to a network buffer. 495 * @param size Size in bytes of the extension. 496 * 497 * Increases the data area of a network buffer(@p nbuf) by @p size bytes at the 498 * end of the area and returns the pointer to the beginning of 499 * the data area. 500 * 501 * @return Updated pointer to the data in the network buffer if successful, otherwise NULL. 502 */ 503 void *nrf_wifi_osal_nbuf_data_put(void *nbuf, 504 unsigned int size); 505 506 507 /** 508 * @brief Extend the head portion of the data in a network buffer. 509 * @param nbuf Pointer to a network buffer. 510 * @param size Size in bytes, of the extension. 511 * 512 * Increases the data area of a network buffer(@p nbuf) by @p size bytes at the 513 * start of the area and returns the pointer to the beginning of 514 * the data area. 515 * 516 * @return Updated pointer to the data in the network buffer if successful, NULL otherwise. 517 */ 518 void *nrf_wifi_osal_nbuf_data_push(void *nbuf, 519 unsigned int size); 520 521 522 /** 523 * @brief Reduce the head portion of the data in a network buffer. 524 * @param nbuf Pointer to a network buffer. 525 * @param size Size in bytes, of the reduction. 526 * 527 * Decreases the data area of a network buffer(@p nbuf) by @p size bytes at the 528 * start of the area and returns the pointer to the beginning 529 * of the data area. 530 * 531 * @return Updated pointer to the data in the network buffer if successful, NULL otherwise. 532 */ 533 void *nrf_wifi_osal_nbuf_data_pull(void *nbuf, 534 unsigned int size); 535 536 537 /** 538 * @brief Get the priority of a network buffer. 539 * @param nbuf Pointer to a network buffer. 540 * 541 * Gets the priority of a network buffer. 542 * 543 * @return Priority of the network buffer. 544 */ 545 unsigned char nrf_wifi_osal_nbuf_get_priority(void *nbuf); 546 547 /** 548 * @brief Get the checksum status of a network buffer. 549 * @param nbuf Pointer to a network buffer. 550 * 551 * Get the checksum status of a network buffer. 552 * 553 * @return Checksum status of the network buffer. 554 */ 555 unsigned char nrf_wifi_osal_nbuf_get_chksum_done(void *nbuf); 556 557 /** 558 * @brief Set the checksum status of a network buffer. 559 * @param nbuf Pointer to a network buffer. 560 * @param chksum_done Checksum status of the network buffer. 561 * 562 * Set the checksum status of a network buffer. 563 */ 564 void nrf_wifi_osal_nbuf_set_chksum_done(void *nbuf, 565 unsigned char chksum_done); 566 567 /** 568 * @brief Allocate a tasklet. 569 * @param type Type of tasklet. 570 * 571 * Allocates a tasklet structure and returns a pointer to it. 572 * 573 * @return Pointer to the tasklet instance allocated if successful, otherwise NULL. 574 */ 575 void *nrf_wifi_osal_tasklet_alloc(int type); 576 577 /** 578 * @brief Free a tasklet. 579 * @param tasklet Pointer to a tasklet. 580 * 581 * Frees a tasklet structure that had been allocated using 582 * nrf_wifi_osal_tasklet_alloc(). 583 */ 584 void nrf_wifi_osal_tasklet_free(void *tasklet); 585 586 587 /** 588 * @brief - Initialize a tasklet. 589 * @param tasklet Pointer to a tasklet. 590 * @param callbk_fn Callback function to be invoked by the tasklet. 591 * @param data Data to be passed to the callback function when the tasklet invokes it. 592 * 593 * Initializes a tasklet. 594 */ 595 void nrf_wifi_osal_tasklet_init(void *tasklet, 596 void (*callbk_fn)(unsigned long), 597 unsigned long data); 598 599 600 /** 601 * @brief Schedule a tasklet. 602 * @param tasklet Pointer to a tasklet. 603 * 604 * Schedules a tasklet that had been allocated using 605 * nrf_wifi_osal_tasklet_alloc and initialized using 606 * nrf_wifi_osal_tasklet_init. 607 */ 608 void nrf_wifi_osal_tasklet_schedule(void *tasklet); 609 610 611 /** 612 * @brief Terminate a tasklet. 613 * @param tasklet Pointer to a tasklet. 614 * 615 * Terminates a tasklet(tasklet) that had been scheduled by 616 * nrf_wifi_osal_tasklet_schedule. 617 */ 618 void nrf_wifi_osal_tasklet_kill(void *tasklet); 619 620 621 /** 622 * @brief Sleep for a specified duration in milliseconds. 623 * @param msecs: Sleep duration in milliseconds. 624 * 625 * Puts the calling thread to sleep for at least msecs milliseconds. 626 */ 627 void nrf_wifi_osal_sleep_ms(unsigned int msecs); 628 629 630 /** 631 * @brief Delay for a specified duration in microseconds. 632 * @param usecs Delay duration in microseconds. 633 * 634 * Delays execution of calling thread for usecs microseconds. This is 635 * busy-waiting and won't allow other threads to execute during 636 * the time lapse. 637 */ 638 void nrf_wifi_osal_delay_us(unsigned long usecs); 639 640 641 /** 642 * @brief Get current system uptime in microseconds. 643 * 644 * Get the current system uptime in microseconds. 645 * 646 * @return System uptime in microseconds. 647 */ 648 unsigned long nrf_wifi_osal_time_get_curr_us(void); 649 650 /** 651 * @brief Get elapsed time in microseconds. 652 * @param start_time_us The timestamp in microseconds from which elapsed time is to be measured. 653 * 654 * Get the elapsed system uptime in microseconds. 655 * 656 * @return Elapsed time in microseconds. 657 */ 658 unsigned int nrf_wifi_osal_time_elapsed_us(unsigned long start_time_us); 659 660 /** 661 * nrf_wifi_osal_time_get_curr_ms() - Get current system uptime in milliseconds. 662 * 663 * Gets the current system uptime in milliseconds. 664 * 665 * Return: System uptime in milliseconds. 666 */ 667 unsigned long nrf_wifi_osal_time_get_curr_ms(void); 668 669 /** 670 * nrf_wifi_osal_time_elapsed_ms() - Get elapsed time in milliseconds 671 * @param start_time_ms: The timestamp in milliseconds from which elapsed 672 * time is to be measured. 673 * 674 * Returns the time elapsed in milliseconds since some 675 * time instant (@p start_time_ms). 676 * 677 * Return: Elapsed time in milliseconds. 678 */ 679 unsigned int nrf_wifi_osal_time_elapsed_ms(unsigned long start_time_ms); 680 681 /** 682 * @brief Initialize a PCIe driver. 683 * @param dev_name Name of the PCIe device. 684 * @param vendor_id Vendor ID of the PCIe device. 685 * @param sub_vendor_id Sub-vendor ID of the PCIE device. 686 * @param device_id Device ID of the PCIe device. 687 * @param sub_device_id Sub-device ID of the PCIe device. 688 * 689 * Initializes a PCIe device. 690 * 691 * @return OS specific PCIe device context. 692 */ 693 void *nrf_wifi_osal_bus_pcie_init(const char *dev_name, 694 unsigned int vendor_id, 695 unsigned int sub_vendor_id, 696 unsigned int device_id, 697 unsigned int sub_device_id); 698 699 700 /** 701 * @brief Deinitialize a PCIe device driver. 702 * @param os_pcie_priv OS specific PCIe context. 703 * 704 * This API should be called when the PCIe device driver is to be unregistered from 705 * the OS's PCIe core. 706 */ 707 void nrf_wifi_osal_bus_pcie_deinit(void *os_pcie_priv); 708 709 710 /** 711 * brief Add a PCIe device instance. 712 * @param os_pcie_priv OS specific PCIe context. 713 * @param osal_pcie_dev_ctx: Pointer to the OSAL PCIe device context. 714 */ 715 void *nrf_wifi_osal_bus_pcie_dev_add(void *os_pcie_priv, 716 void *osal_pcie_dev_ctx); 717 718 719 /** 720 * @brief Remove a PCIe device instance. 721 * @param os_pcie_dev_ctx Pointer to the OS specific PCIe device context which was 722 * returned by nrf_wifi_osal_bus_pcie_dev_add. 723 * 724 * Function to be invoked when a matching PCIe device is removed from the system. 725 */ 726 void nrf_wifi_osal_bus_pcie_dev_rem(void *os_pcie_dev_ctx); 727 728 729 /** 730 * @brief Initialize a PCIe device instance. 731 * @param os_pcie_dev_ctx Pointer to the OS specific PCIe device context which was 732 * returned by nrf_wifi_osal_bus_pcie_dev_add. 733 * 734 * Function to be invoked when a PCIe device is to be initialized. 735 * 736 * @return NRF_WIFI_STATUS_SUCCESS if successful, NRF_WIFI_STATUS_FAIL otherwise. 737 */ 738 enum nrf_wifi_status nrf_wifi_osal_bus_pcie_dev_init(void *os_pcie_dev_ctx); 739 740 741 /** 742 * @brief Deinitialize a PCIe device instance. 743 * @param os_pcie_dev_ctx Pointer to the OS specific PCIe device context which was 744 * returned by nrf_wifi_osal_bus_pcie_dev_add. 745 * 746 * Function to be invoked when a PCIe device is to be deinitialized. 747 */ 748 void nrf_wifi_osal_bus_pcie_dev_deinit(void *os_pcie_dev_ctx); 749 750 751 /** 752 * @brief Register an interrupt handler for a PCIe device. 753 * @param os_pcie_dev_ctx OS specific PCIe device context. 754 * @param callbk_data Data to be passed to the ISR. 755 * @param callbk_fn ISR to be invoked on receiving an interrupt. 756 * 757 * Registers an interrupt handler to the OS. This API also passes the callback 758 * data to be passed to the ISR when an interrupt is received. 759 * 760 * @return NRF_WIFI_STATUS_SUCCESS if successful, NRF_WIFI_STATUS_FAIL otherwise. 761 */ 762 enum nrf_wifi_status nrf_wifi_osal_bus_pcie_dev_intr_reg(void *os_pcie_dev_ctx, 763 void *callbk_data, 764 int (*callbk_fn)(void *callbk_data)); 765 766 767 /** 768 * @brief Unregister an interrupt handler for a PCIe device. 769 * @param os_pcie_dev_ctx OS specific PCIe device context. 770 * 771 * Unregisters the interrupt handler that was registered using 772 */ 773 void nrf_wifi_osal_bus_pcie_dev_intr_unreg(void *os_pcie_dev_ctx); 774 775 776 /** 777 * @brief Map host memory for DMA access. 778 * @param os_pcie_dev_ctx Pointer to a OS specific PCIe device handle. 779 * @param virt_addr Virtual host address to be DMA mapped. 780 * @param size Size in bytes of the host memory to be DMA mapped. 781 * @param dir DMA direction. 782 * 783 * Maps host memory of @p size bytes pointed to by the virtual address 784 * @p virt_addr to be used by the device(@p dma_dev) for DMAing contents. 785 * The contents are available for DMAing to the device if @p dir has a 786 * value of NRF_WIFI_OSAL_DMA_DIR_TO_DEV. Conversely the device can DMA 787 * contents to the host memory if @p dir has a value of 788 * NRF_WIFI_OSAL_DMA_DIR_FROM_DEV. The function returns the DMA address 789 * of the mapped memory. 790 */ 791 void *nrf_wifi_osal_bus_pcie_dev_dma_map(void *os_pcie_dev_ctx, 792 void *virt_addr, 793 size_t size, 794 enum nrf_wifi_osal_dma_dir dir); 795 796 797 /** 798 * @brief Unmap DMA mapped host memory. 799 * @param os_pcie_dev_ctx Pointer to a OS specific PCIe device handle. 800 * @param dma_addr DMA mapped physical host memory address. 801 * @param size Size in bytes of the DMA mapped host memory. 802 * @param dir DMA direction. 803 * 804 * Unmaps the host memory which was mapped for DMA using nrf_wifi_osal_dma_map. 805 */ 806 void nrf_wifi_osal_bus_pcie_dev_dma_unmap(void *os_pcie_dev_ctx, 807 void *dma_addr, 808 size_t size, 809 enum nrf_wifi_osal_dma_dir dir); 810 811 812 /** 813 * @brief Get host mapped address for a PCIe device. 814 * @param os_pcie_dev_ctx OS specific PCIe device context. 815 * @param host_map Host map address information. 816 * 817 * Get host mapped address for a PCIe device. 818 */ 819 void nrf_wifi_osal_bus_pcie_dev_host_map_get(void *os_pcie_dev_ctx, 820 struct nrf_wifi_osal_host_map *host_map); 821 822 823 824 825 /** 826 * @brief Initialize a qspi driver. 827 * 828 * Registers a qspi device driver to the OS's qspi core. 829 * 830 * @return OS specific qspi device context. 831 */ 832 void *nrf_wifi_osal_bus_qspi_init(void); 833 834 /** 835 * @brief Deinitialize a qspi device driver. 836 * @param os_qspi_priv OS specific qspi context. 837 * 838 * This API should be called when the qspi device driver is 839 * to be unregistered from the OS's qspi core. 840 */ 841 void nrf_wifi_osal_bus_qspi_deinit(void *os_qspi_priv); 842 843 844 /** 845 * brief Add a qspi device instance. 846 * @param os_qspi_priv OS specific qspi context. 847 * @param osal_qspi_dev_ctx: Pointer to the OSAL qspi device context. 848 * 849 * Function to be invoked when a matching qspi device is added to the system. 850 * It expects the pointer to an OS specific qspi device context to be returned. 851 * 852 * @return OS specific qspi device context. 853 */ 854 void *nrf_wifi_osal_bus_qspi_dev_add(void *os_qspi_priv, 855 void *osal_qspi_dev_ctx); 856 857 858 /** 859 * brief Remove a qspi device instance. 860 * @param os_qspi_dev_ctx: Pointer to the OS specific qspi device context which was 861 * returned by nrf_wifi_osal_bus_qspi_dev_add. 862 * 863 * Function to be invoked when a matching qspi device is removed from the system. 864 */ 865 void nrf_wifi_osal_bus_qspi_dev_rem(void *os_qspi_dev_ctx); 866 867 868 /** 869 * @brief Initialize a qspi device instance. 870 * @param os_qspi_dev_ctx: Pointer to the OS specific qspi device context which was 871 * returned by nrf_wifi_osal_bus_qspi_dev_add. 872 * 873 * Function to be invoked when a qspi device is to be initialized. 874 * 875 * @return 876 * - Pass: NRF_WIFI_STATUS_SUCCESS. 877 * - Fail: NRF_WIFI_STATUS_FAIL. 878 */ 879 enum nrf_wifi_status nrf_wifi_osal_bus_qspi_dev_init(void *os_qspi_dev_ctx); 880 881 882 /** 883 * brief Deinitialize a qspi device instance. 884 * @param os_qspi_dev_ctx: Pointer to the OS specific qspi device context which was 885 * returned by nrf_wifi_osal_bus_qspi_dev_add. 886 * 887 * Function to be invoked when a qspi device is to be deinitialized. 888 */ 889 void nrf_wifi_osal_bus_qspi_dev_deinit(void *os_qspi_dev_ctx); 890 891 892 /** 893 * brief Register a interrupt handler for a qspi device. 894 * @param os_qspi_dev_ctx OS specific qspi device context. 895 * @param callbk_data Data to be passed to the ISR. 896 * @param callbk_fn ISR to be invoked on receiving an interrupt. 897 * 898 * Registers an interrupt handler to the OS. This API also passes the callback 899 * data to be passed to the ISR when an interrupt is received. 900 * 901 * @return NRF_WIFI_STATUS_SUCCESS if successful, NRF_WIFI_STATUS_FAIL otherwise. 902 */ 903 enum nrf_wifi_status nrf_wifi_osal_bus_qspi_dev_intr_reg(void *os_qspi_dev_ctx, 904 void *callbk_data, 905 int (*callbk_fn)(void *callbk_data)); 906 907 908 /** 909 * brief Unregister an interrupt handler for a qspi device. 910 * @param os_qspi_dev_ctx OS specific qspi device context. 911 * 912 * Unregisters the interrupt handler that was registered using 913 * nrf_wifi_osal_bus_qspi_dev_intr_reg. 914 */ 915 void nrf_wifi_osal_bus_qspi_dev_intr_unreg(void *os_qspi_dev_ctx); 916 917 918 /** 919 * @brief Get host mapped address for a qspi device. 920 * @param os_qspi_dev_ctx OS specific qspi device context. 921 * @param host_map Host map address information. 922 * 923 * Gets the host map address for a qspi device. 924 */ 925 void nrf_wifi_osal_bus_qspi_dev_host_map_get(void *os_qspi_dev_ctx, 926 struct nrf_wifi_osal_host_map *host_map); 927 928 /** 929 * @brief Read value from a 32 bit register on a QSPI slave device. 930 * @param priv 931 * @param addr Address of the register to read from. 932 * 933 * @return 32 bit value read from register. 934 */ 935 unsigned int nrf_wifi_osal_qspi_read_reg32(void *priv, 936 unsigned long addr); 937 938 /** 939 * @brief Writes a 32 bit value to a 32 bit device register on a QSPI slave device. 940 * @param priv 941 * @param addr Address of the register to write to. 942 * @param val Value to be written to the register. 943 */ 944 void nrf_wifi_osal_qspi_write_reg32(void *priv, 945 unsigned long addr, 946 unsigned int val); 947 948 /** 949 * @brief Copies data from a QSPI slave device to a destination buffer. 950 * @param priv 951 * @param dest Destination buffer. 952 * @param addr Address of the data to be copied. 953 * @param count Number of bytes to be copied. 954 */ 955 void nrf_wifi_osal_qspi_cpy_from(void *priv, 956 void *dest, 957 unsigned long addr, 958 size_t count); 959 960 /** 961 * @brief Copies data from a source buffer to a QSPI slave device. 962 * @param priv 963 * @param addr Address of the data to be written. 964 * @param src Source buffer. 965 * @param count Number of bytes to be copied. 966 */ 967 void nrf_wifi_osal_qspi_cpy_to(void *priv, 968 unsigned long addr, 969 const void *src, 970 size_t count); 971 972 /** 973 * @brief Initialize a spi driver. 974 * 975 * Registers a spi device driver to the OS's spi core. 976 * 977 * @return OS specific spi device context. 978 */ 979 void *nrf_wifi_osal_bus_spi_init(void); 980 981 /** 982 * @brief Deinitialize a spi device driver. 983 * @param os_spi_priv OS specific spi context. 984 * 985 * This API should be called when the spi device driver is 986 * to be unregistered from the OS's spi core. 987 */ 988 void nrf_wifi_osal_bus_spi_deinit(void *os_spi_priv); 989 990 991 /** 992 * brief Add a spi device instance. 993 * @param os_spi_priv OS specific spi context. 994 * @param osal_spi_dev_ctx Pointer to the OSAL spi device context. 995 * 996 * Function to be invoked when a matching spi device is added to the system. 997 * It expects the pointer to a OS specific spi device context to be returned. 998 * 999 * @return OS specific spi device context. 1000 */ 1001 void *nrf_wifi_osal_bus_spi_dev_add(void *os_spi_priv, 1002 void *osal_spi_dev_ctx); 1003 1004 1005 /** 1006 * @brief Remove a spi device instance. 1007 * @param os_spi_dev_ctx Pointer to the OS specific spi device context which was 1008 * returned by nrf_wifi_osal_bus_spi_dev_add. 1009 * 1010 * Function to be invoked when a matching spi device is removed from the system. 1011 */ 1012 void nrf_wifi_osal_bus_spi_dev_rem(void *os_spi_dev_ctx); 1013 1014 1015 /** 1016 * @brief Initialize a spi device instance. 1017 * @param os_spi_dev_ctx Pointer to the OS specific spi device context which was 1018 * returned by nrf_wifi_osal_bus_spi_dev_add. 1019 * 1020 * Function to be invoked when a spi device is to be initialized. 1021 * 1022 * @return 1023 * - Pass: nrf_wifi_STATUS_SUCCESS. 1024 * - Fail: nrf_wifi_STATUS_FAIL. 1025 */ 1026 enum nrf_wifi_status nrf_wifi_osal_bus_spi_dev_init(void *os_spi_dev_ctx); 1027 1028 1029 /** 1030 * @brief Deinitialize a spi device instance. 1031 * @param os_spi_dev_ctx Pointer to the OS specific spi device context which was 1032 * returned by nrf_wifi_osal_bus_spi_dev_add. 1033 * 1034 * Function to be invoked when a spi device is to be deinitialized. 1035 */ 1036 void nrf_wifi_osal_bus_spi_dev_deinit(void *os_spi_dev_ctx); 1037 1038 1039 /** 1040 * @brief Register a interrupt handler for a spi device. 1041 * @param os_spi_dev_ctx OS specific spi device context. 1042 * @param callbk_data Data to be passed to the ISR. 1043 * @param callbk_fn ISR to be invoked on receiving an interrupt. 1044 * 1045 * Registers an interrupt handler to the OS. This API also passes the callback 1046 * data to be passed to the ISR when an interrupt is received. 1047 * 1048 * @return 1049 * Pass: nrf_wifi_STATUS_SUCCESS. 1050 * Fail: nrf_wifi_STATUS_FAIL. 1051 */ 1052 enum nrf_wifi_status nrf_wifi_osal_bus_spi_dev_intr_reg(void *os_spi_dev_ctx, 1053 void *callbk_data, 1054 int (*callbk_fn)(void *callbk_data)); 1055 1056 1057 /** 1058 * @brief Unregister an interrupt handler for a spi device. 1059 * @param os_spi_dev_ctx OS specific spi device context. 1060 * 1061 * Unregisters the interrupt handler that was registered using 1062 * nrf_wifi_osal_bus_spi_dev_intr_reg. 1063 */ 1064 void nrf_wifi_osal_bus_spi_dev_intr_unreg(void *os_spi_dev_ctx); 1065 1066 1067 /** 1068 * @brief Get host mapped address for a spi device. 1069 * @param os_spi_dev_ctx OS specific spi device context. 1070 * @param host_map Host map address information. 1071 * 1072 * Get the host map address for a spi device. 1073 */ 1074 void nrf_wifi_osal_bus_spi_dev_host_map_get(void *os_spi_dev_ctx, 1075 struct nrf_wifi_osal_host_map *host_map); 1076 1077 /** 1078 * @brief Read value from a 32 bit register on a SPI slave device. 1079 * @param priv 1080 * @param addr Address of the register to read from. 1081 * 1082 * @return 32 bit value read from register. 1083 */ 1084 unsigned int nrf_wifi_osal_spi_read_reg32(void *priv, 1085 unsigned long addr); 1086 1087 /** 1088 * @brief Writes a 32 bit value to a 32 bit device register on a SPI slave device. 1089 * @param priv 1090 * @param addr Address of the register to write to. 1091 * @param val Value to be written to the register. 1092 */ 1093 void nrf_wifi_osal_spi_write_reg32(void *priv, 1094 unsigned long addr, 1095 unsigned int val); 1096 1097 /** 1098 * @brief Copies data from a SPI slave device to a destination buffer. 1099 * @param priv 1100 * @param dest Destination buffer. 1101 * @param addr Address of the register to read from. 1102 * @param count Number of bytes to copy. 1103 */ 1104 void nrf_wifi_osal_spi_cpy_from(void *priv, 1105 void *dest, 1106 unsigned long addr, 1107 size_t count); 1108 1109 /** 1110 * @brief Copies data from a source buffer to a SPI slave device. 1111 * @param priv 1112 * @param addr Address of the register to write to. 1113 * @param src Source buffer. 1114 * @param count Number of bytes to copy. 1115 */ 1116 void nrf_wifi_osal_spi_cpy_to(void *priv, 1117 unsigned long addr, 1118 const void *src, 1119 size_t count); 1120 1121 1122 #if defined(NRF_WIFI_LOW_POWER) || defined(__DOXYGEN__) 1123 /** 1124 * @brief Allocate a timer. 1125 * 1126 * Allocates a timer instance and returns a pointer to it. 1127 * 1128 * @return Pointer to the allocated timer instance. 1129 */ 1130 void *nrf_wifi_osal_timer_alloc(void); 1131 1132 /** 1133 * @brief Free a timer. 1134 * @param timer Pointer to a timer instance. 1135 * 1136 * Frees/Deallocates a timer that has been allocated using nrf_wifi_osal_timer_alloc 1137 */ 1138 void nrf_wifi_osal_timer_free(void *timer); 1139 1140 1141 /** 1142 * @brief Initialize a timer. 1143 * @param timer Pointer to a timer instance. 1144 * @param callbk_fn Callback function to be invoked when the timer expires. 1145 * @param data Data to be passed to the callback function. 1146 * 1147 * Initializes a timer that has been allocated using nrf_wifi_osal_timer_alloc 1148 * Need to pass (@p callbk_fn) callback function with the data(@p data) to be 1149 * passed to the callback function, whenever the timer expires. 1150 */ 1151 void nrf_wifi_osal_timer_init(void *timer, 1152 void (*callbk_fn)(unsigned long), 1153 unsigned long data); 1154 1155 1156 /** 1157 * @brief Schedule a timer. 1158 * @param timer Pointer to a timer instance. 1159 * @param duration Duration of the timer in seconds. 1160 * 1161 * Schedules a timer with a @p duration seconds that has been allocated using 1162 * nrf_wifi_osal_timer_alloc and initialized with nrf_wifi_osal_timer_init. 1163 */ 1164 void nrf_wifi_osal_timer_schedule(void *timer, 1165 unsigned long duration); 1166 1167 1168 /** 1169 * @brief Kills a timer. 1170 * @param timer Pointer to a timer instance. 1171 */ 1172 void nrf_wifi_osal_timer_kill(void *timer); 1173 1174 /** 1175 * @brief Puts the QSPI interface to sleep. 1176 * @param os_qspi_priv Pointer to the QSPI private data. 1177 * 1178 * @return 0 on success, negative error code on failure. 1179 */ 1180 int nrf_wifi_osal_bus_qspi_ps_sleep(void *os_qspi_priv); 1181 1182 /** 1183 * @brief Wakes up the QSPI interface from sleep. 1184 * @param os_qspi_priv Pointer to the QSPI private data. 1185 * 1186 * @return 0 on success, negative error code on failure. 1187 */ 1188 int nrf_wifi_osal_bus_qspi_ps_wake(void *os_qspi_priv); 1189 1190 /** 1191 * @brief Get the power status of a QSPI interface. 1192 * @param os_qspi_priv Pointer to the QSPI private data. 1193 * 1194 * @return 0 if the QSPI interface is in sleep mode, 1195 * 1 if it is awake, 1196 * Negative error code on failure. 1197 */ 1198 int nrf_wifi_osal_bus_qspi_ps_status(void *os_qspi_priv); 1199 #endif /* NRF_WIFI_LOW_POWER */ 1200 1201 /** 1202 * @brief nrf_wifi_osal_assert() - Assert a condition with a value. 1203 * @param test Variable to be tested. 1204 * @param val Value to be checked for the @p test 1205 * @param op Type of operation to be done during assertion check. 1206 * @param msg Assertion message. 1207 * 1208 * Compares @p test with @p val. If true, prints assert message. 1209 */ 1210 void nrf_wifi_osal_assert(int test, 1211 int val, 1212 enum nrf_wifi_assert_op_type op, 1213 char *msg); 1214 1215 /** 1216 * @brief Gives the length of the string @p str. 1217 * @param str: Pointer to the memory location of the string. 1218 * 1219 * Calculates the length of the string pointed to by str. 1220 * 1221 * @return The number of bytes of the string str. 1222 */ 1223 unsigned int nrf_wifi_osal_strlen(const void *str); 1224 1225 /** 1226 * @brief Compare contents from one memory location to another. 1227 * @param addr1 Pointer to the memory location of first address. 1228 * @param addr2 Pointer to the memory location of second address. 1229 * @param count Number of bytes to be compared. 1230 * 1231 * Compares count number of bytes from addr1 location in memory to addr2 1232 * location in memory. 1233 * 1234 * @return An integer less than, equal to, or greater than zero. 1235 */ 1236 int nrf_wifi_osal_mem_cmp(const void *addr1, 1237 const void *addr2, 1238 size_t count); 1239 1240 /** 1241 * nrf_wifi_osal_rand8_get() - Get a random 8 bit number. 1242 * 1243 * Generates an 8 bit random number. 1244 * 1245 * Return: 1246 * returns an 8 bit random number. 1247 */ 1248 unsigned char nrf_wifi_osal_rand8_get(void); 1249 #endif /* __OSAL_API_H__ */ 1250
