1 /* 2 * Copyright 2022, Cypress Semiconductor Corporation (an Infineon company) 3 * SPDX-License-Identifier: Apache-2.0 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 /** @file whd_network_types.h 19 * Prototypes of functions corresponding to Buffer and Network Interface 20 * 21 * This file provides prototypes for functions which allows different functionalities related to: 22 * - Buffer Interface: Allocate and release a packet buffer, Retrieve the current pointer and size of a packet buffer, etc. 23 * - Network Interface: Called by WHD to pass received data to the network stack, to send an ethernet frame to WHD, etc. 24 */ 25 #include "whd.h" 26 27 #ifndef INC_WHD_NETWORK_TYPES_H_ 28 #define INC_WHD_NETWORK_TYPES_H_ 29 30 #ifdef __cplusplus 31 extern "C" 32 { 33 #endif 34 35 /****************************************************** 36 * Constants 37 ******************************************************/ 38 /** @addtogroup buffif WHD Buffer Interface API 39 * Allows WHD to perform buffer related operations like, allocating, releasing, retrieving the current pointer of and size of a packet buffer. 40 * @{ 41 */ 42 43 /** 44 * Indicates transmit/receive direction that the packet buffer has 45 * been used for. This is needed if tx/rx pools are separate. 46 */ 47 typedef enum 48 { 49 WHD_NETWORK_TX, /**< Transmit direction */ 50 WHD_NETWORK_RX /**< Recieve direction */ 51 } whd_buffer_dir_t; 52 53 /** 54 * Allows WHD to perform buffer related operations like, allocating, releasing, retrieving the current pointer of and size of a packet buffer. 55 */ 56 struct whd_buffer_funcs 57 { 58 /** Allocates a packet buffer 59 * 60 * Implemented in the port layer interface which is specific to the 61 * buffering scheme in use. 62 * Attempts to allocate a packet buffer of the size requested. It can do this 63 * by allocating a pre-existing packet from a pool, using a static buffer, 64 * or by dynamically allocating memory. The method of allocation does not 65 * concern WHD, however it must match the way the network stack expects packet 66 * buffers to be allocated. Usually WHD requires packet of size of WHD_LINK_MTU 67 * which includes the MTU, other other various header. Refer to whd_types.h 68 * to find the size of WHD_LINK_MTU 69 * 70 * @param buffer A pointer which receives the allocated packet buffer handle 71 * @param direction Indicates transmit/receive direction that the packet buffer is 72 * used for. This may be needed if tx/rx pools are separate. 73 * @param size The number of bytes to allocate. 74 * @param timeout_ms Maximum period to block for available buffer 75 * 76 * @return WHD_SUCCESS or error code 77 * 78 */ 79 whd_result_t (*whd_host_buffer_get)(whd_buffer_t *buffer, whd_buffer_dir_t direction, uint16_t size, 80 uint32_t timeout_ms); 81 82 /** Releases a packet buffer 83 * 84 * Implemented in the port layer interface, which will be specific to the 85 * buffering scheme in use. 86 * This function is used by WHD to indicate that it no longer requires 87 * a packet buffer. The buffer can then be released back into a pool for 88 * reuse, or the dynamically allocated memory can be freed, according to 89 * how the packet was allocated. 90 * Returns void since WHD cannot do anything about failures 91 * 92 * @param buffer The handle of the packet buffer to be released 93 * @param direction Indicates transmit/receive direction that the packet buffer has 94 * been used for. This might be needed if tx/rx pools are separate. 95 * 96 */ 97 void (*whd_buffer_release)(whd_buffer_t buffer, whd_buffer_dir_t direction); 98 99 /** Retrieves the current pointer of a packet buffer 100 * 101 * Implemented in the port layer interface which is specific to the 102 * buffering scheme in use. 103 * Since packet buffers usually need to be created with space at the 104 * front for additional headers, this function allows WHD to get 105 * the current 'front' location pointer. 106 * 107 * @param buffer The handle of the packet buffer whose pointer is to be retrieved 108 * 109 * @return The packet buffer's current pointer. 110 */ 111 uint8_t *(*whd_buffer_get_current_piece_data_pointer)(whd_buffer_t buffer); 112 113 /** Retrieves the size of a packet buffer 114 * 115 * Implemented in the port layer interface which is specific to the 116 * buffering scheme in use. 117 * Since packet buffers usually need to be created with space at the 118 * front for additional headers, the memory block use to contain a packet buffer 119 * will often be larger than the current size of the packet buffer data. 120 * This function allows WHD to retrieve the current size of a packet buffer's data. 121 * 122 * @param buffer The handle of the packet buffer whose size is to be retrieved 123 * 124 * @return The size of the packet buffer. 125 */ 126 uint16_t (*whd_buffer_get_current_piece_size)(whd_buffer_t buffer); 127 128 /** Sets the current size of a WHD packet 129 * 130 * Implemented in the port layer interface which is specific to the 131 * buffering scheme in use. 132 * This function sets the current length of a WHD packet buffer 133 * 134 * @param buffer The packet to be modified 135 * @param size The new size of the packet buffer 136 * 137 * @return WHD_SUCCESS or error code 138 */ 139 whd_result_t (*whd_buffer_set_size)(whd_buffer_t buffer, uint16_t size); 140 141 /** Moves the current pointer of a packet buffer 142 * 143 * Implemented in the port layer interface which is specific to the buffering scheme in use. 144 * 145 * Since packet buffers usually need to be created with space at the front for additional headers, 146 * this function allows WHD to move the current 'front' location pointer so that it has space to 147 * add headers to transmit packets, and so that the network stack does not see the internal WHD 148 * headers on received packets. 149 * 150 * @param buffer A pointer to the handle of the current packet buffer for which the 151 * current pointer will be moved. On return this may contain a pointer 152 * to a newly allocated packet buffer which has been daisy chained to 153 * the front of the given packet buffer. This would be the case if the given packet 154 * buffer didn't have enough space at the front. 155 * @param add_remove_amount This is the number of bytes to move the current pointer of the packet 156 * buffer - a negative value increases the space for headers at the front 157 * of the packet, a positive value decreases the space. 158 * 159 * @return WHD_SUCCESS or error code 160 */ 161 whd_result_t (*whd_buffer_add_remove_at_front)(whd_buffer_t *buffer, int32_t add_remove_amount); 162 }; 163 /* @} */ 164 165 /** @addtogroup netif WHD Network Interface API 166 * Allows WHD to pass received data to the network stack, to send an ethernet frame to WHD, etc. 167 * @{ 168 */ 169 170 /** 171 * Contains functions which allows WHD to pass received data to the network stack, to send an ethernet frame to WHD, etc 172 */ 173 struct whd_netif_funcs 174 { 175 /** Called by WHD to pass received data to the network stack 176 * 177 * 178 * Packets received from the Wi-Fi network by WHD are forwarded to by calling function ptr which 179 * must be implemented in the network interface. Ethernet headers 180 * are present at the start of these packet buffers. 181 * 182 * This function is called asynchronously in the context of the 183 * WHD thread whenever new data has arrived. 184 * Packet buffers are allocated within WHD, and ownership is transferred 185 * to the network stack. The network stack or application is thus 186 * responsible for releasing the packet buffers. 187 * Most packet buffering systems have a pointer to the 'current point' within 188 * the packet buffer. When this function is called, the pointer points 189 * to the start of the Ethernet header. There is other inconsequential data 190 * before the Ethernet header. 191 * 192 * It is preferable that the (whd_network_process_ethernet_data)() function simply puts 193 * the received packet on a queue for processing by another thread. This avoids the 194 * WHD thread being unnecessarily tied up which would delay other packets 195 * being transmitted or received. 196 * 197 * @param interface The interface on which the packet was received. 198 * @param buffer Handle of the packet which has just been received. Responsibility for 199 * releasing this buffer is transferred from WHD at this point. 200 * 201 */ 202 void (*whd_network_process_ethernet_data)(whd_interface_t ifp, whd_buffer_t buffer); 203 }; 204 205 /** To send an ethernet frame to WHD (called by the Network Stack) 206 * 207 * This function takes ethernet data from the network stack and queues it for transmission over the wireless network. 208 * The function can be called from any thread context as it is thread safe, however 209 * it must not be called from interrupt context since it might get blocked while waiting 210 * for a lock on the transmit queue. 211 * 212 * This function returns immediately after the packet has been queued for transmit, 213 * NOT after it has been transmitted. Packet buffers passed to the WHD 214 * are released inside the WHD once they have been transmitted. 215 * 216 * @param ifp Pointer to handle instance of whd interface 217 * @param buffer Handle of the packet buffer to be sent. 218 * 219 * @return WHD_SUCCESS or Error code 220 * 221 */ 222 extern whd_result_t whd_network_send_ethernet_data(whd_interface_t ifp, whd_buffer_t buffer); 223 /* @} */ 224 225 226 #ifdef __cplusplus 227 } /*extern "C" */ 228 #endif 229 #endif /* INC_WHD_NETWORK_TYPES_H_ */ 230
