doc: update mbuf section of programmers guide

In Release 1.8, the mbuf structure was significantly reworked to add
extra information, leading to the structure being split across two
cache lines, and the data pointer being replaced by an offset. The
description of the library in the programmer's guide document needs
to be updated to take account of these changes.

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Bernard Iremonger <bernard.iremonger@intel.com>

diff --git a/doc/guides/prog_guide/img/mbuf1.svg b/doc/guides/prog_guide/img/mbuf1.svg
index 0b8ff00..5bd84d1 100644 (file)
--- a/doc/guides/prog_guide/img/mbuf1.svg
+++ b/doc/guides/prog_guide/img/mbuf1.svg
@@ -2,7 +2,9 @@
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
 
 <!--
-# Copyright (c) <2010>, Intel Corporation
+# BSD LICENSE
+#
+# Copyright (c) <2010 - 2014>, Intel Corporation
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -327,16 +329,16 @@
      borderopacity="1.0"
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
-     inkscape:zoom="2.8"
-     inkscape:cx="424.95386"
-     inkscape:cy="143.63151"
+     inkscape:zoom="2.8231676"
+     inkscape:cx="315.95715"
+     inkscape:cy="144.17143"
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      showgrid="false"
-     inkscape:window-width="1650"
-     inkscape:window-height="1059"
-     inkscape:window-x="177"
-     inkscape:window-y="111"
+     inkscape:window-width="1910"
+     inkscape:window-height="1170"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
      inkscape:window-maximized="0"
      fit-margin-top="0.1"
      fit-margin-left="0.1"
@@ -416,17 +418,17 @@
     <text
        xml:space="preserve"
        style="font-size:15.22520161px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="452.7626"
-       y="374.68066"
+       x="468.47687"
+       y="376.4664"
        id="text2912"
        inkscape:export-filename="/home/matz/barracuda/rapports/mbuf-api-v2-images/octeon_multi.png"
        inkscape:export-xdpi="112"
        inkscape:export-ydpi="112"><tspan
          sodipodi:role="line"
-         x="452.7626"
-         y="374.68066"
+         x="468.47687"
+         y="376.4664"
          id="tspan2916"
-         style="font-weight:bold">rte_mbuf (type is pkt)</tspan></text>
+         style="font-weight:bold">struct rte_mbuf </tspan></text>
     <path
        style="fill:none;stroke:#000000;stroke-width:1.26900005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
        d="M 270.40246,239.43649 C 273.9494,287.74619 176.1143,278.684 176.1143,278.684"
@@ -491,14 +493,10 @@
        x="249.28572"
        y="119.50503"
        id="text5219"><tspan
-         sodipodi:role="line"
-         id="tspan5221"
-         x="249.28572"
-         y="119.50503">rte_pktmbuf_mtod(m)</tspan><tspan
          sodipodi:role="line"
          x="249.28572"
-         y="132.00504"
-         id="tspan5223">or m-&gt;pkt.data</tspan></text>
+         y="119.50503"
+         id="tspan5223">rte_pktmbuf_mtod(m)</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
@@ -516,13 +514,13 @@
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="82.14286"
-       y="293.07645"
+       x="59.842155"
+       y="282.37683"
        id="text5254"><tspan
          sodipodi:role="line"
          id="tspan5256"
-         x="82.14286"
-         y="293.07645">m-&gt;pkt.next = NULL</tspan></text>
+         x="59.842155"
+         y="282.37683">m-&gt;pkt.next = NULL</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
@@ -568,11 +566,11 @@
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="520.37152"
+       x="525.0144"
        y="231.04784"
        id="text5258-1-5"><tspan
          sodipodi:role="line"
-         x="520.37152"
+         x="525.0144"
          y="231.04784"
          id="tspan5262-6-4">tailroom</tspan></text>
     <path

diff --git a/doc/guides/prog_guide/img/mbuf2.svg b/doc/guides/prog_guide/img/mbuf2.svg
index 49553be..347b9b1 100644 (file)
--- a/doc/guides/prog_guide/img/mbuf2.svg
+++ b/doc/guides/prog_guide/img/mbuf2.svg
@@ -2,7 +2,9 @@
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
 
 <!--
-# Copyright (c) <2010>, Intel Corporation
+# BSD LICENSE
+#
+# Copyright (c) <2010 - 2014>, Intel Corporation
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -48,7 +50,7 @@
    height="288.34286"
    id="svg3868"
    version="1.1"
-   inkscape:version="0.48.4 r9939"
+   inkscape:version="0.48.5 r10040"
    sodipodi:docname="mbuf2.svg"
    inkscape:export-filename="/home/matz/rapports/doc/intel/architecture_docs/mbuf2.png"
    inkscape:export-xdpi="200"
@@ -879,17 +881,17 @@
      borderopacity="1.0"
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
-     inkscape:zoom="1.4"
-     inkscape:cx="349.23531"
-     inkscape:cy="97.526166"
+     inkscape:zoom="1.979899"
+     inkscape:cx="335.62533"
+     inkscape:cy="102.43492"
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      showgrid="false"
-     inkscape:window-width="1650"
-     inkscape:window-height="1059"
-     inkscape:window-x="100"
-     inkscape:window-y="17"
-     inkscape:window-maximized="0"
+     inkscape:window-width="1920"
+     inkscape:window-height="1017"
+     inkscape:window-x="1592"
+     inkscape:window-y="285"
+     inkscape:window-maximized="1"
      fit-margin-top="0.1"
      fit-margin-left="0.1"
      fit-margin-right="0.1"
@@ -1058,17 +1060,17 @@
     <text
        xml:space="preserve"
        style="font-size:15.22520161px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="331.85513"
-       y="704.97418"
+       x="424.78918"
+       y="702.44879"
        id="text2912"
        inkscape:export-filename="/home/matz/barracuda/rapports/mbuf-api-v2-images/octeon_multi.png"
        inkscape:export-xdpi="112"
        inkscape:export-ydpi="112"><tspan
          sodipodi:role="line"
-         x="331.85513"
-         y="704.97418"
+         x="424.78918"
+         y="702.44879"
          id="tspan2916"
-         style="font-weight:bold">multi-segmented rte_mbuf (type is pkt)</tspan></text>
+         style="font-weight:bold">multi-segmented rte_mbuf</tspan></text>
     <path
        style="fill:none;stroke:#000000;stroke-width:1.26900005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-end:url(#Arrow1Mend)"
        d="m 119.23004,564.01527 c 101.10943,109.21871 189.23315,8.60651 189.23315,8.60651"
@@ -1168,31 +1170,28 @@
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="78.288223"
-       y="493.72507"
+       x="78.793297"
+       y="498.27075"
        id="text5219-6"><tspan
          sodipodi:role="line"
-         id="tspan5221-8"
-         x="78.288223"
-         y="493.72507">rte_pktmbuf_mtod(m)</tspan><tspan
-         sodipodi:role="line"
-         x="78.288223"
-         y="506.22507"
-         id="tspan5223-9">or m-&gt;pkt.data</tspan></text>
+         x="78.793297"
+         y="498.27075"
+         id="tspan5223-9">rte_pktmbuf_mtod(m)</tspan></text>
     <text
        xml:space="preserve"
-       style="font-size:10px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
-       x="311.4537"
-       y="447.16037"
-       id="text5258-2"><tspan
+       style="font-size:10.48159599px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans"
+       x="233.53358"
+       y="470.28363"
+       id="text5258-2"
+       transform="scale(1.0481596,0.95405318)"><tspan
          sodipodi:role="line"
-         x="311.4537"
-         y="447.16037"
+         x="233.53358"
+         y="470.28363"
          id="tspan5262-64">rte_pktmbuf_pktlen(m) = rte_pktmbuf_datalen(m) +</tspan><tspan
          sodipodi:role="line"
-         x="311.4537"
-         y="459.66037"
-         id="tspan6985">rte_pktmbuf_datalen(mseg2) + rte_pktmbuf_datalen(mseg3)</tspan></text>
+         x="233.53358"
+         y="483.38562"
+         id="tspan6985">            rte_pktmbuf_datalen(mseg2) + rte_pktmbuf_datalen(mseg3)</tspan></text>
     <path
        style="fill:none;stroke:#000000;stroke-width:1.26900005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#Arrow1Mstart);marker-end:url(#Arrow1Mend)"
        d="m 173.97266,470.21933 c 141.42583,0 391.36979,0 450.62611,0"

diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst
index 75b1c5e..3d59e96 100644 (file)
--- a/doc/guides/prog_guide/mbuf_lib.rst
+++ b/doc/guides/prog_guide/mbuf_lib.rst
@@ -37,10 +37,12 @@ The mbuf library provides the ability to allocate and free buffers (mbufs)
 that may be used by the DPDK application to store message buffers.
 The message buffers are stored in a mempool, using the :ref:`Mempool Library <Mempool_Library>`.
 
-A rte_mbuf struct can carry network packet buffers (type is RTE_MBUF_PKT)
-or generic control buffers (type is RTE_MBUF_CTRL).
+A rte_mbuf struct can carry network packet buffers
+or generic control buffers (indicated by the CTRL_MBUF_FLAG).
 This can be extended to other types.
-The rte_mbuf is kept as small as possible (one cache line if possible).
+The rte_mbuf header structure is kept as small as possible and currently uses
+just two cache lines, with the most frequently used fields being on the first
+of the two cache lines.
 
 Design of Packet Buffers
 ------------------------
@@ -57,17 +59,17 @@ the complete separation of the allocation of metadata structures from the alloca
 
 The first method was chosen for the DPDK.
 The metadata contains control information such as message type, length,
-pointer to the start of the data and a pointer for additional mbuf structures allowing buffer chaining.
+offset to the start of the data and a pointer for additional mbuf structures allowing buffer chaining.
 
 Message buffers that are used to carry network packets can handle buffer chaining
 where multiple buffers are required to hold the complete packet.
-This is the case for jumbo frames that are composed of many mbufs linked together through their pkt.next field.
+This is the case for jumbo frames that are composed of many mbufs linked together through their next field.
 
 For a newly allocated mbuf, the area at which the data begins in the message buffer is
 RTE_PKTMBUF_HEADROOM bytes after the beginning of the buffer, which is cache aligned.
 Message buffers may be used to carry control information, packets, events,
 and so on between different entities in the system.
-Message buffers may also use their data pointers to point to other message buffer data sections or other structures.
+Message buffers may also use their buffer pointers to point to other message buffer data sections or other structures.
 
 Figure 8 and Figure 9 show some of these scenarios.
 
@@ -109,9 +111,8 @@ Allocating and Freeing mbufs
 ----------------------------
 
 Allocating a new mbuf requires the user to specify the mempool from which the mbuf should be taken.
-For a packet mbuf, it contains one segment, with a length of 0.
-The pointer to data is initialized to have some bytes of headroom in the buffer (RTE_PKTMBUF_HEADROOM).
-For a control mbuf, it is initialized with data pointing to the beginning of the buffer and a length of zero.
+For any newly-allocated mbuf, it contains one segment, with a length of 0.
+The offset to data is initialized to have some bytes of headroom in the buffer (RTE_PKTMBUF_HEADROOM).
 
 Freeing a mbuf means returning it into its original mempool.
 The content of an mbuf is not modified when it is stored in a pool (as a free mbuf).
@@ -151,7 +152,8 @@ Direct and Indirect Buffers
 ---------------------------
 
 A direct buffer is a buffer that is completely separate and self-contained.
-An indirect buffer behaves like a direct buffer but for the fact that the data pointer it contains points to data in another direct buffer.
+An indirect buffer behaves like a direct buffer but for the fact that the buffer pointer and
+data offset in it refer to data in another direct buffer.
 This is useful in situations where packets need to be duplicated or fragmented,
 since indirect buffers provide the means to reuse the same packet data across multiple buffers.