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

[Olivier Matz]

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
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