alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
e0b98b75e7
esp-idf/components/bt/porting/nimble/include/os/os_mbuf.h

1147 lines
39 KiB
C
Raw Normal View History

Add new porting file
2022-06-17 09:37:48 -04:00
/*
* SPDX-FileCopyrightText: 2015-2022 The Apache Software Foundation (ASF)
*
* SPDX-License-Identifier: Apache-2.0
*
* SPDX-FileContributor: 2019-2022 Espressif Systems (Shanghai) CO LTD
*/
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/**
* @addtogroup OSKernel
* @{
* @defgroup OSMbuf Chained Memory Buffers
* @{
*/
#ifndef _OS_MBUF_H
#define _OS_MBUF_H
#include <stdbool.h>
#include "os/os.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* A mbuf pool from which to allocate mbufs. This contains a pointer to the os
* mempool to allocate mbufs out of, the total number of elements in the pool,
* and the amount of "user" data in a non-packet header mbuf. The total pool
* size, in bytes, should be:
* os_mbuf_count * (omp_databuf_len + sizeof(struct os_mbuf))
*/
struct os_mbuf_pool {
/**
* Total length of the databuf in each mbuf. This is the size of the
* mempool block, minus the mbuf header
*/
uint16_t omp_databuf_len;
/**
* The memory pool which to allocate mbufs out of
*/
struct os_mempool *omp_pool;
STAILQ_ENTRY(os_mbuf_pool) omp_next;
};
/**
* A packet header structure that preceeds the mbuf packet headers.
*/
struct os_mbuf_pkthdr {
/**
* Overall length of the packet.
*/
uint16_t omp_len;
/**
* Flags
*/
uint16_t omp_flags;
STAILQ_ENTRY(os_mbuf_pkthdr) omp_next;
};
/**
* Chained memory buffer.
*/
struct os_mbuf {
/**
* Current pointer to data in the structure
*/
uint8_t *om_data;
/**
* Flags associated with this buffer, see OS_MBUF_F_* defintions
*/
uint8_t om_flags;
/**
* Length of packet header
*/
uint8_t om_pkthdr_len;
/**
* Length of data in this buffer
*/
uint16_t om_len;
/**
* The mbuf pool this mbuf was allocated out of
*/
struct os_mbuf_pool *om_omp;
SLIST_ENTRY(os_mbuf) om_next;
/**
* Pointer to the beginning of the data, after this buffer
*/
uint8_t om_databuf[0];
};
/**
* Structure representing a queue of mbufs.
*/
struct os_mqueue {
STAILQ_HEAD(, os_mbuf_pkthdr) mq_head;
/** Event to post when new buffers are available on the queue. */
struct ble_npl_event mq_ev;
};
/*
* Given a flag number, provide the mask for it
*
* @param __n The number of the flag in the mask
*/
#define OS_MBUF_F_MASK(__n) (1 << (__n))
/*
* Checks whether a given mbuf is a packet header mbuf
*
* @param __om The mbuf to check
*/
#define OS_MBUF_IS_PKTHDR(__om) \
((__om)->om_pkthdr_len >= sizeof (struct os_mbuf_pkthdr))
/** Get a packet header pointer given an mbuf pointer */
#define OS_MBUF_PKTHDR(__om) ((struct os_mbuf_pkthdr *) \
((uint8_t *)&(__om)->om_data + sizeof(struct os_mbuf)))
/** Given a mbuf packet header pointer, return a pointer to the mbuf */
#define OS_MBUF_PKTHDR_TO_MBUF(__hdr) \
(struct os_mbuf *)((uint8_t *)(__hdr) - sizeof(struct os_mbuf))
/**
* Gets the length of an entire mbuf chain. The specified mbuf must have a
* packet header.
*/
#define OS_MBUF_PKTLEN(__om) (OS_MBUF_PKTHDR(__om)->omp_len)
/**
* Access the data of a mbuf, and cast it to type
*
* @param __om The mbuf to access, and cast
* @param __type The type to cast it to
*/
#define OS_MBUF_DATA(__om, __type) \
(__type) ((__om)->om_data)
/**
* Access the "user header" in the head of an mbuf chain.
*
* @param om Pointer to the head of an mbuf chain.
*/
#define OS_MBUF_USRHDR(om) \
(void *)((uint8_t *)om + sizeof (struct os_mbuf) + \
sizeof (struct os_mbuf_pkthdr))
/**
* Retrieves the length of the user header in an mbuf.
*
* @param om Pointer to the mbuf to query.
*/
#define OS_MBUF_USRHDR_LEN(om) \
((om)->om_pkthdr_len - sizeof (struct os_mbuf_pkthdr))
/** @cond INTERNAL_HIDDEN */
/*
* Called by OS_MBUF_LEADINGSPACE() macro
*/
static inline uint16_t
_os_mbuf_leadingspace(struct os_mbuf *om)
{
uint16_t startoff;
uint16_t leadingspace;
startoff = 0;
if (OS_MBUF_IS_PKTHDR(om)) {
startoff = om->om_pkthdr_len;
}
leadingspace = (uint16_t) (OS_MBUF_DATA(om, uint8_t *) -
((uint8_t *) &om->om_databuf[0] + startoff));
return (leadingspace);
}
/** @endcond */
/**
* Returns the leading space (space at the beginning) of the mbuf.
* Works on both packet header, and regular mbufs, as it accounts
* for the additional space allocated to the packet header.
*
* @param __omp Is the mbuf pool (which contains packet header length.)
* @param __om Is the mbuf in that pool to get the leadingspace for
*
* @return Amount of leading space available in the mbuf
*/
#define OS_MBUF_LEADINGSPACE(__om) _os_mbuf_leadingspace(__om)
/** @cond INTERNAL_HIDDEN */
/* Called by OS_MBUF_TRAILINGSPACE() macro. */
static inline uint16_t
_os_mbuf_trailingspace(struct os_mbuf *om)
{
struct os_mbuf_pool *omp;
omp = om->om_omp;
return (&om->om_databuf[0] + omp->omp_databuf_len) -
(om->om_data + om->om_len);
}
/** @endcond */
/**
* Returns the trailing space (space at the end) of the mbuf.
* Works on both packet header and regular mbufs.
*
* @param __omp The mbuf pool for this mbuf
* @param __om Is the mbuf in that pool to get trailing space for
*
* @return The amount of trailing space available in the mbuf
*/
#define OS_MBUF_TRAILINGSPACE(__om) _os_mbuf_trailingspace(__om)
#if SOC_ESP_NIMBLE_CONTROLLER
/**
* Initializes an mqueue. An mqueue is a queue of mbufs that ties to a
* particular task's event queue. Mqueues form a helper API around a common
* paradigm: wait on an event queue until at least one packet is available,
* then process a queue of packets.
*
* When mbufs are available on the queue, an event OS_EVENT_T_MQUEUE_DATA
* will be posted to the task's mbuf queue.
*
* @param mq The mqueue to initialize
* @param ev_cb The callback to associate with the mqeueue
* event. Typically, this callback pulls each
* packet off the mqueue and processes them.
* @param arg The argument to associate with the mqueue event.
*
* @return 0 on success, non-zero on failure.
*/
int r_os_mqueue_init(struct os_mqueue *mq, ble_npl_event_fn *ev_cb, void *arg);
#define os_mqueue_init r_os_mqueue_init
/**
* Remove and return a single mbuf from the mbuf queue. Does not block.
*
* @param mq The mbuf queue to pull an element off of.
*
* @return The next mbuf in the queue, or NULL if queue has no mbufs.
*/
struct os_mbuf *r_os_mqueue_get(struct os_mqueue *);
#define os_mqueue_get r_os_mqueue_get
/**
* Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated
* with the mqueue gets posted to the specified eventq.
*
* @param mq The mbuf queue to append the mbuf to.
* @param evq The event queue to post an event to.
* @param m The mbuf to append to the mbuf queue.
*
* @return 0 on success, non-zero on failure.
*/
int r_os_mqueue_put(struct os_mqueue *, struct ble_npl_eventq *, struct os_mbuf *);
#define os_mqueue_put r_os_mqueue_put
/**
* MSYS is a system level mbuf registry. Allows the system to share
* packet buffers amongst the various networking stacks that can be running
* simultaeneously.
*
* Mbuf pools are created in the system initialization code, and then when
* a mbuf is allocated out of msys, it will try and find the best fit based
* upon estimated mbuf size.
*
* os_msys_register() registers a mbuf pool with MSYS, and allows MSYS to
* allocate mbufs out of it.
*
* @param new_pool The pool to register with MSYS
*
* @return 0 on success, non-zero on failure
*/
int r_os_msys_register(struct os_mbuf_pool *);
#define os_msys_register r_os_msys_register
/**
* Allocate a mbuf from msys. Based upon the data size requested,
* os_msys_get() will choose the mbuf pool that has the best fit.
*
* @param dsize The estimated size of the data being stored in the mbuf
* @param leadingspace The amount of leadingspace to allocate in the mbuf
*
* @return A freshly allocated mbuf on success, NULL on failure.
*/
struct os_mbuf *r_os_msys_get(uint16_t dsize, uint16_t leadingspace);
#define os_msys_get r_os_msys_get
/**
* De-registers all mbuf pools from msys.
*/
void r_os_msys_reset(void);
#define os_msys_reset r_os_msys_reset
/**
* Allocate a packet header structure from the MSYS pool. See
* os_msys_register() for a description of MSYS.
*
* @param dsize The estimated size of the data being stored in the mbuf
* @param user_hdr_len The length to allocate for the packet header structure
*
* @return A freshly allocated mbuf on success, NULL on failure.
*/
struct os_mbuf *r_os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len);
#define os_msys_get_pkthdr r_os_msys_get_pkthdr
/**
* Count the number of blocks in all the mbuf pools that are allocated.
*
* @return total number of blocks allocated in Msys
*/
int r_os_msys_count(void);
#define os_msys_count r_os_msys_count
/**
* Return the number of free blocks in Msys
*
* @return Number of free blocks available in Msys
*/
int r_os_msys_num_free(void);
#define os_msys_num_free r_os_msys_num_free
/**
* Initialize a pool of mbufs.
*
* @param omp The mbuf pool to initialize
* @param mp The memory pool that will hold this mbuf pool
* @param buf_len The length of the buffer itself.
* @param nbufs The number of buffers in the pool
*
* @return 0 on success, error code on failure.
*/
int r_os_mbuf_pool_init(struct os_mbuf_pool *, struct os_mempool *mp,
uint16_t, uint16_t);
#define os_mbuf_pool_init r_os_mbuf_pool_init
/**
* Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized
* prior to being returned.
*
* @param omp The mbuf pool to return the packet from
* @param leadingspace The amount of leadingspace to put before the data
* section by default.
*
* @return An initialized mbuf on success, and NULL on failure.
*/
struct os_mbuf *r_os_mbuf_get(struct os_mbuf_pool *omp, uint16_t);
#define os_mbuf_get r_os_mbuf_get
/**
* Allocate a new packet header mbuf out of the os_mbuf_pool.
*
* @param omp The mbuf pool to allocate out of
* @param user_pkthdr_len The packet header length to reserve for the caller.
*
* @return A freshly allocated mbuf on success, NULL on failure.
*/
struct os_mbuf *r_os_mbuf_get_pkthdr(struct os_mbuf_pool *omp,
uint8_t pkthdr_len);
#define os_mbuf_get_pkthdr r_os_mbuf_get_pkthdr
/**
* Duplicate a chain of mbufs. Return the start of the duplicated chain.
*
* @param omp The mbuf pool to duplicate out of
* @param om The mbuf chain to duplicate
*
* @return A pointer to the new chain of mbufs
*/
struct os_mbuf *r_os_mbuf_dup(struct os_mbuf *m);
#define os_mbuf_dup r_os_mbuf_dup
/**
* Locates the specified absolute offset within an mbuf chain. The offset
* can be one past than the total length of the chain, but no greater.
*
* @param om The start of the mbuf chain to seek within.
* @param off The absolute address to find.
* @param out_off On success, this points to the relative offset
* within the returned mbuf.
*
* @return The mbuf containing the specified offset on
* success.
* NULL if the specified offset is out of bounds.
*/
struct os_mbuf *r_os_mbuf_off(const struct os_mbuf *om, int off,
uint16_t *out_off);
#define os_mbuf_off r_os_mbuf_off
/*
* Copy data from an mbuf chain starting "off" bytes from the beginning,
* continuing for "len" bytes, into the indicated buffer.
*
* @param m The mbuf chain to copy from
* @param off The offset into the mbuf chain to begin copying from
* @param len The length of the data to copy
* @param dst The destination buffer to copy into
*
* @return 0 on success;
* -1 if the mbuf does not contain enough data.
*/
int r_os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst);
#define os_mbuf_copydata r_os_mbuf_copydata
/**
* @brief Calculates the length of an mbuf chain.
*
* Calculates the length of an mbuf chain. If the mbuf contains a packet
* header, you should use `OS_MBUF_PKTLEN()` as a more efficient alternative to
* this function.
*
* @param om The mbuf to measure.
*
* @return The length, in bytes, of the provided mbuf
* chain.
*/
uint16_t r_os_mbuf_len(const struct os_mbuf *om);
#define os_mbuf_len r_os_mbuf_len
/**
* Append data onto a mbuf
*
* @param om The mbuf to append the data onto
* @param data The data to append onto the mbuf
* @param len The length of the data to append
*
* @return 0 on success, and an error code on failure
*/
int r_os_mbuf_append(struct os_mbuf *m, const void *, uint16_t);
#define os_mbuf_append r_os_mbuf_append
/**
* Reads data from one mbuf and appends it to another. On error, the specified
* data range may be partially appended. Neither mbuf is required to contain
* an mbuf packet header.
*
* @param dst The mbuf to append to.
* @param src The mbuf to copy data from.
* @param src_off The absolute offset within the source mbuf
* chain to read from.
* @param len The number of bytes to append.
*
* @return 0 on success;
* OS_EINVAL if the specified range extends beyond
* the end of the source mbuf chain.
*/
int r_os_mbuf_appendfrom(struct os_mbuf *dst, const struct os_mbuf *src,
uint16_t src_off, uint16_t len);
#define os_mbuf_appendfrom r_os_mbuf_appendfrom
/**
* Release a mbuf back to the pool
*
* @param omp The Mbuf pool to release back to
* @param om The Mbuf to release back to the pool
*
* @return 0 on success, -1 on failure
*/
Nimble: Fixed compilation error for esp32c2 and esp32h2 when os_mbuf_free is called.
2022-07-13 07:14:21 -04:00
int r_os_mbuf_free(struct os_mbuf *mb);
Add new porting file
2022-06-17 09:37:48 -04:00
#define os_mbuf_free r_os_mbuf_free
/**
* Free a chain of mbufs
*
* @param omp The mbuf pool to free the chain of mbufs into
* @param om The starting mbuf of the chain to free back into the pool
*
* @return 0 on success, -1 on failure
*/
int r_os_mbuf_free_chain(struct os_mbuf *om);
#define os_mbuf_free_chain r_os_mbuf_free_chain
/**
* Adjust the length of a mbuf, trimming either from the head or the tail
* of the mbuf.
*
* @param mp The mbuf chain to adjust
* @param req_len The length to trim from the mbuf. If positive, trims
* from the head of the mbuf, if negative, trims from the
* tail of the mbuf.
*/
void r_os_mbuf_adj(struct os_mbuf *mp, int req_len);
#define os_mbuf_adj r_os_mbuf_adj
/**
* Performs a memory compare of the specified region of an mbuf chain against a
* flat buffer.
*
* @param om The start of the mbuf chain to compare.
* @param off The offset within the mbuf chain to start the
* comparison.
* @param data The flat buffer to compare.
* @param len The length of the flat buffer.
*
* @return 0 if both memory regions are identical;
* A memcmp return code if there is a mismatch;
* INT_MAX if the mbuf is too short.
*/
int r_os_mbuf_cmpf(const struct os_mbuf *om, int off, const void *data, int len);
#define os_mbuf_cmpf r_os_mbuf_cmpf
/**
* Compares the contents of two mbuf chains. The ranges of the two chains to
* be compared are specified via the two offset parameters and the len
* parameter. Neither mbuf chain is required to contain a packet header.
*
* @param om1 The first mbuf chain to compare.
* @param offset1 The absolute offset within om1 at which to
* start the comparison.
* @param om2 The second mbuf chain to compare.
* @param offset2 The absolute offset within om2 at which to
* start the comparison.
* @param len The number of bytes to compare.
*
* @return 0 if both mbuf segments are identical;
* A memcmp() return code if the segment contents
* differ;
* INT_MAX if a specified range extends beyond the
* end of its corresponding mbuf chain.
*/
int r_os_mbuf_cmpm(const struct os_mbuf *om1, uint16_t offset1,
const struct os_mbuf *om2, uint16_t offset2,
uint16_t len);
#define os_mbuf_cmpm r_os_mbuf_cmpm
/**
* Increases the length of an mbuf chain by adding data to the front. If there
* is insufficient room in the leading mbuf, additional mbufs are allocated and
* prepended as necessary. If this function fails to allocate an mbuf, the
* entire chain is freed.
*
* The specified mbuf chain does not need to contain a packet header.
*
* @param omp The mbuf pool to allocate from.
* @param om The head of the mbuf chain.
* @param len The number of bytes to prepend.
*
* @return The new head of the chain on success;
* NULL on failure.
*/
struct os_mbuf *r_os_mbuf_prepend(struct os_mbuf *om, int len);
#define os_mbuf_prepend r_os_mbuf_prepend
/**
* Prepends a chunk of empty data to the specified mbuf chain and ensures the
* chunk is contiguous. If either operation fails, the specified mbuf chain is
* freed and NULL is returned.
*
* @param om The mbuf chain to prepend to.
* @param len The number of bytes to prepend and pullup.
*
* @return The modified mbuf on success;
* NULL on failure (and the mbuf chain is freed).
*/
struct os_mbuf *r_os_mbuf_prepend_pullup(struct os_mbuf *om, uint16_t len);
#define os_mbuf_prepend_pullup r_os_mbuf_prepend_pullup
/**
* Copies the contents of a flat buffer into an mbuf chain, starting at the
* specified destination offset. If the mbuf is too small for the source data,
* it is extended as necessary. If the destination mbuf contains a packet
* header, the header length is updated.
*
* @param omp The mbuf pool to allocate from.
* @param om The mbuf chain to copy into.
* @param off The offset within the chain to copy to.
* @param src The source buffer to copy from.
* @param len The number of bytes to copy.
*
* @return 0 on success; nonzero on failure.
*/
int r_os_mbuf_copyinto(struct os_mbuf *om, int off, const void *src, int len);
#define os_mbuf_copyinto r_os_mbuf_copyinto
/**
* Attaches a second mbuf chain onto the end of the first. If the first chain
* contains a packet header, the header's length is updated. If the second
* chain has a packet header, its header is cleared.
*
* @param first The mbuf chain being attached to.
* @param second The mbuf chain that gets attached.
*/
void r_os_mbuf_concat(struct os_mbuf *first, struct os_mbuf *second);
#define os_mbuf_concat r_os_mbuf_concat
/**
* Increases the length of an mbuf chain by the specified amount. If there is
* not sufficient room in the last buffer, a new buffer is allocated and
* appended to the chain. It is an error to request more data than can fit in
* a single buffer.
*
* @param omp
* @param om The head of the chain to extend.
* @param len The number of bytes to extend by.
*
* @return A pointer to the new data on success;
* NULL on failure.
*/
void *r_os_mbuf_extend(struct os_mbuf *om, uint16_t len);
#define os_mbuf_extend r_os_mbuf_extend
/**
* Rearrange a mbuf chain so that len bytes are contiguous,
* and in the data area of an mbuf (so that OS_MBUF_DATA() will
* work on a structure of size len.) Returns the resulting
* mbuf chain on success, free's it and returns NULL on failure.
*
* If there is room, it will add up to "max_protohdr - len"
* extra bytes to the contiguous region, in an attempt to avoid being
* called next time.
*
* @param omp The mbuf pool to take the mbufs out of
* @param om The mbuf chain to make contiguous
* @param len The number of bytes in the chain to make contiguous
*
* @return The contiguous mbuf chain on success, NULL on failure.
*/
struct os_mbuf *r_os_mbuf_pullup(struct os_mbuf *om, uint16_t len);
#define os_mbuf_pullup r_os_mbuf_pullup
/**
* Removes and frees empty mbufs from the front of a chain. If the chain
* contains a packet header, it is preserved.
*
* @param om The mbuf chain to trim.
*
* @return The head of the trimmed mbuf chain.
*/
struct os_mbuf *r_os_mbuf_trim_front(struct os_mbuf *om);
#define os_mbuf_trim_front r_os_mbuf_trim_front
/**
* Increases the length of an mbuf chain by inserting a gap at the specified
* offset. The contents of the gap are indeterminate. If the mbuf chain
* contains a packet header, its total length is increased accordingly.
*
* This function never frees the provided mbuf chain.
*
* @param om The mbuf chain to widen.
* @param off The offset at which to insert the gap.
* @param len The size of the gap to insert.
*
* @return 0 on success; SYS_[...] error code on failure.
*/
int r_os_mbuf_widen(struct os_mbuf *om, uint16_t off, uint16_t len);
#define os_mbuf_widen r_os_mbuf_widen
/**
* Creates a single chained mbuf from m1 and m2 utilizing all
* the available buffer space in all mbufs in the resulting
* chain. In other words, ensures there is no leading space in
* any mbuf in the resulting chain and trailing space only in
* the last mbuf in the chain. Mbufs from either chain may be
* freed if not needed. No mbufs are allocated. Note that mbufs
* from m2 are added to the end of m1. If m1 has a packet
* header, it is retained and length updated. If m2 has a packet
* header it is discarded. If m1 is NULL, NULL is returned and
* m2 is left untouched.
*
* @param m1 Pointer to first mbuf chain to pack
* @param m2 Pointer to second mbuf chain to pack
*
* @return struct os_mbuf* Pointer to resulting mbuf chain
*/
struct os_mbuf *r_os_mbuf_pack_chains(struct os_mbuf *m1, struct os_mbuf *m2);
#define os_mbuf_pack_chains r_os_mbuf_pack_chains
#else
/**
* Initializes an mqueue. An mqueue is a queue of mbufs that ties to a
* particular task's event queue. Mqueues form a helper API around a common
* paradigm: wait on an event queue until at least one packet is available,
* then process a queue of packets.
*
* When mbufs are available on the queue, an event OS_EVENT_T_MQUEUE_DATA
* will be posted to the task's mbuf queue.
*
* @param mq The mqueue to initialize
* @param ev_cb The callback to associate with the mqeueue
* event. Typically, this callback pulls each
* packet off the mqueue and processes them.
* @param arg The argument to associate with the mqueue event.
*
* @return 0 on success, non-zero on failure.
*/
int os_mqueue_init(struct os_mqueue *mq, ble_npl_event_fn *ev_cb, void *arg);
/**
* Remove and return a single mbuf from the mbuf queue. Does not block.
*
* @param mq The mbuf queue to pull an element off of.
*
* @return The next mbuf in the queue, or NULL if queue has no mbufs.
*/
struct os_mbuf *os_mqueue_get(struct os_mqueue *);
/**
* Adds a packet (i.e. packet header mbuf) to an mqueue. The event associated
* with the mqueue gets posted to the specified eventq.
*
* @param mq The mbuf queue to append the mbuf to.
* @param evq The event queue to post an event to.
* @param m The mbuf to append to the mbuf queue.
*
* @return 0 on success, non-zero on failure.
*/
int os_mqueue_put(struct os_mqueue *, struct ble_npl_eventq *, struct os_mbuf *);
/**
* MSYS is a system level mbuf registry. Allows the system to share
* packet buffers amongst the various networking stacks that can be running
* simultaeneously.
*
* Mbuf pools are created in the system initialization code, and then when
* a mbuf is allocated out of msys, it will try and find the best fit based
* upon estimated mbuf size.
*
* os_msys_register() registers a mbuf pool with MSYS, and allows MSYS to
* allocate mbufs out of it.
*
* @param new_pool The pool to register with MSYS
*
* @return 0 on success, non-zero on failure
*/
int os_msys_register(struct os_mbuf_pool *);
/**
* Allocate a mbuf from msys. Based upon the data size requested,
* os_msys_get() will choose the mbuf pool that has the best fit.
*
* @param dsize The estimated size of the data being stored in the mbuf
* @param leadingspace The amount of leadingspace to allocate in the mbuf
*
* @return A freshly allocated mbuf on success, NULL on failure.
*/
struct os_mbuf *os_msys_get(uint16_t dsize, uint16_t leadingspace);
/**
* De-registers all mbuf pools from msys.
*/
void os_msys_reset(void);
/**
* Allocate a packet header structure from the MSYS pool. See
* os_msys_register() for a description of MSYS.
*
* @param dsize The estimated size of the data being stored in the mbuf
* @param user_hdr_len The length to allocate for the packet header structure
*
* @return A freshly allocated mbuf on success, NULL on failure.
*/
struct os_mbuf *os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len);
/**
* Count the number of blocks in all the mbuf pools that are allocated.
*
* @return total number of blocks allocated in Msys
*/
int os_msys_count(void);
/**
* Return the number of free blocks in Msys
*
* @return Number of free blocks available in Msys
*/
int os_msys_num_free(void);
/**
* Initialize a pool of mbufs.
*
* @param omp The mbuf pool to initialize
* @param mp The memory pool that will hold this mbuf pool
* @param buf_len The length of the buffer itself.
* @param nbufs The number of buffers in the pool
*
* @return 0 on success, error code on failure.
*/
int os_mbuf_pool_init(struct os_mbuf_pool *, struct os_mempool *mp,
uint16_t, uint16_t);
/**
* Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized
* prior to being returned.
*
* @param omp The mbuf pool to return the packet from
* @param leadingspace The amount of leadingspace to put before the data
* section by default.
*
* @return An initialized mbuf on success, and NULL on failure.
*/
struct os_mbuf *os_mbuf_get(struct os_mbuf_pool *omp, uint16_t);
/**
* Allocate a new packet header mbuf out of the os_mbuf_pool.
*
* @param omp The mbuf pool to allocate out of
* @param user_pkthdr_len The packet header length to reserve for the caller.
*
* @return A freshly allocated mbuf on success, NULL on failure.
*/
struct os_mbuf *os_mbuf_get_pkthdr(struct os_mbuf_pool *omp,
uint8_t pkthdr_len);
/**
* Duplicate a chain of mbufs. Return the start of the duplicated chain.
*
* @param omp The mbuf pool to duplicate out of
* @param om The mbuf chain to duplicate
*
* @return A pointer to the new chain of mbufs
*/
struct os_mbuf *os_mbuf_dup(struct os_mbuf *m);
/**
* Locates the specified absolute offset within an mbuf chain. The offset
* can be one past than the total length of the chain, but no greater.
*
* @param om The start of the mbuf chain to seek within.
* @param off The absolute address to find.
* @param out_off On success, this points to the relative offset
* within the returned mbuf.
*
* @return The mbuf containing the specified offset on
* success.
* NULL if the specified offset is out of bounds.
*/
struct os_mbuf *os_mbuf_off(const struct os_mbuf *om, int off,
uint16_t *out_off);
/*
* Copy data from an mbuf chain starting "off" bytes from the beginning,
* continuing for "len" bytes, into the indicated buffer.
*
* @param m The mbuf chain to copy from
* @param off The offset into the mbuf chain to begin copying from
* @param len The length of the data to copy
* @param dst The destination buffer to copy into
*
* @return 0 on success;
* -1 if the mbuf does not contain enough data.
*/
int os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst);
/**
* @brief Calculates the length of an mbuf chain.
*
* Calculates the length of an mbuf chain. If the mbuf contains a packet
* header, you should use `OS_MBUF_PKTLEN()` as a more efficient alternative to
* this function.
*
* @param om The mbuf to measure.
*
* @return The length, in bytes, of the provided mbuf
* chain.
*/
uint16_t os_mbuf_len(const struct os_mbuf *om);
/**
* Append data onto a mbuf
*
* @param om The mbuf to append the data onto
* @param data The data to append onto the mbuf
* @param len The length of the data to append
*
* @return 0 on success, and an error code on failure
*/
int os_mbuf_append(struct os_mbuf *m, const void *, uint16_t);
/**
* Reads data from one mbuf and appends it to another. On error, the specified
* data range may be partially appended. Neither mbuf is required to contain
* an mbuf packet header.
*
* @param dst The mbuf to append to.
* @param src The mbuf to copy data from.
* @param src_off The absolute offset within the source mbuf
* chain to read from.
* @param len The number of bytes to append.
*
* @return 0 on success;
* OS_EINVAL if the specified range extends beyond
* the end of the source mbuf chain.
*/
int os_mbuf_appendfrom(struct os_mbuf *dst, const struct os_mbuf *src,
uint16_t src_off, uint16_t len);
/**
* Release a mbuf back to the pool
*
* @param omp The Mbuf pool to release back to
* @param om The Mbuf to release back to the pool
*
* @return 0 on success, -1 on failure
*/
int os_mbuf_free(struct os_mbuf *mb);
/**
* Free a chain of mbufs
*
* @param omp The mbuf pool to free the chain of mbufs into
* @param om The starting mbuf of the chain to free back into the pool
*
* @return 0 on success, -1 on failure
*/
int os_mbuf_free_chain(struct os_mbuf *om);
/**
* Adjust the length of a mbuf, trimming either from the head or the tail
* of the mbuf.
*
* @param mp The mbuf chain to adjust
* @param req_len The length to trim from the mbuf. If positive, trims
* from the head of the mbuf, if negative, trims from the
* tail of the mbuf.
*/
void os_mbuf_adj(struct os_mbuf *mp, int req_len);
/**
* Performs a memory compare of the specified region of an mbuf chain against a
* flat buffer.
*
* @param om The start of the mbuf chain to compare.
* @param off The offset within the mbuf chain to start the
* comparison.
* @param data The flat buffer to compare.
* @param len The length of the flat buffer.
*
* @return 0 if both memory regions are identical;
* A memcmp return code if there is a mismatch;
* INT_MAX if the mbuf is too short.
*/
int os_mbuf_cmpf(const struct os_mbuf *om, int off, const void *data, int len);
/**
* Compares the contents of two mbuf chains. The ranges of the two chains to
* be compared are specified via the two offset parameters and the len
* parameter. Neither mbuf chain is required to contain a packet header.
*
* @param om1 The first mbuf chain to compare.
* @param offset1 The absolute offset within om1 at which to
* start the comparison.
* @param om2 The second mbuf chain to compare.
* @param offset2 The absolute offset within om2 at which to
* start the comparison.
* @param len The number of bytes to compare.
*
* @return 0 if both mbuf segments are identical;
* A memcmp() return code if the segment contents
* differ;
* INT_MAX if a specified range extends beyond the
* end of its corresponding mbuf chain.
*/
int os_mbuf_cmpm(const struct os_mbuf *om1, uint16_t offset1,
const struct os_mbuf *om2, uint16_t offset2,
uint16_t len);
/**
* Increases the length of an mbuf chain by adding data to the front. If there
* is insufficient room in the leading mbuf, additional mbufs are allocated and
* prepended as necessary. If this function fails to allocate an mbuf, the
* entire chain is freed.
*
* The specified mbuf chain does not need to contain a packet header.
*
* @param omp The mbuf pool to allocate from.
* @param om The head of the mbuf chain.
* @param len The number of bytes to prepend.
*
* @return The new head of the chain on success;
* NULL on failure.
*/
struct os_mbuf *os_mbuf_prepend(struct os_mbuf *om, int len);
/**
* Prepends a chunk of empty data to the specified mbuf chain and ensures the
* chunk is contiguous. If either operation fails, the specified mbuf chain is
* freed and NULL is returned.
*
* @param om The mbuf chain to prepend to.
* @param len The number of bytes to prepend and pullup.
*
* @return The modified mbuf on success;
* NULL on failure (and the mbuf chain is freed).
*/
struct os_mbuf *os_mbuf_prepend_pullup(struct os_mbuf *om, uint16_t len);
/**
* Copies the contents of a flat buffer into an mbuf chain, starting at the
* specified destination offset. If the mbuf is too small for the source data,
* it is extended as necessary. If the destination mbuf contains a packet
* header, the header length is updated.
*
* @param omp The mbuf pool to allocate from.
* @param om The mbuf chain to copy into.
* @param off The offset within the chain to copy to.
* @param src The source buffer to copy from.
* @param len The number of bytes to copy.
*
* @return 0 on success; nonzero on failure.
*/
int os_mbuf_copyinto(struct os_mbuf *om, int off, const void *src, int len);
/**
* Attaches a second mbuf chain onto the end of the first. If the first chain
* contains a packet header, the header's length is updated. If the second
* chain has a packet header, its header is cleared.
*
* @param first The mbuf chain being attached to.
* @param second The mbuf chain that gets attached.
*/
void os_mbuf_concat(struct os_mbuf *first, struct os_mbuf *second);
/**
* Increases the length of an mbuf chain by the specified amount. If there is
* not sufficient room in the last buffer, a new buffer is allocated and
* appended to the chain. It is an error to request more data than can fit in
* a single buffer.
*
* @param omp
* @param om The head of the chain to extend.
* @param len The number of bytes to extend by.
*
* @return A pointer to the new data on success;
* NULL on failure.
*/
void *os_mbuf_extend(struct os_mbuf *om, uint16_t len);
/**
* Rearrange a mbuf chain so that len bytes are contiguous,
* and in the data area of an mbuf (so that OS_MBUF_DATA() will
* work on a structure of size len.) Returns the resulting
* mbuf chain on success, free's it and returns NULL on failure.
*
* If there is room, it will add up to "max_protohdr - len"
* extra bytes to the contiguous region, in an attempt to avoid being
* called next time.
*
* @param omp The mbuf pool to take the mbufs out of
* @param om The mbuf chain to make contiguous
* @param len The number of bytes in the chain to make contiguous
*
* @return The contiguous mbuf chain on success, NULL on failure.
*/
struct os_mbuf *os_mbuf_pullup(struct os_mbuf *om, uint16_t len);
/**
* Removes and frees empty mbufs from the front of a chain. If the chain
* contains a packet header, it is preserved.
*
* @param om The mbuf chain to trim.
*
* @return The head of the trimmed mbuf chain.
*/
struct os_mbuf *os_mbuf_trim_front(struct os_mbuf *om);
/**
* Increases the length of an mbuf chain by inserting a gap at the specified
* offset. The contents of the gap are indeterminate. If the mbuf chain
* contains a packet header, its total length is increased accordingly.
*
* This function never frees the provided mbuf chain.
*
* @param om The mbuf chain to widen.
* @param off The offset at which to insert the gap.
* @param len The size of the gap to insert.
*
* @return 0 on success; SYS_[...] error code on failure.
*/
int os_mbuf_widen(struct os_mbuf *om, uint16_t off, uint16_t len);
/**
* Creates a single chained mbuf from m1 and m2 utilizing all
* the available buffer space in all mbufs in the resulting
* chain. In other words, ensures there is no leading space in
* any mbuf in the resulting chain and trailing space only in
* the last mbuf in the chain. Mbufs from either chain may be
* freed if not needed. No mbufs are allocated. Note that mbufs
* from m2 are added to the end of m1. If m1 has a packet
* header, it is retained and length updated. If m2 has a packet
* header it is discarded. If m1 is NULL, NULL is returned and
* m2 is left untouched.
*
* @param m1 Pointer to first mbuf chain to pack
* @param m2 Pointer to second mbuf chain to pack
*
* @return struct os_mbuf* Pointer to resulting mbuf chain
*/
struct os_mbuf *os_mbuf_pack_chains(struct os_mbuf *m1, struct os_mbuf *m2);
#endif
#ifdef __cplusplus
}
#endif
#endif /* _OS_MBUF_H */
/**
* @} OSMbuf
* @} OSKernel
*/
Reference in New Issue Copy Permalink