From 4a42c9a8deed2e40ee1b114d35ff5dccdcc843c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nils=20O=2E=20Sel=C3=A5sdal?= Date: Mon, 4 May 2015 22:57:49 +0200 Subject: [PATCH] Improve mbuf documentation --- include/ucore/mbuf.h | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/include/ucore/mbuf.h b/include/ucore/mbuf.h index 704cbe6..9272568 100644 --- a/include/ucore/mbuf.h +++ b/include/ucore/mbuf.h @@ -24,16 +24,17 @@ @endverbatim * * Initially when empty, head == tail, and the length is 0. - * Data is added to the tail. + * Data can be added to the tailroom or the headroom. + * The data is the memory from (including) head to (excluding) tail. * * If head == bufstart, there is no headroom * if tail points one past the allocated space, there is no * tailroom (the buffer is full) * * Conventions: - * push - prepend data to the buffer (in the head room part) + * push - prepend data to the buffer in the head room part * (move head to the left) - * pull - remove data from the beginning of the message. + * pull - remove data from the beginning of the data * (move head to the right) * put - Add data to the buffer. * (move tail to the right) @@ -103,7 +104,12 @@ struct MBuf *uc_mbuf_new_inline_hr(uint32_t len, uint32_t headroom); /** As uc_mbuf_new_inline_hr, but without any headroom*/ #define uc_mbuf_new_inline(len) uc_mbuf_new_inline_hr((len), 0) -/** @param mbuf the mbuf to free. (passing NULL is a no-op)*/ +/** Free the memory of an mbuf and its data. + * If passing in NULL or an mbuf with a UC_MBUF_FL_STATIC flag, + * no action is taken. + * + * @param mbuf the mbuf to free. + */ void uc_mbuf_free(struct MBuf *mbuf); /** Create a new mbuf, with a copy of the data from the given @@ -117,9 +123,7 @@ struct MBuf *uc_mbuf_copy_data(struct MBuf *mbuf); /** Initialize an mbuf. This function is mostly used internally, * but can be used to e.g. create an mbuf based on a local array * (in which case UC_MBUF_FL_STATIC must be set), or other data - * whose memory is already allocated. - * - * The whole buffer must have len + headroom available data + * whose memory is already allocated. * The whole buffer must have len + headroom available data * * @param mbuf to initialise * @param buf start of the buffer @@ -130,7 +134,7 @@ struct MBuf *uc_mbuf_copy_data(struct MBuf *mbuf); void uc_mbuf_init(struct MBuf *mbuf, uint8_t *restrict buf, uint32_t len, uint32_t headroom, uint32_t flags); -/** Zero out all the data in this mbuf, including the headroom +/** Zero out all the data in this mbuf, including the headroom and tailroom * * @param mbuf mbuf to zero out */