Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
whd_buffer_api.h
Go to the documentation of this file.
1 /*
2  * Copyright 2020 Cypress Semiconductor Corporation
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
19  * Provides prototypes / declarations for common APSTA functionality
20  */
21 #ifndef _WHD_INTERNAL_BUFFER_API_H_
22 #define _WHD_INTERNAL_BUFFER_API_H_
23 
24 #include "whd.h"
25 #include "whd_int.h"
26 
27 #ifdef __cplusplus
28 extern "C"
29 {
30 #endif
31 
32 /******************************************************
33 * Macros
34 ******************************************************/
35 
36 /******************************************************
37 * Structures
38 ******************************************************/
39 
40 /******************************************************
41 * Function prototypes
42 ******************************************************/
43 /** Allocates a packet buffer
44  *
45  * Implemented in the port layer interface which is specific to the
46  * buffering scheme in use.
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.
52  *
53  * @param buffer : A pointer which receives the allocated packet buffer handle
54  * @param direction : Indicates transmit/receive direction that the packet buffer is
55  * used for. This may be needed if tx/rx pools are separate.
56  * @param size : The number of bytes to allocate.
57  * @param wait : Whether to wait for a packet buffer to be available
58  *
59  * @return : WHD_SUCCESS or error code
60  *
61  */
62 whd_result_t whd_host_buffer_get(whd_driver_t whd_driver, whd_buffer_t *buffer, whd_buffer_dir_t direction,
63  uint16_t size, uint32_t wait);
64 
65 /** Releases a packet buffer
66  *
67  * Implemented in the port layer interface, which will be specific to the
68  * buffering scheme in use.
69  * This function is used by WHD to indicate that it no longer requires
70  * a packet buffer. The buffer can then be released back into a pool for
71  * reuse, or the dynamically allocated memory can be freed, according to
72  * how the packet was allocated.
73  * Returns void since WHD cannot do anything about failures
74  *
75  * @param buffer : The handle of the packet buffer to be released
76  * @param direction : Indicates transmit/receive direction that the packet buffer has
77  * been used for. This might be needed if tx/rx pools are separate.
78  *
79  */
80 whd_result_t whd_buffer_release(whd_driver_t whd_driver, whd_buffer_t buffer, whd_buffer_dir_t direction);
81 
82 /** Retrieves the current pointer of a packet buffer
83  *
84  * Implemented in the port layer interface which is specific to the
85  * buffering scheme in use.
86  * Since packet buffers usually need to be created with space at the
87  * front for additional headers, this function allows WHD to get
88  * the current 'front' location pointer.
89  *
90  * @param buffer : The handle of the packet buffer whose pointer is to be retrieved
91  *
92  * @return : The packet buffer's current pointer.
93  */
94 uint8_t *whd_buffer_get_current_piece_data_pointer(whd_driver_t whd_driver, whd_buffer_t buffer);
95 
96 /** Retrieves the size of a packet buffer
97  *
98  * Implemented in the port layer interface which is specific to the
99  * buffering scheme in use.
100  * Since packet buffers usually need to be created with space at the
101  * front for additional headers, the memory block used to contain a packet buffer
102  * will often be larger than the current size of the packet buffer data.
103  * This function allows WHD to retrieve the current size of a packet buffer's data.
104  *
105  * @param buffer : The handle of the packet buffer whose size is to be retrieved
106  *
107  * @return : The size of the packet buffer.
108  */
109 uint16_t whd_buffer_get_current_piece_size(whd_driver_t whd_driver, whd_buffer_t buffer);
110 
111 /** Sets the current size of a WHD packet
112  *
113  *
114  * Implemented in the port layer interface which is specific to the
115  * buffering scheme in use.
116  * This function sets the current length of a WHD packet buffer
117  *
118  * @param buffer : The packet to be modified
119  * @param size : The new size of the packet buffer
120  *
121  * @return : WHD_SUCCESS or error code
122  */
123 whd_result_t whd_buffer_set_size(whd_driver_t whd_driver, whd_buffer_t buffer, uint16_t size);
124 
125 /** Moves the current pointer of a packet buffer
126  *
127  * Implemented in the port layer interface which is specific to the buffering scheme in use.
128  *
129  * Since packet buffers usually need to be created with space at the front for additional headers,
130  * this function allows WHD to move the current 'front' location pointer so that it has space to
131  * add headers to transmit packets, and so that the network stack does not see the internal WHD
132  * headers on received packets.
133  *
134  * @param buffer : A pointer to the handle of the current packet buffer for which the
135  * current pointer will be moved. On return this may contain a pointer
136  * to a newly allocated packet buffer which has been daisy chained to
137  * the front of the given one. This would be the case if the given packet
138  * buffer didn't have enough space at the front.
139  * @param add_remove_amount : This is the number of bytes to move the current pointer of the packet
140  * buffer - a negative value increases the space for headers at the front
141  * of the packet, a positive value decreases the space.
142  *
143  * @return : WHD_SUCCESS or error code
144  */
145 whd_result_t whd_buffer_add_remove_at_front(whd_driver_t whd_driver, whd_buffer_t *buffer, int32_t add_remove_amount);
146 #ifdef __cplusplus
147 } /*extern "C" */
148 #endif
149 
150 #endif /* ifndef _WHD_INTERNAL_BUFFER_API_H_ */
151 
whd_buffer_get_current_piece_size
uint16_t whd_buffer_get_current_piece_size(whd_driver_t whd_driver, whd_buffer_t buffer)
Retrieves the size of a packet buffer.
whd.h
Provides abstract pointer type to act as instance for: driver, interface, buffer funcs, network funcs, resource funcs and bus funcs.
whd_buffer_set_size
whd_result_t whd_buffer_set_size(whd_driver_t whd_driver, whd_buffer_t buffer, uint16_t size)
Sets the current size of a WHD packet.
whd_buffer_get_current_piece_data_pointer
uint8_t * whd_buffer_get_current_piece_data_pointer(whd_driver_t whd_driver, whd_buffer_t buffer)
Retrieves the current pointer of a packet buffer.
whd_driver
Definition: whd_int.h:72
whd_buffer_add_remove_at_front
whd_result_t whd_buffer_add_remove_at_front(whd_driver_t whd_driver, whd_buffer_t *buffer, int32_t add_remove_amount)
Moves the current pointer 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
whd_host_buffer_get
whd_result_t whd_host_buffer_get(whd_driver_t whd_driver, whd_buffer_t *buffer, whd_buffer_dir_t direction, uint16_t size, uint32_t wait)
Allocates a packet buffer.
whd_int.h
Header for whd_driver structure.
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_release
whd_result_t whd_buffer_release(whd_driver_t whd_driver, whd_buffer_t buffer, whd_buffer_dir_t direction)
Releases a packet buffer.
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.