1 /*
2  * Copyright 2023, 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
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 timeout_ms : Maximum period to block for available buffer
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 timeout_ms);
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 
152