Repository: incubator-mynewt-site Updated Branches: refs/heads/os_tasks 22c090fb0 -> fb6890bcb
MYNEWT-147: add mbuf documentation Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/fb6890bc Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/fb6890bc Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/fb6890bc Branch: refs/heads/os_tasks Commit: fb6890bcb1b7700979dc5376fae8fb084d566dca Parents: 22c090f Author: wes3 <w...@micosa.io> Authored: Tue Mar 1 17:50:08 2016 -0800 Committer: wes3 <w...@micosa.io> Committed: Tue Mar 1 17:50:08 2016 -0800 ---------------------------------------------------------------------- docs/os/core_os/mbuf/OS_MBUF_DATA.md | 33 +++ docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md | 44 ++++ docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md | 42 ++++ docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md | 31 +++ docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md | 36 ++++ docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md | 42 ++++ docs/os/core_os/mbuf/OS_MBUF_USRHDR.md | 31 +++ docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md | 32 +++ docs/os/core_os/mbuf/_os_mbuf_copypkthdr.md | 0 docs/os/core_os/mbuf/_os_msys_find_pool.md | 0 docs/os/core_os/mbuf/mbuf.md | 219 +++++++++++++++++++- docs/os/core_os/mbuf/os_mbuf_adj.md | 46 ++++ docs/os/core_os/mbuf/os_mbuf_append.md | 61 ++++++ docs/os/core_os/mbuf/os_mbuf_concat.md | 50 +++++ docs/os/core_os/mbuf/os_mbuf_copydata.md | 56 +++++ docs/os/core_os/mbuf/os_mbuf_copyinto.md | 56 +++++ docs/os/core_os/mbuf/os_mbuf_dup.md | 42 ++++ docs/os/core_os/mbuf/os_mbuf_extend.md | 45 ++++ docs/os/core_os/mbuf/os_mbuf_free.md | 43 ++++ docs/os/core_os/mbuf/os_mbuf_free_chain.md | 42 ++++ docs/os/core_os/mbuf/os_mbuf_get.md | 43 ++++ docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md | 44 ++++ docs/os/core_os/mbuf/os_mbuf_memcmp.md | 46 ++++ docs/os/core_os/mbuf/os_mbuf_off.md | 56 +++++ docs/os/core_os/mbuf/os_mbuf_pool_init.md | 64 ++++++ docs/os/core_os/mbuf/os_mbuf_prepend.md | 50 +++++ docs/os/core_os/mbuf/os_mbuf_pullup.md | 50 +++++ docs/os/core_os/mbuf/os_msys_get.md | 46 ++++ docs/os/core_os/mbuf/os_msys_get_pkthdr.md | 48 +++++ docs/os/core_os/mbuf/os_msys_register.md | 35 ++++ docs/os/core_os/mbuf/os_msys_reset.md | 33 +++ docs/os/core_os/mbuf/pics/mbuf_fig1.png | Bin 0 -> 32123 bytes docs/os/core_os/mbuf/pics/mbuf_fig2.png | Bin 0 -> 40402 bytes docs/os/core_os/mbuf/pics/mbuf_fig3.png | Bin 0 -> 54819 bytes mkdocs.yml | 11 +- 35 files changed, 1463 insertions(+), 14 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_DATA.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_DATA.md b/docs/os/core_os/mbuf/OS_MBUF_DATA.md new file mode 100644 index 0000000..016f95e --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_DATA.md @@ -0,0 +1,33 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_DATA</font> + +```no-highlight +OS_MBUF_DATA(__om, __type) +``` + +Macro used to cast the data pointer of an mbuf to a given type. + + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *) | +| __type | Type to cast | + + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om + uint8_t *rxbuf; + + rxbuf = OS_MBUF_DATA(om, uint8_t *); +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md b/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md new file mode 100644 index 0000000..fee5f4e --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md @@ -0,0 +1,44 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_LEADINGSPACE</font> + +```no-highlight +OS_MBUF_LEADINGSPACE(__om) +``` + +Macro used to get the amount of leading space in an mbuf (in bytes). + + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *) | + + +<br> + +#### Notes +This macro works on both normal mbufs and packet header mbufs. The amount of leading space is the number of bytes between the current om_data pointer of the mbuf and the start of the mbuf user data buffer. + +<br> + +#### Example + +```no-highlight + uint8_t *dptr; + uint16_t space; + struct os_mbuf *om; + struct my_data_struct my_data; + + /* Copy data from "my_data" into the start of an mbuf but only if there is enough room */ + space = OS_MBUF_LEADINGSPACE(om); + if (space >= sizeof(struct my_data_struct)) { + dptr = om->om_data - sizeof(struct my_data_struct); + memcpy(dptr, &my_data, sizeof(struct my_data_struct)); + } +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md new file mode 100644 index 0000000..6509030 --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR.md @@ -0,0 +1,42 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_PKTHDR</font> + +```no-highlight +OS_MBUF_PKTHDR(__om) +``` + +Macro used to get a pointer to the os mbuf packet header of a mbuf. + + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *) | + + +<br> + +#### Example + +```no-highlight +int +does_packet_have_data(struct os_mbuf *om) +{ + struct os_mbuf_pkthdr *hdr; + + hdr = OS_MBUF_PKTHDR(om); + if (hdr->omp_len != 0) { + /* Packet has data in it */ + return TRUE + } else { + /* Packet has no data */ + return FALSE; + } +} +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md new file mode 100644 index 0000000..f53a895 --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md @@ -0,0 +1,31 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_PKTHDR_TO_MBUF</font> + +```no-highlight +OS_MBUF_PKTHDR_TO_MBUF(__hdr) +``` + +Macro used to get a pointer to the mbuf given a pointer to the os mbuf packet header + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __hdr | Pointer to os mbuf packet header (struct os_mbuf_pkthdr *) | + +<br> + + +#### Example + +```no-highlight + struct os_mbuf *om; + struct os_mbuf_pkthdr *hdr; + + om = OS_MBUF_PKTHDR_TO_MBUF(hdr); + os_mbuf_free_chain(om); +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md b/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md new file mode 100644 index 0000000..eb995a1 --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_PKTLEN.md @@ -0,0 +1,36 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_PKTLEN</font> + +```no-highlight +OS_MBUF_PKTLEN(__om) +``` + +Macro used to get the length of an entire mbuf chain. + + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *) | + + +<br> + +#### Example + +```no-highlight + uint16_t pktlen; + struct os_mbuf *om; + + /* Check if there is any data in the mbuf chain */ + pktlen = OS_MBUF_PKTLEN(om); + if (pktlen != 0) { + /* mbuf chain has data */ + } +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md b/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md new file mode 100644 index 0000000..4e9f344 --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md @@ -0,0 +1,42 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_TRAILINGSPACE</font> + +```no-highlight +OS_MBUF_TRAILINGSPACE(__om) +``` + +Macro used to get the amount of trailing space in an mbuf (in bytes). + + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *) | + + +<br> + +#### Notes +This macro works on both normal mbufs and packet header mbufs. The amount of trailing space is the number of bytes between the current om_data pointer of the mbuf and the end of the mbuf. + +<br> + +#### Example + +```no-highlight + uint16_t space; + struct os_mbuf *om; + struct my_data_struct my_data; + + /* Copy data from "my_data" to the end of an mbuf but only if there is enough room */ + space = OS_MBUF_TRAILINGSPACE(om); + if (space >= sizeof(struct my_data_struct)) { + memcpy(om->om_data, &my_data, sizeof(struct my_data_struct)); + } +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md b/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md new file mode 100644 index 0000000..0c55866 --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_USRHDR.md @@ -0,0 +1,31 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_USRHDR</font> + +```no-highlight +OS_MBUF_USRHDR(__om) +``` + +Macro used to get a pointer to the user packet header of a mbuf. + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf) | + + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om + struct user_header *hdr; + + hdr = OS_MBUF_USRHDR(om); +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md b/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md new file mode 100644 index 0000000..2a5971e --- /dev/null +++ b/docs/os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md @@ -0,0 +1,32 @@ +## <font color="#F2853F" style="font-size:24pt">OS_MBUF_USRHDR_LEN</font> + +```no-highlight +OS_MBUF_USRHDR_LEN(__om) +``` + +Macro used to retrieve the length of the user packet header in a mbuf. + +<br> + + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| __om | Pointer to mbuf (struct os_mbuf *). Must be head of chain (i.e. a packet header mbuf) | + + +<br> + +#### Example + +```no-highlight + uint16_t user_length; + struct os_mbuf *om + struct user_header *hdr; + + user_length = OS_MBUF_USRHDR_LEN(om); +``` + +--------------------- + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/_os_mbuf_copypkthdr.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/_os_mbuf_copypkthdr.md b/docs/os/core_os/mbuf/_os_mbuf_copypkthdr.md deleted file mode 100644 index e69de29..0000000 http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/_os_msys_find_pool.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/_os_msys_find_pool.md b/docs/os/core_os/mbuf/_os_msys_find_pool.md deleted file mode 100644 index e69de29..0000000 http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/mbuf.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/mbuf.md b/docs/os/core_os/mbuf/mbuf.md index 976f425..8f39f31 100644 --- a/docs/os/core_os/mbuf/mbuf.md +++ b/docs/os/core_os/mbuf/mbuf.md @@ -1,23 +1,223 @@ # Mbufs +The mbuf (short for memory buffer) is a common concept in networking stacks. The mbuf is used to hold packet data as it traverses the stack. The mbuf also generally stores header information or other networking stack information that is carried around with the packet. The mbuf and its associated library of functions were developed to make common networking stack operations (like stripping and adding protocol headers) efficient and as copy-free as possible. -Insert synopsis here +In its simplest form, a mbuf is a memory block with some space reserved for internal information and a pointer which is used to "chain" memory blocks together in order to create a "packet". This is a very important aspect of the mbuf: the ability to chain mbufs together to create larger "packets" (chains of mbufs). +Why use mbufs? The main reason is to conserve memory. Consider a networking protocol that generally sends small packets but occasionally sends large ones (The Bluetooth Low Energy (BLE) protocol, is one such example). A flat buffer would need to be sized so that the maximum packet size could be contained by the buffer. With the mbuf, a number of mbufs can be chained together so that the occasional large packet can be handled while leaving more packet buffers available to the networking stack for smaller packets. + +Not all mbufs are created equal. The first mbuf in a chain of mbufs is a special mbuf called a "packet header mbuf". The reason that this mbuf is special is that it contains the length of all the data contained by the chain of mbufs (the packet length, if you will). The packet header mbuf may also contain a user defined structure (called a "user header") so that networking protocol specific information can be conveyed to various layers of the networking stack. Any mbufs that are part of the packet (i.e. in the mbuf chain but not the first one) are "normal" (i.e. non-packet header) mbufs. A normal mbuf does not have any packet header or user packet header structures in them; they only contain the basic mbuf header (`struct os_mbuf`). Figure 1 illustrates these two types of mbufs. Note that the numbers/text in parentheses denote the size of the structures/elements (in bytes) and that MBLEN is the memory block length of the memory pool used by the mbuf pool. + + + +Now let's take a deeper dive into the mbuf structure. Figure 2 illustrates a normal mbuf and breaks out the various fields in the `os_mbuf` structure. The *om_data* field is a pointer to where the data starts inside the data buffer. Typically, mbufs that are allocated from the mbuf pool (discussed later) have their om_data pointer set to the start of the data buffer but there are cases where this may not be desirable (added a protocol header to a packet, for example). The *om_flags* field is a set of flags used internally by the mbuf library. Currently, no flags have been defined. The *om_pkthdr_len* field is the total length of all packet headers in the mbuf. For normal mbufs this is set to 0 as there is no packet or user packet headers. For packet header mbufs, this would be set to the length of the packet header structure (16) plus the size of the user packet header (if any). Note that it is this field which differentiates packet header mbufs from normal mbufs (i.e. if *om_pkthdr _len* is zero, this is a normal mbuf; otherwise it is a packet header mbuf). The *om_len* field contains the amount of user data in the data buffer. When initially allocated, this field is 0 as there is no user data in the mbuf. The *omp_pool* field is a pointer to the pool from which this mbuf has been allocated. This is used internally by the mbuf library. The *omp_next* field is a linked list element which is used to chain mbufs. + +Figure 2 also shows a normal mbuf with actual values in the `os_mbuf` structure. This mbuf starts at address 0x1000 and is 256 bytes in total length. In this example, the user has copied 33 bytes into the data buffer starting at address 0x1010 (this is where om_data points). Note that the packet header length in this mbuf is 0 as it is not a packet header mbuf. + + + +Figure 3 illustrates the packet header mbuf along with some chained mbufs (i.e a "packet"). In this example, the user header structure is defined to be 8 bytes. Note that in figure 3 we show a number of different mbufs with varying *om_data* pointers and lengths since we want to show various examples of valid mbufs. For all the mbufs (both packet header and normal ones) the total length of the memory block is 128 bytes. + + + +Mbufs are collected into "mbuf pools" much like memory blocks. The mbuf pool itself contains a pointer to a memory pool. The memory blocks in this memory pool are the actual mbufs; both normal and packet header mbufs. Thus, the memory block (and corresponding memory pool) must be sized correctly. In other words, the memory blocks which make up the memory pool used by the mbuf pool must be at least: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_defined_header) + desired minimum data buffer length. For example, if the developer wants mbufs to contain at least 64 bytes of user data and they have a user header of 12 bytes, the size of the memory block would be (at least): 64 + 12 + 16 + 8, or 100 bytes. Yes, this is a fair amount of overhead. However, the flexibility provided by the mbuf library usually outweighs overhead concerns. ## Description -Describe OS feature here +Creating a mbuf pool is fairly simple: create a memory pool and then create the mbuf pool using that memory pool. Once the developer has determined the size of the user data needed per mbuf (this is based on the application/networking stack and is outside the scope of this discussion) and the size of the user header (if any), the memory blocks can be sized. In the example shown below, the application requires 64 bytes of user data per mbuf and also allocates a user header (called struct user_hdr). Note that we dont show the user header data structure as there really is no need; all we need to do is to account for it when creating the memory pool. In the example, we use the macro *MBUF_PKTHDR_OVERHEAD* to denote the amount of packet header overhead per mbuf and *MBUF_MEMBLOCK_OVERHEAD* to denote the total amount of overhead required per memory block. The macro *MBUF_BUF_SIZE* is used to denote the amount of payload that the application requires (aligned on a 32-bit boundary in this c ase). All this leads to the total memory block size required, denoted by the macro *MBUF_MEMBLOCK_OVERHEAD*. + + +```no-highlight + +#define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr) +#define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD + +#define MBUF_NUM_MBUFS (32) +#define MBUF_PAYLOAD_SIZE (64) +#define MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4) +#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD) +#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE) + +struct os_mbuf_pool g_mbuf_pool; +struct os_mempool g_mbuf_mempool; +os_membuf_t g_mbuf_buffer[MBUF_MEMPOOL_SIZE]; + +void +create_mbuf_pool(void) +{ + int rc; + + rc = os_mempool_init(&g_mbuf_mempool, MBUF_NUM_MBUFS, + MBUF_MEMBLOCK_SIZE, &g_mbuf_buffer[0], "mbuf_pool"); + assert(rc == 0); + + rc = os_mbuf_pool_init(&g_mbuf_pool, &g_mbuf_mempool, MBUF_MEMBLOCK_SIZE, + MBUF_NUM_MBUFS); + assert(rc == 0); +} + +``` + +The following example illustrates typical mbuf usage. There are two basic mbuf allocation API: `os_mbuf_get()` and `os_mbuf_get_pkthdr()`. The first API obtains a normal mbuf whereas the latter obtains a packet header mbuf. Typically, application developers use `os_mbuf_get_pkthdr()` and rarely, if ever, need to call `os_mbuf_get()` as the other mbuf API typically deal with allocating and chaining mbufs. It is recommended to use the provided API to copy data into/out of mbuf chains and/or manipulate mbufs (for reasons which are hopefully apparent to the reader). + +In example 1, the developer creates a packet and then sends the packet to a networking interface. The code sample also provides an example of copying data out of an mbuf as well as use of the "pullup" api (another very common mbuf api). + +In example 2 we show use of the pullup api as this illustrates some of the typical pitfalls developers encounter when using mbufs. The first pitfall is one of alignment/padding. Depending on the processor and/or compiler, the sizeof() a structure may vary. Thus, the size of *my_protocol_header* may be different inside the packet data of the mbuf than the size of the structure on the stack or as a global variable, for instance. While some networking protcols may align protocol information on convenient processor boundaries many others try to conserve bytes "on the air" (i.e inside the packet data). Typical methods used to deal with this are "packing" the structure (i.e. force compiler to not pad) or creating protocol headers that do not require padding. Example 2 assumes that one of these methods was used when defining the *my_protocol_header* strcture. + +Example 2 also demonstrates (albeit a bit opaquely) the endianness pitfall. A network protocol may be little endian or big endian; it all depends on the protocol specification. Processors also have an endianness; this means that the developer has to be careful that the processor endianness and the protocol endianness are handled correctly. In example 2, some common networking functions are used: `ntohs()` and `ntohl()`. These are shorthand for "network order to host order, short" and "network order to host order, long". Basically, these functions convert data of a certain size (i.e. 16 bits, 32 bits, etc) to the endianness of the host. Network byte order is big-endian (most significant byte first), so these functions convert big-endian byte order to host order (thus, the implementation of these functions is host dependent). Note that the BLE networking stack "on the air" format is least signigicant byte first (i.e. little endian), so a "bletoh" function would have to take little end ian format and convert to host format. + +A long story short: the developer must take care when copying structure data to/from mbufs and flat buffers! + +A final note: these examples assume the same mbuf struture and definitions used in the previous example. + +```no-highlight + +void +mbuf_usage_example1(uint8_t *mydata, int mydata_length) +{ + int rc; + struct os_mbuf *om; + + /* get a packet header mbuf */ + om = os_mbuf_get_pkthdr(&g_mbuf_pool, sizeof(struct user_hdr)); + if (om) { + /* + * Copy user data into mbuf. NOTE: if mydata_length is greater than the + * mbuf payload size (64 bytes using above example), mbufs are allocated + * and chained together to accommodate the total packet length. + */ + rc = os_mbuf_copyinto(om, 0, mydata, len); + if (rc) { + /* Error! Could not allocate enough mbufs for total packet length */ + return -1; + } + + /* Send packet to networking interface */ + send_pkt(om); + } +} + +void +mbuf_usage_example2(struct mbuf *rxpkt) +{ + int rc; + uint8_t packet_data[16]; + struct mbuf *om; + struct my_protocol_header *phdr; + + /* Make sure that "my_protocol_header" bytes are contiguous in mbuf */ + om = os_mbuf_pullup(&g_mbuf_pool, sizeof(struct my_protocol_header)); + if (!om) { + /* Not able to pull up data into contiguous area */ + return -1; + } + + /* + * Get the protocol information from the packet. In this example we presume that we + * are interested in protocol types that are equal to MY_PROTOCOL_TYPE, are not zero + * length, and have had some time in flight. + */ + phdr = OS_MBUF_DATA(om, struct my_protocol_header *); + type = ntohs(phdr->prot_type); + length = ntohs(phdr->prot_length); + time_in_flight = ntohl(phdr->prot_tif); + + if ((type == MY_PROTOCOL_TYPE) && (length > 0) && (time_in_flight > 0)) { + rc = os_mbuf_copydata(rxpkt, sizeof(struct my_protocol_header), 16, packet_data); + if (!rc) { + /* Success! Perform operations on packet data */ + <... user code here ...> + } + } + + /* Free passed in packet (mbuf chain) since we dont need it anymore */ + os_mbuf_free_chain(om); +} + +``` + +<br> + +# MSYS + +MSYS stands for "system mbufs" and is set of API built on top of the mbuf code. The basic idea behind msys is the following. The developer can create different size mbuf pools and register them with msys. The application then allocates mbufs using the msys API (as opposed to the mbuf API). The msys code will choose the mbuf pool with the smallest mbufs that can accommodate the requested size. For example, the user registers three mbuf pools with msys: one with 32 byte mbufs, one with 256 and one with 2048. If the user requests a mbuf with 10 bytes, the 32-byte mbuf pool is used. If the request is for 33 bytes the 256 byte mbuf pool is used. If a mbuf data size is requested that is larger than any of the pools (say, 4000 bytes) the largest pool is used. While this behaviour may not be optimal in all cases that is the currently implemented behaviour. All this means is that the user is not guaranteed that a single mbuf cannot hold the requested data. + +Another msys note: the msys code will not allocate a mbuf from a larger pool if the chosen mbuf pool is empty. Similarly, the msys code will not chain together a number of smaller mbufs to accommodate the requested size. While this behaviour may change in future implementation the current code will simply return NULL. Using the above example, say the user request 250 bytes. The msys code chooses the appropriate pool (i.e. the 256 byte mbuf pool) and attempts to allocate a mbuf from that pool. If that pool is empty, NULL is returned even though the 32 and 2048 byte pools are not empty. + +Note that no added description on how to use the msys API are presented here (other than in the API descriptions themselves) as the msys API are used in exactly the same manner as the mbuf API. The only difference is that mbuf pools are added to msys by calling `os_msys_register().` + +<br> + +## Data Structures + +```no-highlight +struct os_mbuf_pool { + uint16_t omp_databuf_len; + uint16_t omp_mbuf_count; + struct os_mempool *omp_pool; + STAILQ_ENTRY(os_mbuf_pool) omp_next; +}; +``` + +| **Element** | **Description** | +|-----------|-------------| +| omp_databuf_len | The length, in bytes, of the "data buffer" of the mbuf. The data buffer of the mbuf is everything except the os_mbuf structure (which is present in all types of mbufs)| +| omp_mbuf_count | Total number of mbufs in the pool when allocated. This is NOT the number of free mbufs in the pool! | +| omp_pool | The memory pool from which the mbufs are allocated | +| omp_next | This is a linked list pointer which chains memory pools. It is used by the system memory pool library | + +<br> + +```no-highlight +struct os_mbuf_pkthdr { + uint16_t omp_len; + uint16_t omp_flags; + STAILQ_ENTRY(os_mbuf_pkthdr) omp_next; +}; +``` + +| **Element** | **Description** | +|-----------|-------------| +| omp_len | Length, in bytes, of the "packet". This is the sum of the user data in all the mbufs chained to the packet header mbuf (including the packet header mbuf)| +| omp_flags | Packet header flags. | +| omp_next | Linked list pointer to chain "packets". This can be used to add mbuf chains to a queue or linked list and is there for convenience. | + +<br> -## Data structures +```no-highlight +struct os_mbuf { + uint8_t *om_data; + uint8_t om_flags; + uint8_t om_pkthdr_len; + uint16_t om_len; + struct os_mbuf_pool *om_omp; + SLIST_ENTRY(os_mbuf) om_next; + uint8_t om_databuf[0]; +}; +``` -Replace this with the list of data structures used, why, any neat features +| **Element** | **Description** | +|-----------|-------------| +| om_data | Pointer to start of user data in mbuf data buffer | +| om_flags | mbuf flags field. Currently all flags unused. | +| om_pkthdr_len | The total length of all packet headers in the mbuf (mbuf packet header plus user packet header), in bytes | +| om_len | The length of the user data contained in this mbuf, in bytes | +| om_omp | Memory pool pointer. This is the mbuf pool from which this mbuf was allocated. | +| om_next | Pointer to next mbuf in packet chain | +| om_databuf | mbuf data buffer (accessor to start of mbuf data buffer). Note that the mbuf data buffer refers to the start of either the user data in normal mbufs or the start of the os mbuf packet header for packet header mbufs | -## List of Functions +## List of Functions/Macros -The functions available in mbuf are: +The functions/macros available in mbuf are: -* [_os_mbuf_copypkthdr](_os_mbuf_copypkthdr.md) -* [_os_msys_find_pool](_os_msys_find_pool.md) +* [OS_MBUF_PKTHDR](OS_MBUF_PKTHDR.md) +* [OS_MBUF_PKTHDR_TO_MBUF](OS_MBUF_PKTHDR_TO_MBUF.md) +* [OS_MBUF_PKTLEN](OS_MBUF_PKTLEN.md) +* [OS_MBUF_DATA](OS_MBUF_DATA.md) +* [OS_MBUF_USRHDR](OS_MBUF_USRHDR.md) +* [OS_MBUF_USRHDR_LEN](OS_MBUF_USRHDR_LEN.md) +* [OS_MBUF_LEADINGSPACE](OS_MBUF_LEADINGSPACE.md) +* [OS_MBUF_TRAILINGSPACE](OS_MBUF_TRAILINGSPACE.md) * [os_mbuf_adj](os_mbuf_adj.md) * [os_mbuf_append](os_mbuf_append.md) * [os_mbuf_concat](os_mbuf_concat.md) @@ -34,9 +234,6 @@ The functions available in mbuf are: * [os_mbuf_pool_init](os_mbuf_pool_init.md) * [os_mbuf_prepend](os_mbuf_prepend.md) * [os_mbuf_pullup](os_mbuf_pullup.md) -* [os_mqueue_get](os_mqueue_get.md) -* [os_mqueue_init](os_mqueue_init.md) -* [os_mqueue_put](os_mqueue_put.md) * [os_msys_get](os_msys_get.md) * [os_msys_get_pkthdr](os_msys_get_pkthdr.md) * [os_msys_register](os_msys_register.md) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_adj.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_adj.md b/docs/os/core_os/mbuf/os_mbuf_adj.md index e69de29..75caa3e 100644 --- a/docs/os/core_os/mbuf/os_mbuf_adj.md +++ b/docs/os/core_os/mbuf/os_mbuf_adj.md @@ -0,0 +1,46 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_adj</font> + +```no-highlight +void os_mbuf_adj(struct os_mbuf *mp, int req_len); +``` + +Trims *req_len* bytes from either the head (if positive) or tail (if negative) of a mbuf chain. Adjusts the packet length of the mbuf chain if *mp* points to a packet header mbuf. When trimming from the head, no mbufs are freed. When trimming from the tail, any mbufs of zero length left at the end of the chain are freed. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| mp | Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf | +| req_len | Number of bytes to trim from head or tail of mbuf + + +<br> + +#### Returned values + +None + +#### Notes + + +#### Example + +```no-highlight + uint16_t pktlen; + struct os_mbuf *om; + struct my_pkt_header hdr; + + /* Get mbuf chain length */ + pktlen = OS_MBUF_PKTLEN(om); + + /* Strip header from mbuf chain */ + os_mbuf_adj(om, sizeof(struct my_pkt_header)); + pktlen -= sizeof(struct my_pkt_header); + + /* New packet length should be old packet length minus stripped header */ + assert(pktlen == OS_MBUF_PKTLEN(om)); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_append.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_append.md b/docs/os/core_os/mbuf/os_mbuf_append.md index e69de29..c2a65d0 100644 --- a/docs/os/core_os/mbuf/os_mbuf_append.md +++ b/docs/os/core_os/mbuf/os_mbuf_append.md @@ -0,0 +1,61 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_append</font> + +```no-highlight +int os_mbuf_append(struct os_mbuf *om, const void *data, uint16_t len) +``` + +Appends a data buffer of length *len* to the end of a mbuf chain, adjusting packet length if *om* is a packet header mbuf. If not enough trailing space exists at the end of the mbuf chain, mbufs are allocated to hold the data. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf. Can be head of a chain of mbufs, a single mbuf or a packet header mbuf | +| data | Pointer to data buffer to copy from | +| len | Number of bytes to copy from data buffer to the end of the mbuf | + + +<br> + +#### Returned values + +0: success +OS_ENOMEM: Could not allocate enough mbufs to hold data. +OS_EINVAL: *om* was NULL on entry. + +<br> + +#### Notes +If not enough mbufs were available the packet header length of the mbuf may get adjusted even though the entire data buffer was not appended to the end of the mbuf. + +<br> + +If any mbufs are allocated, they are allocated from the same pool as *om* + +<br> + +#### Example + +```no-highlight + int rc; + uint16_t pktlen; + struct os_mbuf *om; + struct my_data_struct my_data; + + /* Get initial packet length */ + pktlen = OS_MBUF_PKTLEN(om); + + /* Append "my_data" to end of mbuf, freeing mbuf if unable to append all the data */ + rc = os_mbuf_append(om, &my_data, sizeof(struct my_pkt_header)); + if (rc) { + os_mbuf_free_chain(om); + } + pktlen += sizeof(struct my_pkt_header); + + /* New packet length should be initial packet length plus length of "my_data" */ + assert(pktlen == OS_MBUF_PKTLEN(om)); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_concat.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_concat.md b/docs/os/core_os/mbuf/os_mbuf_concat.md index e69de29..9e8bc7c 100644 --- a/docs/os/core_os/mbuf/os_mbuf_concat.md +++ b/docs/os/core_os/mbuf/os_mbuf_concat.md @@ -0,0 +1,50 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_concat</font> + +```no-highlight +void os_mbuf_concat(struct os_mbuf *first, struct os_mbuf *second) +``` + +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. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| first | Pointer to first mbuf chain | +| second | Pointer to second mbuf chain | + +<br> + +#### Returned values + +None + +<br> + +#### Notes +No data is copied or moved nor are any mbufs freed. + +<br> + +#### Example + +```no-highlight + uint16_t pktlen1; + uint16_t pktlen2; + struct os_mbuf *pkt1; + struct os_mbuf *pkt2; + + /* Get initial packet lengths */ + pktlen1 = OS_MBUF_PKTLEN(pkt1); + pktlen2 = OS_MBUF_PKTLEN(pkt2); + + /* Add pkt2 to end of pkt1 */ + os_mbuf_concat(pkt1, pkt2); + + /* New packet length should be sum of pkt1 and pkt2 */ + assert((pktlen1 + pktlen2) == OS_MBUF_PKTLEN(pkt1)); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_copydata.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_copydata.md b/docs/os/core_os/mbuf/os_mbuf_copydata.md index e69de29..7bee2a7 100644 --- a/docs/os/core_os/mbuf/os_mbuf_copydata.md +++ b/docs/os/core_os/mbuf/os_mbuf_copydata.md @@ -0,0 +1,56 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_copydata</font> + +```no-highlight +int os_mbuf_copydata(const struct os_mbuf *m, int off, int len, void *dst) +``` + +Copy data from an mbuf chain starting *off* bytes from the beginning, continuing for *len* bytes, into the indicated buffer. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| m | Pointer to mbuf chain | +| off | Start copy offset, in bytes, from beginning of mbuf chain | +| len | Number of bytes to copy | +| dst | Data buffer to copy into | + +<br> + +#### Returned values + +0: success. +-1: The mbuf does not contain enough data + +<br> + +#### Notes + +<br> + +#### Example + +```no-highlight + int rc; + struct os_mbuf *om; + struct my_hdr_1 my_hdr1; + struct my_hdr_2 my_hdr2; + + /* Header 1 and Header 2 are contiguous in packet at start. Retrieve them from the mbuf chain */ + rc = os_mbuf_copydata(om, 0, sizeof(struct my_hdr_1), &my_hdr1); + if (rc) { + /* error! */ + return -1; + } + + rc = os_mbuf_copydata(om, sizeof(struct my_hdr_1), sizeof(struct my_hdr_2), &my_hdr2); + if (rc) { + /* error! */ + return -1; + } + +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_copyinto.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_copyinto.md b/docs/os/core_os/mbuf/os_mbuf_copyinto.md index e69de29..9565a05 100644 --- a/docs/os/core_os/mbuf/os_mbuf_copyinto.md +++ b/docs/os/core_os/mbuf/os_mbuf_copyinto.md @@ -0,0 +1,56 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_copyinto</font> + +```no-highlight +int os_mbuf_copyinto(struct os_mbuf *om, int off, const void *src, int 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. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf chain | +| off | Start copy offset, in bytes, from beginning of mbuf chain | +| src | Address from which bytes are copied | +| len | Number of bytes to copy from src | + +<br> + +#### Returned values + +0: success. +All other values indicate an error. + +<br> + +#### Notes + +<br> + +#### Example + +```no-highlight + int rc; + uint16_t pktlen; + struct os_mbuf *om; + struct my_data_struct my_data; + + /* Get initial packet length */ + pktlen = OS_MBUF_PKTLEN(om); + + /* Copy "my_data" into mbuf */ + rc = os_mbuf_copyinto(om, 0, &my_data, sizeof(struct my_data_struct)); + if (rc) { + os_mbuf_free_chain(om); + return; + } + + /* Packet length should have increased by size of "my_data" */ + pktlen += sizeof(struct my_data_struct); + assert(pktlen == OS_MBUF_PKTLEN(om)); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_dup.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_dup.md b/docs/os/core_os/mbuf/os_mbuf_dup.md index e69de29..5e2f850 100644 --- a/docs/os/core_os/mbuf/os_mbuf_dup.md +++ b/docs/os/core_os/mbuf/os_mbuf_dup.md @@ -0,0 +1,42 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_dup</font> + +```no-highlight +struct os_mbuf *os_mbuf_dup(struct os_mbuf *om) +``` + +Duplicate a chain of mbufs. Return the start of the duplicated chain. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf chain to duplicate | + +<br> + +#### Returned values + +Pointer to the duplicated chain or NULL if not enough mbufs were available to duplicate the chain. + +<br> + +#### Notes + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om; + struct os_mbuf *new_om; + + /* Make a copy of om, returning -1 if not able to duplicate om */ + new_om = os_mbuf_dup(om); + if (!new_om) { + return -1; + } +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_extend.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_extend.md b/docs/os/core_os/mbuf/os_mbuf_extend.md index e69de29..86ff6a1 100644 --- a/docs/os/core_os/mbuf/os_mbuf_extend.md +++ b/docs/os/core_os/mbuf/os_mbuf_extend.md @@ -0,0 +1,45 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_extend</font> + +```no-highlight +void *os_mbuf_extend(struct os_mbuf *om, uint16_t len); +``` + +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. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf chain | +| len | Number of bytes to increase packet header | + +<br> + +#### Returned values + +Pointer to start of extended data. Caller is guaranteed that there are at least *len* bytes from this pointer to the end of the mbuf. + +Returns NULL if extension fails due to insufficient mbufs or *len* too large. +<br> + +#### Notes + +<br> + +#### Example + +```no-highlight + uint8_t *dptr; + struct os_mbuf *om; + struct my_data_struct my_data; + + /* Obtain enough room to add "my_data" to an mbuf chain */ + dptr = os_mbuf_extend(om, sizeof(struct my_data_struct)); + if (dptr) { + memcpy(dptr, &my_data, sizeof(struct my_data_struct)); + } +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_free.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_free.md b/docs/os/core_os/mbuf/os_mbuf_free.md index e69de29..33a966e 100644 --- a/docs/os/core_os/mbuf/os_mbuf_free.md +++ b/docs/os/core_os/mbuf/os_mbuf_free.md @@ -0,0 +1,43 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_free</font> + +```no-highlight +int os_mbuf_free(struct os_mbuf *om); +``` + +Free a single mbuf + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to single mbuf | + +<br> + +#### Returned values + +0: success +Any other value indicates error + +<br> + +#### Notes +The mbuf is freed to the pool pointed to by *om_omp* in the mbuf. If the pool pointer is NULL, no error is returned and the mbuf is not freed. + +Care should be taked when using this function as any mbufs chained to *om* will be lost as this function assumes no mbufs are chained to *om*. + +<br> + +#### Example + +```no-highlight + int rc; + struct os_mbuf *om; + + rc = os_mbuf_free(om); + assert(rc == 0); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_free_chain.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_free_chain.md b/docs/os/core_os/mbuf/os_mbuf_free_chain.md index e69de29..28f6198 100644 --- a/docs/os/core_os/mbuf/os_mbuf_free_chain.md +++ b/docs/os/core_os/mbuf/os_mbuf_free_chain.md @@ -0,0 +1,42 @@ +## <font color="#F2853F" style="font-size:24pt"> os_mbuf_free_chain</font> + +```no-highlight +int os_mbuf_free_chain(struct os_mbuf *om); +``` + +Frees a chain of mbufs + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf chain | + +<br> + +#### Returned values + +0: success +Any other value indicates error + +<br> + +#### Notes +Note that for each mbuf in the chain, `os_mbuf_free()` is called. + +<br> + +#### Example + +```no-highlight + int rc; + struct os_mbuf *om; + + /* Free mbuf chain */ + rc = os_mbuf_free_chain(om); + assert(rc == 0); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_get.md b/docs/os/core_os/mbuf/os_mbuf_get.md index e69de29..317e676 100644 --- a/docs/os/core_os/mbuf/os_mbuf_get.md +++ b/docs/os/core_os/mbuf/os_mbuf_get.md @@ -0,0 +1,43 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_get</font> + +```no-highlight +struct os_mbuf *os_mbuf_get(struct os_mbuf_pool *omp, uint16_t leadingspace) +``` + +Get an mbuf from the mbuf pool. The mbuf is allocated, and initialized prior to being returned. The *leadingspace* parameter allows the user to specify the amount of leading space in the allocated mbuf. + + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf pool from which to allocate mbuf | +| leadingspace | Amount of leading space in allocated mbuf. Request cannot exceed the mbuf data buffer size. | + +<br> + +#### Returned values + +Returns a pointer to the allocated mbuf or NULL if there are no mbufs available or *leadingspace* was too large. +<br> + +#### Notes +In most typical applications, the application developer does not need to call `os_mbuf_get()`; the other API will do this automatically. However, this API is provided for convenience as mbufs can also be a simple way to allocate temporary chunks of memory. + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om; + + /* Get a mbuf */ + om = os_mbuf_get(&g_mbuf_pool, 0); + if (om) { + /* we have allocated an mbuf from the pool */ + } +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md b/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md index e69de29..71a1b6b 100644 --- a/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md +++ b/docs/os/core_os/mbuf/os_mbuf_get_pkthdr.md @@ -0,0 +1,44 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_get_pkthdr</font> + +```no-highlight +struct os_mbuf *os_mbuf_get_pkthdr(struct os_mbuf_pool *omp, uint8_t pkthdr_len); +``` + +Allocates a packet header mbuf from the mbuf pool pointed to by *omp*. Adds a user header of length *pkthdr_len* to packet header mbuf. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf pool from which to allocate mbuf | +| pkthdr_len | The user header packet length to allocate for the packet header mbuf | + +<br> + +#### Returned values + +Returns a pointer to the allocated mbuf or NULL if there are no mbufs available or the user packet header was too large. + +<br> + +#### Notes +The packet header mbuf returned will have its data pointer incremented by the sizeof(struct os_mbuf_pkthdr) as well as the amount of user header data (i.e. *pkthdr_len*). In other words, the data pointer is offset from the start of the mbuf by: sizeof(struct os_mbuf) + sizeof(struct os_mbuf_pkthdr) + pkthdr_len. The `om_pkthdr_len` element in the allocated mbuf is set to: sizeof(struct os_mbuf_pkthdr) + pkthdr_len. + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om; + struct my_user_header my_hdr; + + /* Get a packet header mbuf with a user header in it */ + om = os_mbuf_get_pkthdr(&g_mbuf_pool, sizeof(struct my_user_header)); + if (om) { + /* Packet header mbuf was allocated */ + } +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_memcmp.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_memcmp.md b/docs/os/core_os/mbuf/os_mbuf_memcmp.md index e69de29..dab296f 100644 --- a/docs/os/core_os/mbuf/os_mbuf_memcmp.md +++ b/docs/os/core_os/mbuf/os_mbuf_memcmp.md @@ -0,0 +1,46 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_memcmp</font> + +```no-highlight +int os_mbuf_memcmp(const struct os_mbuf *om, int off, const void *data, int len) +``` + +Performs a memory compare of the specified region of an mbuf chain against a flat buffer. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf | +| off | Offset, in bytes, from start of mbuf to start of comparison | +| data | Pointer to flat data buffer to compare | +| len | Number of bytes to compare | + +<br> + +#### Returned values +A value of zero means the memory regions are identical; all other values represent either an error or a value returned from memcmp. + +<br> + +#### Notes +This function will compare bytes starting from *off* bytes from the start of the mbuf chain with a data buffer. + +<br> + +#### Example + +```no-highlight + int rc; + struct os_mbuf *om; + uint8_t my_data_buffer[32]; + + /* Get a packet header mbuf with a user header in it */ + rc = os_mbuf_memcmp(om, 0, my_data_buffer, 32); + if (!rc) { + /* "my_data_buffer" and the data from offset 0 in the mbuf chain are identical! */ + } +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_off.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_off.md b/docs/os/core_os/mbuf/os_mbuf_off.md index e69de29..6a114a1 100644 --- a/docs/os/core_os/mbuf/os_mbuf_off.md +++ b/docs/os/core_os/mbuf/os_mbuf_off.md @@ -0,0 +1,56 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_off</font> + +```no-highlight +struct os_mbuf *os_mbuf_off(struct os_mbuf *om, int off, int *out_off) +``` + +Given an offset in the packet (i.e. user data byte offset in the mbuf chain), return the mbuf and the offset in that mbuf where byte 'off' is located. Note that the offset is 'returned' in *out_off*. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf | +| off | Location in mbuf chain of desired byte offset | +| out_off | Pointer to storage for the relative offset of the absolute location in the returned mbuf | + +<br> + +#### Returned values +NULL if the offset is not within the mbuf chain or *om* points to NULL. + +<br> + +#### Notes +The user is allowed to call this function with the length of the mbuf chain but no greater. This allows the user to get the mbuf and offset (in that mbuf) where the next user data byte should be written. + +While this api is provided to the user, other API are expected to be used by the applciation developer (i.e. `os_mbuf_append()` or `os_mbuf_copyinto()`). +<br> + +#### Example + +```no-highlight + int relative_offset; + uint16_t pktlen; + struct os_mbuf *om; + struct os_mbuf *tmp; + + /* Append a new line character to end of mbuf data */ + pktlen = OS_MBUF_PKTLEN(om); + + relative_offset = 0; + tmp = os_mbuf_off(om, pktlen, &relative_offset); + if (tmp) { + /* Offset found. */ + tmp->om_data[relative_offset] = '\n'; + } else { + /* + * This mbuf does not contain enough bytes so this is an invalid offset. + * In other words, the mbuf is less than 62 bytes in length. + */ + } +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_pool_init.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_pool_init.md b/docs/os/core_os/mbuf/os_mbuf_pool_init.md index e69de29..896e028 100644 --- a/docs/os/core_os/mbuf/os_mbuf_pool_init.md +++ b/docs/os/core_os/mbuf/os_mbuf_pool_init.md @@ -0,0 +1,64 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_pool_init</font> + +```no-highlight +int os_mbuf_pool_init(struct os_mbuf_pool *omp, struct os_mempool *mp, uint16_t buf_len, + uint16_t nbufs) +``` + +Initialize a mbuf pool + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| omp | Pointer to mbuf pool to initialize | +| mp | Pointer to memory pool used by mbuf pool | +| buf_len | The size of the memory blocks in the memory pool used by the mbuf pool | +| nbufs | The number of mbufs in the pool | + +<br> + +#### Returned values +0 on success; all other values indicate an error. + +<br> + +#### Notes +The parameter *buf_len* is the total size of the memory block. This must accommodate the os_mbuf structure, the os_mbuf_pkthdr structure, any user headers plus the desired amount of user data. + +<br> + +#### Example + +```no-highlight +#define MBUF_PKTHDR_OVERHEAD sizeof(struct os_mbuf_pkthdr) + sizeof(struct user_hdr) +#define MBUF_MEMBLOCK_OVERHEAD sizeof(struct os_mbuf) + MBUF_PKTHDR_OVERHEAD + +#define MBUF_NUM_MBUFS (32) +#define MBUF_PAYLOAD_SIZE (64) +#define MBUF_BUF_SIZE OS_ALIGN(MBUF_PAYLOAD_SIZE, 4) +#define MBUF_MEMBLOCK_SIZE (MBUF_BUF_SIZE + MBUF_MEMBLOCK_OVERHEAD) +#define MBUF_MEMPOOL_SIZE OS_MEMPOOL_SIZE(MBUF_NUM_MBUFS, MBUF_MEMBLOCK_SIZE) + +struct os_mbuf_pool g_mbuf_pool; +struct os_mempool g_mbuf_mempool; +os_membuf_t g_mbuf_buffer[MBUF_MEMPOOL_SIZE]; + +void +create_mbuf_pool(void) +{ + int rc; + + rc = os_mempool_init(&g_mbuf_mempool, MBUF_NUM_MBUFS, + MBUF_MEMBLOCK_SIZE, &g_mbuf_buffer[0], "mbuf_pool"); + assert(rc == 0); + + rc = os_mbuf_pool_init(&g_mbuf_pool, &g_mbuf_mempool, MBUF_MEMBLOCK_SIZE, + MBUF_NUM_MBUFS); + assert(rc == 0); +} +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_prepend.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_prepend.md b/docs/os/core_os/mbuf/os_mbuf_prepend.md index e69de29..23b23ef 100644 --- a/docs/os/core_os/mbuf/os_mbuf_prepend.md +++ b/docs/os/core_os/mbuf/os_mbuf_prepend.md @@ -0,0 +1,50 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_prepend</font> + +```no-highlight +struct os_mbuf *os_mbuf_prepend(struct os_mbuf *om, int 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. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf | +| len | Length, in bytes, to prepend | + +<br> + +#### Returned values +Pointer to mbuf at head of chain; NULL if not enough mbufs were available to accommodate *len*. + +<br> + +#### Notes +If *om* is a packet header mbuf, the total length of the packet is adjusted by *len*. Note that the returned mbuf may not point to *om* if insufficient leading space was available in *om*. + +<br> + +#### Example + +```no-highlight + uint16_t pktlen; + struct os_mbuf *om; + struct os_mbuf *tmp; + + /* Get initial packet length before prepend */ + pktlen = OS_MBUF_PKTLEN(om); + + tmp = os_mbuf_prepend(om, 32); + if (!tmp) { + /* Not able to prepend. The chain pointed to by *om has been freed */ + return -1; + } + + /* The packet length should equal the original length plus what we prepended */ + assert((pktlen + 32) == OS_MBUF_PKTLEN(tmp)); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_mbuf_pullup.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_mbuf_pullup.md b/docs/os/core_os/mbuf/os_mbuf_pullup.md index e69de29..ba398dd 100644 --- a/docs/os/core_os/mbuf/os_mbuf_pullup.md +++ b/docs/os/core_os/mbuf/os_mbuf_pullup.md @@ -0,0 +1,50 @@ +## <font color="#F2853F" style="font-size:24pt">os_mbuf_pullup</font> + +```no-highlight +struct os_mbuf *os_mbuf_pullup(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. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| om | Pointer to mbuf | +| len | Length, in bytes, to pullup (make contiguous in mbuf) | + +<br> + +#### Returned values +Pointer to mbuf at head of chain; NULL if not enough mbufs were available to accommodate *len* or if the requested pullup size was too large. + +<br> + +#### Notes +Hopefully it is apparent to the user that you cannot pullup more bytes than the mbuf can accommodate. Pullup does not allocate more than one mbuf; the entire pullup length must be contained within a single mbuf. + +The mbuf that is being pulled up into does not need to be a packet header mbuf; it can be a normal mbuf. The user should note that the maximum pullup length does depend on the type of mbuf being pulled up into (a packet header or normal mbuf). + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om; + struct os_mbuf *tmp; + struct my_header_struct my_header; + + /* Make sure "my_header" is contiguous in the mbuf */ + tmp = os_mbuf_pullup(om, sizeof(my_header_struct)); + if (!tmp) { + /* Pullup failed. The chain pointed to by *om has been freed */ + return -1; + } + + /* copy data from mbuf into header structure */ + memcpy(&my_header, tmp->om_data, sizeof(struct my_header_struct)); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_msys_get.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_msys_get.md b/docs/os/core_os/mbuf/os_msys_get.md index e69de29..6257f53 100644 --- a/docs/os/core_os/mbuf/os_msys_get.md +++ b/docs/os/core_os/mbuf/os_msys_get.md @@ -0,0 +1,46 @@ +## <font color="#F2853F" style="font-size:24pt">os_msys_get</font> + +```no-highlight +struct os_mbuf *os_msys_get(uint16_t dsize, uint16_t leadingspace) +``` + +Retrieve a mbuf from the system mbuf pools with *leadingspace* bytes available in the mbuf. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| dsize | Minimum requested size of mbuf. Actual mbuf allocated may not accommodate *dsize* | +| leadingspace | Number of bytes for leading space in mbuf (space at start of mbuf) | + +<br> + +#### Returned values +Pointer to mbuf or NULL if no mbufs were available. + +<br> + +#### Notes +As described in the overview section, `os_msys_get()` may return a mbuf that is smaller than dsize, meaning that the mbuf user data buffer does not have enough contiguous space to hold *dsize* bytes. + +This API will not return a mbuf from a larger mbuf pool if the appropriate msys mbuf pool is empty. See the overview for more information. + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om; + + /* Allocate a mbuf with hopefully at least 100 bytes in its user data buffer */ + om = os_msys_get(100, 0); + if (!om) { + /* No mbufs available. */ + return -1; + } +} +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_msys_get_pkthdr.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_msys_get_pkthdr.md b/docs/os/core_os/mbuf/os_msys_get_pkthdr.md index e69de29..c747ecd 100644 --- a/docs/os/core_os/mbuf/os_msys_get_pkthdr.md +++ b/docs/os/core_os/mbuf/os_msys_get_pkthdr.md @@ -0,0 +1,48 @@ +## <font color="#F2853F" style="font-size:24pt">os_msys_get</font> + +```no-highlight +struct os_mbuf *os_msys_get_pkthdr(uint16_t dsize, uint16_t user_hdr_len) +``` + +Retrieve a packet header mbuf from the system mbuf pools with *user_hdr_len* bytes available for the user header in the mbuf. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| dsize | Minimum requested size of mbuf. Actual mbuf allocated may not accommodate *dsize* | +| user_hdr_len | Size, in of bytes, of user header in the mbuf | + +<br> + +#### Returned values +Pointer to mbuf or NULL if no mbufs were available. + +<br> + +#### Notes +The same notes apply to this API as to `os_msys_get()`. + +<br> + +#### Example + +```no-highlight + struct os_mbuf *om; + struct my_user_hdr_struct my_usr_hdr; + + /* + * Allocate a mbuf with hopefully at least 100 bytes in its user data buffer + * and that has a user header of size sizeof(struct my_user_hdr_struct) + */ + om = os_msys_get_pkthdr(100, sizeof(struct my_user_hdr_struct)); + if (!om) { + /* No mbufs available. */ + return -1; + } +} +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_msys_register.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_msys_register.md b/docs/os/core_os/mbuf/os_msys_register.md index e69de29..f30f3e7 100644 --- a/docs/os/core_os/mbuf/os_msys_register.md +++ b/docs/os/core_os/mbuf/os_msys_register.md @@ -0,0 +1,35 @@ +## <font color="#F2853F" style="font-size:24pt">os_msys_register</font> + +```no-highlight +int os_msys_register(struct os_mbuf_pool *new_pool) +``` + +Register a mbuf pool for use as a system mbuf pool. The pool should be initialized prior to registration. + +<br> + +#### Arguments + +| Arguments | Description | +|-----------|-------------| +| new_pool | Pointer to mbuf pool to add to system mbuf pools | + +<br> + +#### Returned values +0 on success; all other values indicate an error. + +<br> + +#### Notes + +<br> + +#### Example + +```no-highlight + rc = os_msys_register(&g_mbuf_pool); + assert(rc == 0); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/os_msys_reset.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/os_msys_reset.md b/docs/os/core_os/mbuf/os_msys_reset.md index e69de29..1ed5875 100644 --- a/docs/os/core_os/mbuf/os_msys_reset.md +++ b/docs/os/core_os/mbuf/os_msys_reset.md @@ -0,0 +1,33 @@ +## <font color="#F2853F" style="font-size:24pt">os_msys_reset</font> + +```no-highlight +void os_msys_reset(void) +``` + +Resets msys module. This de-registers all pools from msys but does nothing to the pools themselves (they still exist as mbuf pools). + +<br> + +#### Arguments + +None + +<br> + +#### Returned values + +None + +<br> + +#### Notes + +<br> + +#### Example + +```no-highlight + os_msys_reset(); +``` + +--------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/pics/mbuf_fig1.png ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/pics/mbuf_fig1.png b/docs/os/core_os/mbuf/pics/mbuf_fig1.png new file mode 100644 index 0000000..ba7ab0f Binary files /dev/null and b/docs/os/core_os/mbuf/pics/mbuf_fig1.png differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/pics/mbuf_fig2.png ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/pics/mbuf_fig2.png b/docs/os/core_os/mbuf/pics/mbuf_fig2.png new file mode 100644 index 0000000..68a9716 Binary files /dev/null and b/docs/os/core_os/mbuf/pics/mbuf_fig2.png differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/docs/os/core_os/mbuf/pics/mbuf_fig3.png ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mbuf/pics/mbuf_fig3.png b/docs/os/core_os/mbuf/pics/mbuf_fig3.png new file mode 100644 index 0000000..6d5ac5b Binary files /dev/null and b/docs/os/core_os/mbuf/pics/mbuf_fig3.png differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/fb6890bc/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index 39dd04a..c79f8c5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,6 +88,14 @@ pages: - Mbufs: - 'Overview': 'os/core_os/mbuf/mbuf.md' - 'Functions': + - 'OS_MBUF_PKTHDR': 'os/core_os/mbuf/OS_MBUF_PKTHDR.md' + - 'OS_MBUF_PKTHDR_TO_MBUF': 'os/core_os/mbuf/OS_MBUF_PKTHDR_TO_MBUF.md' + - 'OS_MBUF_PKTLEN': 'os/core_os/mbuf/OS_MBUF_PKTLEN.md' + - 'OS_MBUF_DATA': 'os/core_os/mbuf/OS_MBUF_DATA.md' + - 'OS_MBUF_USRHDR': 'os/core_os/mbuf/OS_MBUF_USRHDR.md' + - 'OS_MBUF_USRHDR_LEN': 'os/core_os/mbuf/OS_MBUF_USRHDR_LEN.md' + - 'OS_MBUF_LEADINGSPACE': 'os/core_os/mbuf/OS_MBUF_LEADINGSPACE.md' + - 'OS_MBUF_TRAILINGSPACE': 'os/core_os/mbuf/OS_MBUF_TRAILINGSPACE.md' - 'os_mbuf_adj': 'os/core_os/mbuf/os_mbuf_adj.md' - 'os_mbuf_append': 'os/core_os/mbuf/os_mbuf_append.md' - 'os_mbuf_concat': 'os/core_os/mbuf/os_mbuf_concat.md' @@ -104,9 +112,6 @@ pages: - 'os_mbuf_pool_init': 'os/core_os/mbuf/os_mbuf_pool_init.md' - 'os_mbuf_prepend': 'os/core_os/mbuf/os_mbuf_prepend.md' - 'os_mbuf_pullup': 'os/core_os/mbuf/os_mbuf_pullup.md' - - 'os_mqueue_get': 'os/core_os/mbuf/os_mqueue_get.md' - - 'os_mqueue_init': 'os/core_os/mbuf/os_mqueue_init.md' - - 'os_mqueue_put': 'os/core_os/mbuf/os_mqueue_put.md' - 'os_msys_get': 'os/core_os/mbuf/os_msys_get.md' - 'os_msys_get_pkthdr': 'os/core_os/mbuf/os_msys_get_pkthdr.md' - 'os_msys_register': 'os/core_os/mbuf/os_msys_register.md'
