This is an automated email from the ASF dual-hosted git repository. janc pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mynewt-core.git
commit 5dced2655a028ef200a1bdde5e13182c7095b377 Author: Wojciech Pietraszewski <[email protected]> AuthorDate: Thu Jun 20 17:03:37 2024 +0200 kernel/os_mbuf: Adjust doxygen comments Adjusts formatting for better readability. --- kernel/os/include/os/os_mbuf.h | 129 ++++++++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 54 deletions(-) diff --git a/kernel/os/include/os/os_mbuf.h b/kernel/os/include/os/os_mbuf.h index 0ecb4e523..73fe477bd 100644 --- a/kernel/os/include/os/os_mbuf.h +++ b/kernel/os/include/os/os_mbuf.h @@ -130,14 +130,14 @@ struct os_mqueue { /** * Given a flag number, provide the mask for it * - * @param __n The number of the flag in the mask + * @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 + * @param __om The mbuf to check */ #define OS_MBUF_IS_PKTHDR(__om) \ ((__om)->om_pkthdr_len >= sizeof (struct os_mbuf_pkthdr)) @@ -159,8 +159,8 @@ struct os_mqueue { /** * 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 + * @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) @@ -212,9 +212,10 @@ _os_mbuf_leadingspace(struct os_mbuf *om) * Works on both packet header, and regular mbufs, as it accounts * for the additional space allocated to the packet header. * - * @param __om Is the mbuf in that pool to get the leadingspace for + * @param __om The mbuf in that pool to get the leading + * space for * - * @return Amount of leading space available in the mbuf + * @return Amount of leading space available in the mbuf */ #define OS_MBUF_LEADINGSPACE(__om) _os_mbuf_leadingspace(__om) @@ -239,9 +240,10 @@ _os_mbuf_trailingspace(struct os_mbuf *om) * Returns the trailing space (space at the end) of the mbuf. * Works on both packet header and regular mbufs. * - * @param __om Is the mbuf in that pool to get trailing space for + * @param __om The mbuf in that pool to get the trailing + * space for * - * @return The amount of trailing space available in the mbuf + * @return Amount of trailing space available in the mbuf */ #define OS_MBUF_TRAILINGSPACE(__om) _os_mbuf_trailingspace(__om) @@ -268,9 +270,10 @@ int os_mqueue_init(struct os_mqueue *mq, os_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. + * @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. + * @return The next mbuf in the queue; + * NULL if queue has no mbufs. */ struct os_mbuf *os_mqueue_get(struct os_mqueue *mq); @@ -284,7 +287,8 @@ struct os_mbuf *os_mqueue_get(struct os_mqueue *mq); * * @return 0 on success, non-zero on failure. */ -int os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, struct os_mbuf *om); +int os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, + struct os_mbuf *om); /** * MSYS is a system level mbuf registry. Allows the system to share @@ -298,9 +302,10 @@ int os_mqueue_put(struct os_mqueue *mq, struct os_eventq *evq, struct os_mbuf *o * 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 + * @param new_pool The pool to register with MSYS * - * @return 0 on success, non-zero on failure + * @return 0 on success; + * non-zero on failure */ int os_msys_register(struct os_mbuf_pool *new_pool); @@ -308,10 +313,13 @@ int os_msys_register(struct os_mbuf_pool *new_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 + * @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. + * @return A freshly allocated mbuf on success; + * NULL on failure. */ struct os_mbuf *os_msys_get(uint16_t dsize, uint16_t leadingspace); @@ -324,36 +332,40 @@ 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 + * @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. + * @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 + * @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 + * @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 + * @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. + * @return 0 on success; + * error code on failure. */ int os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp, uint16_t buf_len, uint16_t nbufs); @@ -361,31 +373,34 @@ int os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp, * 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. + * @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. + * @return An initialized mbuf on success; + * NULL on failure. */ struct os_mbuf *os_mbuf_get(struct os_mbuf_pool *omp, uint16_t leadingspace); /** * 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. + * @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. + * @return A freshly allocated mbuf on success; + * NULL on failure. */ struct os_mbuf *os_mbuf_get_pkthdr(struct os_mbuf_pool *omp, - uint8_t user_pkthdr_len); + uint8_t user_pkthdr_len); /** * Duplicate a chain of mbufs. Return the start of the duplicated chain. * - * @param om The mbuf chain to duplicate + * @param om The mbuf chain to duplicate * - * @return A pointer to the new chain of mbufs + * @return A pointer to the new chain of mbufs */ struct os_mbuf *os_mbuf_dup(struct os_mbuf *om); @@ -437,11 +452,12 @@ 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 + * @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 + * @return 0 on success; + * an error code on failure */ int os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len); @@ -466,18 +482,21 @@ int os_mbuf_appendfrom(struct os_mbuf *dst, const struct os_mbuf *src, /** * Release a mbuf back to the pool * - * @param om The Mbuf to release back to the pool + * @param om The Mbuf to release back to the pool * - * @return 0 on success, -1 on failure + * @return 0 on success; + * -1 on failure */ int os_mbuf_free(struct os_mbuf *om); /** * Free a chain of mbufs * - * @param om The starting mbuf of the chain to free back into the pool + * @param om The starting mbuf of the chain to free back into + * the pool * - * @return 0 on success, -1 on failure + * @return 0 on success; + * -1 on failure */ int os_mbuf_free_chain(struct os_mbuf *om); @@ -485,10 +504,10 @@ 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 om 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. + * @param om 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 *om, int req_len); @@ -611,10 +630,12 @@ void *os_mbuf_extend(struct os_mbuf *om, uint16_t len); * extra bytes to the contiguous region, in an attempt to avoid being * called next time. * - * @param om The mbuf chain to make contiguous - * @param len The number of bytes in the chain to make contiguous + * @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. + * @return The contiguous mbuf chain on success; + * NULL on failure. */ struct os_mbuf *os_mbuf_pullup(struct os_mbuf *om, uint16_t len); @@ -657,10 +678,10 @@ int os_mbuf_widen(struct os_mbuf *om, uint16_t off, uint16_t len); * 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 + * @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 + * @return Pointer to resulting mbuf chain */ struct os_mbuf *os_mbuf_pack_chains(struct os_mbuf *m1, struct os_mbuf *m2);
