You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by st...@apache.org on 2016/05/20 21:07:23 UTC
incubator-mynewt-core git commit: document mbufs and malloc.
Repository: incubator-mynewt-core
Updated Branches:
refs/heads/develop 663d8e632 -> 6787578e6
document mbufs and malloc.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/commit/6787578e
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/tree/6787578e
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/diff/6787578e
Branch: refs/heads/develop
Commit: 6787578e6661476c431120ec7dd0f7244e834c7d
Parents: 663d8e6
Author: Sterling Hughes <st...@apache.org>
Authored: Fri May 20 16:07:16 2016 -0500
Committer: Sterling Hughes <st...@apache.org>
Committed: Fri May 20 16:07:16 2016 -0500
----------------------------------------------------------------------
libs/os/src/os_heap.c | 29 +++++-
libs/os/src/os_mbuf.c | 217 +++++++++++++++++++++++++++++++--------------
2 files changed, 180 insertions(+), 66 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/6787578e/libs/os/src/os_heap.c
----------------------------------------------------------------------
diff --git a/libs/os/src/os_heap.c b/libs/os/src/os_heap.c
index a94d3ad..5f5af95 100644
--- a/libs/os/src/os_heap.c
+++ b/libs/os/src/os_heap.c
@@ -6,7 +6,7 @@
* 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,
@@ -46,6 +46,16 @@ os_malloc_unlock(void)
}
}
+/**
+ * Operating system level malloc(). This ensures that a safe malloc occurs
+ * within the context of the OS. Depending on platform, the OS may rely on
+ * libc's malloc() implementation, which is not guaranteed to be thread-safe.
+ * This malloc() will always be thread-safe.
+ *
+ * @param size The number of bytes to allocate
+ *
+ * @return A pointer to the memory region allocated.
+ */
void *
os_malloc(size_t size)
{
@@ -58,6 +68,13 @@ os_malloc(size_t size)
return ptr;
}
+/**
+ * Operating system level free(). See description of os_malloc() for reasoning.
+ *
+ * Free's memory allocated by malloc.
+ *
+ * @param mem The memory to free.
+ */
void
os_free(void *mem)
{
@@ -66,6 +83,16 @@ os_free(void *mem)
os_malloc_unlock();
}
+/**
+ * Operating system level realloc(). See description of os_malloc() for reasoning.
+ *
+ * Reallocates the memory at ptr, to be size contiguouos bytes.
+ *
+ * @param ptr A pointer to the memory to allocate
+ * @param size The number of contiguouos bytes to allocate at that location
+ *
+ * @return A pointer to memory of size, or NULL on failure to allocate
+ */
void *
os_realloc(void *ptr, size_t size)
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-core/blob/6787578e/libs/os/src/os_mbuf.c
----------------------------------------------------------------------
diff --git a/libs/os/src/os_mbuf.c b/libs/os/src/os_mbuf.c
index b41ded6..85232d8 100644
--- a/libs/os/src/os_mbuf.c
+++ b/libs/os/src/os_mbuf.c
@@ -1,8 +1,8 @@
/*
* Software in this file is based heavily on code written in the FreeBSD source
- * code repostiory. While the code is written from scratch, it contains
- * many of the ideas and logic flow in the original source, this is a
- * derivative work, and the following license applies as well:
+ * code repostiory. While the code is written from scratch, it contains
+ * many of the ideas and logic flow in the original source, this is a
+ * derivative work, and the following license applies as well:
*
* Copyright (c) 1982, 1986, 1988, 1991, 1993
* The Regents of the University of California. All rights reserved.
@@ -33,22 +33,36 @@
*
*/
-
#include "os/os.h"
#include <assert.h>
#include <string.h>
-STAILQ_HEAD(, os_mbuf_pool) g_msys_pool_list =
+STAILQ_HEAD(, os_mbuf_pool) g_msys_pool_list =
STAILQ_HEAD_INITIALIZER(g_msys_pool_list);
-int
+/**
+ * Initialize a mbuf queue. An mbuf queue is a queue of mbufs that tie
+ * to a specific task's event queue. Mbuf queues are a helper API around
+ * a common paradigm, which is to wait on an event queue, until at least
+ * 1 packet is available, and 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 mbuf queue to initialize
+ * @param arg The argument to provide to the event posted on this mbuf queue
+ *
+ * @return 0 on success, non-zero on failure.
+ *
+ */
+int
os_mqueue_init(struct os_mqueue *mq, void *arg)
{
struct os_event *ev;
STAILQ_INIT(&mq->mq_head);
-
+
ev = &mq->mq_ev;
memset(ev, 0, sizeof(*ev));
ev->ev_arg = arg;
@@ -57,7 +71,13 @@ os_mqueue_init(struct os_mqueue *mq, void *arg)
return (0);
}
-
+/**
+ * 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 *mq)
{
@@ -81,13 +101,24 @@ os_mqueue_get(struct os_mqueue *mq)
return (m);
}
-int
+/**
+ * Put a new mbuf in the mbuf queue. Appends an mbuf to the end of the
+ * mbuf queue, and posts an event to the event queue passed in.
+ *
+ * @param mq The mbuf queue to append the mbuf to
+ * @param evq The event queue to post an OS_EVENT_T_MQUEUE_DATA 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 *mq, struct os_eventq *evq, struct os_mbuf *m)
{
struct os_mbuf_pkthdr *mp;
os_sr_t sr;
int rc;
+ /* Can only place the head of a chained mbuf on the queue. */
if (!OS_MBUF_IS_PKTHDR(m)) {
rc = OS_EINVAL;
goto err;
@@ -109,8 +140,24 @@ err:
return (rc);
}
-int
-os_msys_register(struct os_mbuf_pool *new_pool)
+/**
+ * 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 *new_pool)
{
struct os_mbuf_pool *pool;
@@ -140,7 +187,7 @@ os_msys_reset(void)
}
static struct os_mbuf_pool *
-_os_msys_find_pool(uint16_t dsize)
+_os_msys_find_pool(uint16_t dsize)
{
struct os_mbuf_pool *pool;
@@ -158,6 +205,16 @@ _os_msys_find_pool(uint16_t dsize)
return (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)
{
@@ -175,6 +232,15 @@ err:
return (NULL);
}
+/**
+ * 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)
{
@@ -187,7 +253,7 @@ os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len)
if (!pool) {
goto err;
}
-
+
m = os_mbuf_get_pkthdr(pool, user_hdr_len);
return (m);
err:
@@ -196,17 +262,17 @@ err:
/**
- * 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.
+ * 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 *omp, struct os_mempool *mp,
+int
+os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp,
uint16_t buf_len, uint16_t nbufs)
{
omp->omp_databuf_len = buf_len - sizeof(struct os_mbuf);
@@ -216,17 +282,17 @@ os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp,
return (0);
}
-/**
+/**
* 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
+ * @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 *
+struct os_mbuf *
os_mbuf_get(struct os_mbuf_pool *omp, uint16_t leadingspace)
{
struct os_mbuf *om;
@@ -252,7 +318,14 @@ err:
return (NULL);
}
-/* Allocate a new packet header mbuf out of the os_mbuf_pool */
+/**
+ * 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 user_pkthdr_len)
{
@@ -283,13 +356,13 @@ os_mbuf_get_pkthdr(struct os_mbuf_pool *omp, uint8_t user_pkthdr_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
+ * @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
+ * @return 0 on success, -1 on failure
*/
-int
-os_mbuf_free(struct os_mbuf *om)
+int
+os_mbuf_free(struct os_mbuf *om)
{
int rc;
@@ -309,11 +382,11 @@ err:
* 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
+ * @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
+int
os_mbuf_free_chain(struct os_mbuf *om)
{
struct os_mbuf *next;
@@ -335,38 +408,38 @@ err:
return (rc);
}
-/**
+/**
* Copy a packet header from one mbuf to another.
*
* @param omp The mbuf pool associated with these buffers
- * @param new_buf The new buffer to copy the packet header into
+ * @param new_buf The new buffer to copy the packet header into
* @param old_buf The old buffer to copy the packet header from
*/
-static inline void
+static inline void
_os_mbuf_copypkthdr(struct os_mbuf *new_buf, struct os_mbuf *old_buf)
{
assert(new_buf->om_len == 0);
- memcpy(&new_buf->om_databuf[0], &old_buf->om_databuf[0],
+ memcpy(&new_buf->om_databuf[0], &old_buf->om_databuf[0],
old_buf->om_pkthdr_len);
new_buf->om_pkthdr_len = old_buf->om_pkthdr_len;
new_buf->om_data = new_buf->om_databuf + old_buf->om_pkthdr_len;
}
-/**
- * Append data onto a mbuf
+/**
+ * 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, and an error code on failure
*/
-int
+int
os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len)
{
struct os_mbuf_pool *omp;
- struct os_mbuf *last;
+ struct os_mbuf *last;
struct os_mbuf *new;
int remainder;
int space;
@@ -388,7 +461,7 @@ os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len)
remainder = len;
space = OS_MBUF_TRAILINGSPACE(last);
- /* If room in current mbuf, copy the first part of the data into the
+ /* If room in current mbuf, copy the first part of the data into the
* remaining space in that mbuf.
*/
if (space > 0) {
@@ -403,11 +476,11 @@ os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len)
remainder -= space;
}
- /* Take the remaining data, and keep allocating new mbufs and copying
+ /* Take the remaining data, and keep allocating new mbufs and copying
* data into it, until data is exhausted.
*/
while (remainder > 0) {
- new = os_mbuf_get(omp, 0);
+ new = os_mbuf_get(omp, 0);
if (!new) {
break;
}
@@ -428,29 +501,29 @@ os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len)
if (remainder != 0) {
rc = OS_ENOMEM;
goto err;
- }
+ }
return (0);
err:
- return (rc);
+ return (rc);
}
/**
* 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
+ * @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
+ * @return A pointer to the new chain of mbufs
*/
struct os_mbuf *
os_mbuf_dup(struct os_mbuf *om)
{
struct os_mbuf_pool *omp;
struct os_mbuf *head;
- struct os_mbuf *copy;
+ struct os_mbuf *copy;
omp = om->om_omp;
@@ -459,8 +532,8 @@ os_mbuf_dup(struct os_mbuf *om)
for (; om != NULL; om = SLIST_NEXT(om, om_next)) {
if (head) {
- SLIST_NEXT(copy, om_next) = os_mbuf_get(omp,
- OS_MBUF_LEADINGSPACE(om));
+ SLIST_NEXT(copy, om_next) = os_mbuf_get(omp,
+ OS_MBUF_LEADINGSPACE(om));
if (!SLIST_NEXT(copy, om_next)) {
os_mbuf_free_chain(head);
goto err;
@@ -530,6 +603,11 @@ os_mbuf_off(struct os_mbuf *om, int off, int *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.
*/
@@ -567,6 +645,15 @@ os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst)
return (len > 0 ? -1 : 0);
}
+/**
+ * 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)
{
@@ -928,16 +1015,16 @@ 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
+ * 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"
+ * 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 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
*