Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
whd_network_types.h
Go to the documentation of this file.
1 /*
2  * Copyright 2021, 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, unsigned short size,
80  unsigned long 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, unsigned short 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 void 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 
whd_buffer_funcs::whd_buffer_release
void(* whd_buffer_release)(whd_buffer_t buffer, whd_buffer_dir_t direction)
Releases a packet buffer.
Definition: whd_network_types.h:97
whd_netif_funcs
Contains functions which allows WHD to pass received data to the network stack, to send an ethernet f...
Definition: whd_network_types.h:173
whd.h
Provides abstract pointer type to act as instance for: driver, interface, buffer funcs, network funcs, resource funcs and bus funcs.
whd_network_process_ethernet_data
whd_result_t whd_network_process_ethernet_data(whd_interface_t ifp, whd_buffer_t buffer)
Called by WHD to pass received data to the network stack.
whd_result_t
uint32_t whd_result_t
WHD result is specified as uint32_t value.
Definition: whd_types.h:776
whd_buffer_funcs::whd_host_buffer_get
whd_result_t(* whd_host_buffer_get)(whd_buffer_t *buffer, whd_buffer_dir_t direction, unsigned short size, unsigned long timeout_ms)
Allocates a packet buffer.
Definition: whd_network_types.h:79
whd_network_send_ethernet_data
void whd_network_send_ethernet_data(whd_interface_t ifp, whd_buffer_t buffer)
To send an ethernet frame to WHD (called by the Network Stack)
whd_buffer_funcs
Allows WHD to perform buffer related operations like, allocating, releasing, retrieving the current p...
Definition: whd_network_types.h:56
WHD_NETWORK_TX
Transmit direction.
Definition: whd_network_types.h:49
WHD_NETWORK_RX
Recieve direction.
Definition: whd_network_types.h:50
whd_buffer_funcs::whd_buffer_set_size
whd_result_t(* whd_buffer_set_size)(whd_buffer_t buffer, unsigned short size)
Sets the current size of a WHD packet.
Definition: whd_network_types.h:139
whd_buffer_funcs::whd_buffer_add_remove_at_front
whd_result_t(* whd_buffer_add_remove_at_front)(whd_buffer_t *buffer, int32_t add_remove_amount)
Moves the current pointer of a packet buffer.
Definition: whd_network_types.h:161
whd_buffer_dir_t
whd_buffer_dir_t
Indicates transmit/receive direction that the packet buffer has been used for.
Definition: whd_network_types.h:47
whd_buffer_funcs::whd_buffer_get_current_piece_size
uint16_t(* whd_buffer_get_current_piece_size)(whd_buffer_t buffer)
Retrieves the size of a packet buffer.
Definition: whd_network_types.h:126
whd_interface
Definition: whd_int.h:59
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.