[dpdk-dev] [PATCH v3] doc: add graphic showing layout of mbuf struct

[Jerin Jacob]

On Thu, Oct 17, 2019 at 9:28 PM Olivier Matz <olivier.matz at 6wind.com> wrote:
>
> Hi,
>
> On Tue, Aug 27, 2019 at 10:02:30AM +0100, A.McLoughlin wrote:
> > This patch adds a graphical overview of the rte_mbuf struct, showing where
> > each value is stored within the struct.
> >
> > Signed-off-by: A.McLoughlin <aideen.mcloughlin at intel.com>
> > ---
> > v1 -> v2:
> > * changed uint16_t refcnt(+atomic) to uint16_t refcnt
> > v2 -> v3:
> > * added layout of extrenally stored struct rte_mbuf sched sched
> > * added struct names for named structs
> > * made variable names bold for differenciation from types
> > * minor styling changes
> > * specified that graphic represents layout on 64B machine
> > ---
> >  doc/guides/prog_guide/img/mbuf_graphic.svg | 6962 ++++++++++++++++++++
> >  doc/guides/prog_guide/mbuf_lib.rst         |   12 +
> >  2 files changed, 6974 insertions(+)
> >  create mode 100644 doc/guides/prog_guide/img/mbuf_graphic.svg
>
> The diagram is nice, however we have to be careful because it
> has to be kept sync with the code. I tried to edit the svg with
> inkscape, and it seems the text is described as vector shapes,
> which make the diagram impossible to update.
>
> Couldn't it be replaced by the output of pahole? Or better, just explain
> how to generate it in the documentation? The user can then be sure that

+1 for explaining how to generate it in the documentation as pahole
output varies for the 128B cache line machine.


> the information is up to date, matches its architecture, and can also
> check structures other than mbuf.
>
> Example of pahole output for mbuf:
>
> struct rte_mbuf {
>         MARKER                     cacheline0;           /*     0     0 */
>         void *                     buf_addr;             /*     0     8 */
>         union {
>                 rte_iova_t         buf_iova;             /*     8     8 */
>                 rte_iova_t         buf_physaddr;         /*     8     8 */
>         };                                               /*     8     8 */
>         MARKER64                   rearm_data;           /*    16     0 */
>         uint16_t                   data_off;             /*    16     2 */
>         union {
>                 rte_atomic16_t     refcnt_atomic;        /*    18     2 */
>                 uint16_t           refcnt;               /*    18     2 */
>         };                                               /*    18     2 */
>         uint16_t                   nb_segs;              /*    20     2 */
>         uint16_t                   port;                 /*    22     2 */
>         uint64_t                   ol_flags;             /*    24     8 */
>         MARKER                     rx_descriptor_fields1; /*    32     0 */
>         union {
>                 uint32_t           packet_type;          /*    32     4 */
>                 struct {
>                         uint32_t   l2_type:4;            /*    32:28  4 */
>                         uint32_t   l3_type:4;            /*    32:24  4 */
>                         uint32_t   l4_type:4;            /*    32:20  4 */
>                         uint32_t   tun_type:4;           /*    32:16  4 */
>
>                         /* Bitfield combined with next fields */
>
>                         union {
>                                 uint8_t inner_esp_next_proto; /*    34     1 */
>                                 struct {
>                                         uint8_t inner_l2_type:4; /*    34: 4  1 */
>                                         uint8_t inner_l3_type:4; /*    34: 0  1 */
>                                 };                       /*    34     1 */
>                         };                               /*    34     1 */
>
>                         /* Bitfield combined with previous fields */
>
>                         uint32_t   inner_l4_type:4;      /*    32: 4  4 */
>                 };                                       /*    32     4 */
>         };                                               /*    32     4 */
>         uint32_t                   pkt_len;              /*    36     4 */
>         uint16_t                   data_len;             /*    40     2 */
>         uint16_t                   vlan_tci;             /*    42     2 */
>         union {
>                 union {
>                         uint32_t   rss;                  /*    44     4 */
>                         struct {
>                                 union {
>                                         struct {
>                                                 uint16_t       hash; /*    44     2 */
>                                                 uint16_t       id; /*    46     2 */
>                                         };               /*    44     4 */
>                                         uint32_t lo;     /*    44     4 */
>                                 };                       /*    44     4 */
>                                 uint32_t hi;             /*    48     4 */
>                         } fdir;                          /*    44     8 */
>                         struct {
>                                 uint32_t lo;             /*    44     4 */
>                                 uint32_t hi;             /*    48     4 */
>                         } sched;                         /*    44     8 */
>                         uint32_t   usr;                  /*    44     4 */
>                 } hash;                                  /*    44     8 */
>                 struct {
>                         uint32_t   tx_metadata;          /*    44     4 */
>                         uint32_t   reserved;             /*    48     4 */
>                 };                                       /*    44     8 */
>         };                                               /*    44     8 */
>         uint16_t                   vlan_tci_outer;       /*    52     2 */
>         uint16_t                   buf_len;              /*    54     2 */
>         uint64_t                   timestamp;            /*    56     8 */
>         /* --- cacheline 1 boundary (64 bytes) --- */
>         MARKER                     cacheline1;           /*    64     0 */
>         union {
>                 void *             userdata;             /*    64     8 */
>                 uint64_t           udata64;              /*    64     8 */
>         };                                               /*    64     8 */
>         struct rte_mempool *       pool;                 /*    72     8 */
>         struct rte_mbuf *          next;                 /*    80     8 */
>         union {
>                 uint64_t           tx_offload;           /*    88     8 */
>                 struct {
>                         uint64_t   l2_len:7;             /*    88:57  8 */
>                         uint64_t   l3_len:9;             /*    88:48  8 */
>                         uint64_t   l4_len:8;             /*    88:40  8 */
>                         uint64_t   tso_segsz:16;         /*    88:24  8 */
>                         uint64_t   outer_l3_len:9;       /*    88:15  8 */
>                         uint64_t   outer_l2_len:7;       /*    88: 8  8 */
>                 };                                       /*    88     8 */
>         };                                               /*    88     8 */
>         uint16_t                   priv_size;            /*    96     2 */
>         uint16_t                   timesync;             /*    98     2 */
>         uint32_t                   seqn;                 /*   100     4 */
>         struct rte_mbuf_ext_shared_info * shinfo;        /*   104     8 */
>
>         /* size: 128, cachelines: 2, members: 27 */
>         /* padding: 16 */
> };
>
>
> Olivier