1 /***********************************************************************************************//** 2 * \file cy_network_buffer.h 3 * 4 * \brief 5 * Basic set of APIs for dealing with network packet buffers. This is used by WHD 6 * for relaying data between the network stack and the connectivity chip. 7 * 8 *************************************************************************************************** 9 * \copyright 10 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 11 * an affiliate of Cypress Semiconductor Corporation 12 * 13 * SPDX-License-Identifier: Apache-2.0 14 * 15 * Licensed under the Apache License, Version 2.0 (the "License"); 16 * you may not use this file except in compliance with the License. 17 * You may obtain a copy of the License at 18 * 19 * http://www.apache.org/licenses/LICENSE-2.0 20 * 21 * Unless required by applicable law or agreed to in writing, software 22 * distributed under the License is distributed on an "AS IS" BASIS, 23 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 24 * See the License for the specific language governing permissions and 25 * limitations under the License. 26 **************************************************************************************************/ 27 28 /** 29 * \addtogroup group_bsp_network_buffer Buffer management 30 * \{ 31 * Basic set of APIs for dealing with network packet buffers 32 */ 33 34 #pragma once 35 36 #include <stdint.h> 37 #include <stdbool.h> 38 #include "cy_result.h" 39 #include "whd.h" 40 #include "whd_network_types.h" 41 42 #if defined(__cplusplus) 43 extern "C" { 44 #endif 45 46 47 /** Initialize the buffer pools 48 * 49 * Initialize the buffer pools used by the buffer management routines. 50 * A pair of pools, one for RX buffers and one for TX buffers in passed 51 * in for use by the management routines. 52 * 53 * Not all implementations use preallocated buffer pools. 54 * 55 * @param tx_packet_pool : Pointer to the initialized NetXDuo TX packet buffer pool 56 * @param rx_packet_pool : Pointer to the initialized NetXDuo RX packet buffer pool 57 * 58 * @return : CY_RSLT_SUCCESS or WHD_BADARG 59 */ 60 whd_result_t cy_buffer_pool_init(void* tx_packet_pool, void* rx_packet_pool); 61 62 /** Allocates a packet buffer 63 * 64 * Attempts to allocate a packet buffer of the size requested. It can do this 65 * by allocating a pre-existing packet from a pool, using a static buffer, 66 * or by dynamically allocating memory. The method of allocation does not 67 * concern WHD, however it must match the way the network stack expects packet 68 * buffers to be allocated. Usually WHD requires packet of size of WHD_LINK_MTU 69 * which includes the MTU. Refer to whd_types.h to find the size of WHD_LINK_MTU. 70 * 71 * @param buffer : A pointer which receives the allocated packet buffer handle 72 * @param direction : Indicates transmit/receive direction that the packet buffer is 73 * used for. This may be needed if tx/rx pools are separate. 74 * @param size : The number of bytes to allocate. 75 * @param timeout_ms: Time to wait for a packet buffer to be available 76 * 77 * @return : CY_RSLT_SUCCESS or WHD_BUFFER_ALLOC_FAIL if the buffer could not be allocated 78 */ 79 whd_result_t cy_host_buffer_get(whd_buffer_t* buffer, whd_buffer_dir_t direction, 80 uint16_t size, uint32_t timeout_ms); 81 82 /** Releases a packet buffer 83 * 84 * This function is used by WHD to indicate that it no longer requires 85 * a packet buffer. The buffer can then be released back into a pool for 86 * reuse, or the dynamically allocated memory can be freed, according to 87 * how the packet was allocated. 88 * Returns void since WHD cannot do anything about failures 89 * 90 * @param buffer : The handle of the packet buffer to be released 91 * @param direction : Indicates transmit/receive direction that the packet buffer has 92 * been used for. This might be needed if tx/rx pools are separate. 93 */ 94 void cy_buffer_release(whd_buffer_t buffer, whd_buffer_dir_t direction); 95 96 /** Retrieves the current pointer of a packet buffer 97 * 98 * Since packet buffers usually need to be created with space at the 99 * front for additional headers, this function allows WHD to get 100 * the current 'front' location pointer. 101 * 102 * @param buffer : The handle of the packet buffer whose pointer is to be retrieved 103 * 104 * @return : The packet buffer's current pointer. 105 */ 106 uint8_t* cy_buffer_get_current_piece_data_pointer(whd_buffer_t buffer); 107 108 /** Retrieves the size of a packet buffer 109 * 110 * Since packet buffers usually need to be created with space at the 111 * front for additional headers, the memory block used to contain a packet buffer 112 * will often be larger than the current size of the packet buffer data. 113 * This function allows WHD to retrieve the current size of a packet buffer's data. 114 * 115 * @param buffer : The handle of the packet buffer whose size is to be retrieved 116 * 117 * @return : The size of the packet buffer. 118 */ 119 uint16_t cy_buffer_get_current_piece_size(whd_buffer_t buffer); 120 121 /** Sets the current size of a WHD packet 122 * 123 * This function sets the current length of a WHD packet buffer 124 * 125 * @param buffer : The packet to be modified 126 * @param size : The new size of the packet buffer 127 * 128 * @return : CY_RSLT_SUCCESS or WHD_BUFFER_SIZE_SET_ERROR if the requested size is not valid 129 */ 130 whd_result_t cy_buffer_set_size(whd_buffer_t buffer, uint16_t size); 131 132 /** Moves the current pointer of a packet buffer 133 * 134 * Since packet buffers usually need to be created with space at the front for additional headers, 135 * this function allows WHD to move the current 'front' location pointer so that it has space to 136 * add headers to transmit packets, and so that the network stack does not see the internal WHD 137 * headers on received packets. 138 * 139 * @param buffer : A pointer to the handle of the current packet buffer for which the 140 * current pointer will be moved. On return this may contain a pointer 141 * to a newly allocated packet buffer which has been daisy chained to 142 * the front of the given one. This would be the case if the given 143 * packet buffer didn't have enough space at the front. 144 * @param add_remove_amount : This is the number of bytes to move the current pointer of the packet 145 * buffer - a negative value increases the space for headers at the 146 * front of the packet, a positive value decreases the space. 147 * 148 * @return : CY_RSLT_SUCCESS or WHD_BUFFER_POINTER_MOVE_ERROR if the added amount 149 * is outside the size of the buffer 150 */ 151 whd_result_t cy_buffer_add_remove_at_front(whd_buffer_t* buffer, int32_t add_remove_amount); 152 153 154 /** Called by WHD to pass received data to the network stack 155 * 156 * Packets received from the Wi-Fi network by WHD are forwarded to by calling function ptr which 157 * must be implemented in the network interface. Ethernet headers 158 * are present at the start of these packet buffers. 159 * 160 * This function is called asynchronously in the context of the 161 * WHD thread whenever new data has arrived. 162 * Packet buffers are allocated within WHD, and ownership is transferred 163 * to the network stack. The network stack or application is thus 164 * responsible for releasing the packet buffers. 165 * Most packet buffering systems have a pointer to the 'current point' within 166 * the packet buffer. When this function is called, the pointer points 167 * to the start of the Ethernet header. There is other inconsequential data 168 * before the Ethernet header. 169 * 170 * It is preferable that the (whd_network_process_ethernet_data)() function simply puts 171 * the received packet on a queue for processing by another thread. This avoids the 172 * WHD thread being unnecessarily tied up which would delay other packets 173 * being transmitted or received. 174 * 175 * @param interface : The interface on which the packet was received. 176 * @param buffer : Handle of the packet which has just been received. Responsibility for 177 * releasing this buffer is transferred from WHD at this point. 178 * 179 */ 180 void cy_network_process_ethernet_data(whd_interface_t interface, whd_buffer_t buffer); 181 182 183 #ifdef __cplusplus 184 } 185 #endif // __cplusplus 186 187 /** \} group_bsp_network_buffer */ 188
