1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup WLAN 11 * @{ 12 * 13 * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation. 14 * 15 * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface 16 * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips, 17 * network devices, and power, and applying for, releasing, and moving network data buffers. 18 * 19 * @since 1.0 20 * @version 1.0 21 */ 22 23 /** 24 * @file hdf_netbuf.h 25 * 26 * @brief Declares network data buffers and provides APIs for operating buffer queues. 27 * 28 * This file describes the following network data operations for network device driver development: \n 29 * 30 * Applying for, releasing, and moving a network data buffer 31 * Initializing a network data buffer queue, placing a network data buffer to a queue, and removing a network data 32 * buffer from a queue 33 * 34 * @since 1.0 35 * @version 1.0 36 */ 37 38 #ifndef HDF_NETBUF_H 39 #define HDF_NETBUF_H 40 41 #include "netbuf_adapter.h" 42 43 #ifdef __cplusplus 44 #if __cplusplus 45 extern "C" { 46 #endif 47 #endif /* __cplusplus */ 48 49 /** 50 * @brief Initializes a network data buffer queue. 51 * 52 * @param q Indicates the pointer to the network data buffer queue. 53 * 54 * @since 1.0 55 * @version 1.0 56 */ 57 void NetBufQueueInit(NetBufQueue *q); 58 59 /** 60 * @brief Obtains the size of a network data buffer queue. 61 * 62 * @param q Indicates the pointer to the network data buffer queue. 63 * 64 * @return Returns the size of the network data buffer queue. 65 * 66 * @since 1.0 67 * @version 1.0 68 */ 69 uint32_t NetBufQueueSize(const NetBufQueue *q); 70 71 /** 72 * @brief Checks whether the network data buffer queue is empty. 73 * 74 * @param q Indicates the pointer to the network data buffer queue. 75 * 76 * @return Returns <b>true</b> if the queue is empty; returns <b>false</b> otherwise. 77 * 78 * @since 1.0 79 * @version 1.0 80 */ 81 bool NetBufQueueIsEmpty(const NetBufQueue *q); 82 83 /** 84 * @brief Adds a network data buffer to the tail of a queue. 85 * 86 * @param q Indicates the pointer to the network data buffer queue. 87 * @param nb Indicates the pointer to the network data buffer. 88 * 89 * @since 1.0 90 * @version 1.0 91 */ 92 void NetBufQueueEnqueue(NetBufQueue *q, NetBuf *nb); 93 94 /** 95 * @brief Adds a network data buffer to the header of a queue. 96 * 97 * @param q Indicates the pointer to the network data buffer queue. 98 * @param nb Indicates the pointer to the network data buffer. 99 * 100 * @since 1.0 101 * @version 1.0 102 */ 103 void NetBufQueueEnqueueHead(NetBufQueue *q, NetBuf *nb); 104 105 /** 106 * @brief Obtains a network data buffer from the header of a queue and deletes it from the queue. 107 * 108 * @param q Indicates the pointer to the network data buffer queue. 109 * 110 * @return Returns the pointer to the first network data buffer if the queue is not empty; 111 * returns <b>NULL</b> otherwise. 112 * 113 * @since 1.0 114 * @version 1.0 115 */ 116 NetBuf *NetBufQueueDequeue(NetBufQueue *q); 117 118 /** 119 * @brief Obtains a network data buffer from the tail of a queue and deletes it from the queue. 120 * 121 * @param q Indicates the pointer to the network data buffer queue. 122 * 123 * @return Returns the pointer to the last network data buffer if the queue is not empty; 124 * returns <b>NULL</b> otherwise. 125 * 126 * @since 1.0 127 * @version 1.0 128 */ 129 NetBuf *NetBufQueueDequeueTail(NetBufQueue *q); 130 131 /** 132 * @brief Obtains the network data buffer from the header of a queue, without deleting it from the queue. 133 * 134 * @param q Indicates the pointer to the network data buffer queue. 135 * 136 * @return Returns the pointer to the first network data buffer if the queue is not empty; 137 * returns <b>NULL</b> otherwise. 138 * 139 * @since 1.0 140 * @version 1.0 141 */ 142 NetBuf *NetBufQueueAtHead(const NetBufQueue *q); 143 144 /** 145 * @brief Obtains the network data buffer from the tail of a queue, without deleting it from the queue. 146 * 147 * @param q Indicates the pointer to the network data buffer queue. 148 * 149 * @return Returns the pointer to the last network data buffer if the queue is not empty; 150 * returns <b>NULL</b> otherwise. 151 * 152 * @since 1.0 153 * @version 1.0 154 */ 155 NetBuf *NetBufQueueAtTail(const NetBufQueue *q); 156 157 /** 158 * @brief Clears a network data buffer queue and releases the network data buffer in the queue. 159 * 160 * @param q Indicates the pointer to the network data buffer queue. 161 * 162 * @since 1.0 163 * @version 1.0 164 */ 165 void NetBufQueueClear(NetBufQueue *q); 166 167 /** 168 * @brief Moves all network data buffers from one queue to another and clears the source queue. 169 * 170 * @param q Indicates the pointer to the target network data buffer queue. 171 * @param add Indicates the pointer to the source network data buffer queue. 172 * 173 * @since 1.0 174 * @version 1.0 175 */ 176 void NetBufQueueConcat(NetBufQueue *q, NetBufQueue *add); 177 178 /** 179 * @brief Applies for a network data buffer. 180 * 181 * @param size Indicates the size of the network data buffer. 182 * 183 * @return Returns the pointer to the network data buffer if the operation is successful; 184 * returns <b>NULL</b> otherwise. 185 * 186 * @since 1.0 187 * @version 1.0 188 */ 189 NetBuf *NetBufAlloc(uint32_t size); 190 191 /** 192 * @brief Releases a network data buffer. 193 * 194 * @param nb Indicates the pointer to the network data buffer. 195 * 196 * @since 1.0 197 * @version 1.0 198 */ 199 void NetBufFree(NetBuf *nb); 200 201 struct NetDevice; 202 /** 203 * @brief Applies for a network data buffer based on the reserved space and requested size set by a network device. 204 * 205 * @param dev Indicates the pointer to the network device. 206 * @param size Indicates the size of the network data buffer applied. 207 * 208 * @return Returns the pointer to the network data buffer if the operation is successful; 209 * returns <b>NULL</b> otherwise. 210 * 211 * @since 1.0 212 * @version 1.0 213 */ 214 NetBuf *NetBufDevAlloc(const struct NetDevice *dev, uint32_t size); 215 216 /** 217 * @brief Performs operations based on the segment ID of a network data buffer. 218 * The function is opposite to that of {@link NetBufPop}. 219 * 220 * Description: 221 * ID Type | Result 222 * -------|--------- 223 * E_HEAD_BUF | The length of the header buffer segment is increased and the length of the data segment is reduced. 224 * E_DATA_BUF | The length of the data segment is increased and the length of the tail buffer segment is reduced. 225 * E_TAIL_BUF | The length of the tail buffer segment is increased and the length of the data segment is reduced. 226 * 227 * @param nb Indicates the pointer to the network data buffer. 228 * @param id Indicates the buffer segment ID. 229 * @param len Indicates the operation length. 230 * 231 * @return Returns the start address of the data segment if the operation is successful; 232 * returns <b>NULL</b> if the operation length exceeds the space of a specified buffer segment. 233 * 234 * @since 1.0 235 * @version 1.0 236 */ 237 void *NetBufPush(NetBuf *nb, uint32_t id, uint32_t len); 238 239 /** 240 * @brief Performs operations based on the segment ID of a network data buffer. 241 * The function is opposite to that of {@link NetBufPush}. 242 * 243 * Description: 244 * ID Type | Result 245 * -------|--------- 246 * E_HEAD_BUF | The length of the header buffer segment is reduced and the length of the data segment is increased. 247 * E_DATA_BUF| The length of the data segment is reduced and the length of the tail buffer segment is increased. 248 * E_TAIL_BUF | The length of the tail buffer segment is reduced and the length of the data segment is increased. 249 * 250 * @param nb Indicates the pointer to the network data buffer. 251 * @param id Indicates the buffer segment ID. 252 * @param len Indicates the operation length. 253 * 254 * @return Returns the start address of the data segment if the operation is successful; 255 * returns <b>NULL</b> if the operation length exceeds the space of a specified buffer segment. 256 * 257 * @since 1.0 258 * @version 1.0 259 */ 260 void *NetBufPop(NetBuf *nb, uint32_t id, uint32_t len); 261 262 /** 263 * @brief Obtains the address of a specified buffer segment in a network data buffer. 264 * 265 * @param nb Indicates the pointer to the network data buffer. 266 * @param id Indicates the buffer segment ID. 267 * 268 * @return Returns the address of the specified buffer segment if the operation is successful; 269 * returns <b>NULL</b> if the buffer segment ID is invalid. 270 * 271 * @since 1.0 272 * @version 1.0 273 */ 274 uint8_t *NetBufGetAddress(const NetBuf *nb, uint32_t id); 275 276 /** 277 * @brief Obtains the size of a specified buffer segment space in a network data buffer. 278 * 279 * @param nb Indicates the pointer to the network data buffer. 280 * @param id Indicates the buffer segment ID. 281 * 282 * @return Returns the size of the specified buffer segment space if the operation is successful; 283 * returns <b>NULL</b> if the buffer segment ID is invalid. 284 * 285 * @since 1.0 286 * @version 1.0 287 */ 288 uint32_t NetBufGetRoom(const NetBuf *nb, uint32_t id); 289 290 /** 291 * @brief Obtains the actual data length of the data segment of a network data buffer. 292 * 293 * @param nb Indicates the pointer to the network data buffer. 294 * 295 * @return Returns the actual data length of the data segment. 296 * 297 * @since 1.0 298 * @version 1.0 299 */ 300 uint32_t NetBufGetDataLen(const NetBuf *nb); 301 302 /** 303 * @brief Adjusts the size of a network data buffer space. 304 * 305 * This function is used to apply for a new network data buffer based on the configured reserved space and 306 * the size of the source network data buffer, and copy the actual data to the new network data buffer. 307 * 308 * @param nb Indicates the pointer to the network data buffer. 309 * @param head Indicates the size of the header buffer segment reserved. 310 * @param tail Indicates the size of the tail buffer segment reserved. 311 * 312 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 313 * 314 * @since 1.0 315 * @version 1.0 316 */ 317 int32_t NetBufResizeRoom(NetBuf *nb, uint32_t head, uint32_t tail); 318 319 /** 320 * @brief Copies data in a network data buffer to another network data buffer. 321 * 322 * @param nb Indicates the pointer to the network data buffer. 323 * @param cnb Indicates the pointer to the target network data buffer. 324 * 325 * @return Returns <b>0</b> if the operation is successful; returns a non-zero value otherwise. 326 * 327 * @since 1.0 328 * @version 1.0 329 */ 330 int32_t NetBufConcat(NetBuf *nb, NetBuf *cnb); 331 332 #ifdef __cplusplus 333 #if __cplusplus 334 } 335 #endif 336 #endif /* __cplusplus */ 337 338 #endif /* HDF_NETBUF_H */ 339 /** @} */ 340