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