From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id D57D7A04A4; Mon, 25 May 2020 23:24:29 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 054ED1D9C6; Mon, 25 May 2020 23:24:29 +0200 (CEST) Received: from new4-smtp.messagingengine.com (new4-smtp.messagingengine.com [66.111.4.230]) by dpdk.org (Postfix) with ESMTP id D5F691D998 for ; Mon, 25 May 2020 23:24:26 +0200 (CEST) Received: from compute7.internal (compute7.nyi.internal [10.202.2.47]) by mailnew.nyi.internal (Postfix) with ESMTP id 267D758262F; Mon, 25 May 2020 17:24:26 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute7.internal (MEProxy); Mon, 25 May 2020 17:24:26 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; s=fm1; bh=CiMBG2IcsQaN0/Opx96hXT50pu skgfAX9TeDvzCOfFA=; b=pinGhhkv+e158Ef/YRSb8Z1pkjMXymGr60pbiUsRwf 3Uj6qKWP9RxQ444G6/vJNMoOLQfbSfooUmcKnPJrIwHeoy5aOGrhUixXbiC7kMGL 8o37amqPzqcLLY0pqAYfMoKdgsWPlVUJymCl+Wu1n46UOIej3toQlgA8dEwd/QZK HSMpCIUX7hZ3pUH8BBus1d2BjoixvwN4v3R/jsu1ak9NoFWTBTkA9ODNq1aii4Ub zvlThkONIVPoBB0R06k4a4fnTLMoH8z8LffRKol7VsKKtI3zzBnndGjw6NyGmREB 8cmXWZ9wO4ARvvnwvLEbhCeL+C1ZmqqC5tYLKzLTZ/tA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:date:from :message-id:mime-version:subject:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm2; bh=CiMBG2IcsQaN0/Opx 96hXT50puskgfAX9TeDvzCOfFA=; b=lIrrZr2cKieej3+I87PHLi+ae4UPGH3Qo GG2sRy5VRe+9y4Uj1BTKW7SDGbltyEvHvKZAYoy1CVgptn/3pcqfLAyUkR1oKBZB wsLiz0OlL1KMAKqvWB4Jv7ppcLuYCoJSm7mavlj2QaknZIVvX+OGXHo76HfaP/ZZ s5NzegWiaezbqQBBiORz23CbvM3Dvk4MLiWg7Rs1DRzGbzyHUuVUDRACqxR2le3r 2V3nABZdruc9MwKGYbCXiJ0nken2pvhI6yV7Jl++YWC6IVDvjr/w7fnob8W3GiWq zfWa+ixVKSqplj45B4SLQ2mF3KGkiSAD6VVsy4px8sYTspYvdcJzw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduhedruddvtddgudehlecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmd enucfjughrpefhvffufffkofgggfestdekredtredttdenucfhrhhomhepvfhhohhmrghs ucfoohhnjhgrlhhonhcuoehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtqeenucggtf frrghtthgvrhhnpeeujefhlefffedvvdejleegleeiteeitdevjeefvdeuieeuhedtiefh hefhvefgteenucffohhmrghinhepughpughkrdhorhhgnecukfhppeejjedrudefgedrvd dtfedrudekgeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhr ohhmpehthhhomhgrshesmhhonhhjrghlohhnrdhnvght X-ME-Proxy: Received: from xps.monjalon.net (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id 4F40A306657A; Mon, 25 May 2020 17:24:24 -0400 (EDT) From: Thomas Monjalon To: dev@dpdk.org Cc: david.marchand@redhat.com, olivier.matz@6wind.com, jerinj@marvell.com, ndabilpuram@marvell.com, kkanas@marvell.com, arybchenko@solarflare.com, ferruh.yigit@intel.com, bruce.richardson@intel.com, John McNamara , Marko Kovacevic Date: Mon, 25 May 2020 23:24:15 +0200 Message-Id: <20200525212415.3173817-1-thomas@monjalon.net> X-Mailer: git-send-email 2.26.2 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH] mbuf: document rule for new fields and flags X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Since dynamic fields and flags were added in 19.11, the idea was to use them for new features, not only PMD-specific. The rule is made more explicit in doxygen, in the mbuf guide, and in the contribution design guidelines. For more information about the original design, see the presentation https://www.dpdk.org/wp-content/uploads/sites/35/2019/10/DynamicMbuf.pdf Signed-off-by: Thomas Monjalon --- doc/guides/contributing/design.rst | 13 +++++++++++++ doc/guides/prog_guide/mbuf_lib.rst | 23 +++++++++++++++++++++++ lib/librte_mbuf/rte_mbuf_core.h | 2 ++ 3 files changed, 38 insertions(+) diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst index d3dd694b65..508115d5bd 100644 --- a/doc/guides/contributing/design.rst +++ b/doc/guides/contributing/design.rst @@ -57,6 +57,19 @@ The following config options can be used: * ``CONFIG_RTE_EXEC_ENV`` is a string that contains the name of the executive environment. * ``CONFIG_RTE_EXEC_ENV_FREEBSD`` or ``CONFIG_RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment. +Mbuf features +------------- + +The ``rte_mbuf`` structure must be kept small (128 bytes). + +In order to add new features without wasting buffer space for unused features, +some fields and flags can be registered dynamically in a shared area. +The "dynamic" mbuf area is the default choice for the new features. + +The "dynamic" area is eating the remaining space in mbuf, +and some existing "static" fields may need to become "dynamic". + + Library Statistics ------------------ diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index 0d3223b081..c3dbfb9221 100644 --- a/doc/guides/prog_guide/mbuf_lib.rst +++ b/doc/guides/prog_guide/mbuf_lib.rst @@ -207,6 +207,29 @@ The list of flags and their precise meaning is described in the mbuf API documentation (rte_mbuf.h). Also refer to the testpmd source code (specifically the csumonly.c file) for details. +Dynamic fields and flags +~~~~~~~~~~~~~~~~~~~~~~~~ + +The size of the mbuf is constrained and limited; +while the amount of metadata to save for each packet is quite unlimited. +The most basic networking information already find their place +in the existing mbuf fields and flags. + +If new features need to be added, the new fields and flags should fit +in the "dynamic space", by registering some room in the mbuf structure: + +dynamic field + named area in the mbuf structure, + with a given size (at least 1 byte) and alignment constraint. + +dynamic flag + named bit in the mbuf structure, + stored in the field ``ol_flags``. + +The dynamic fields and flags are managed with the functions ``rte_mbuf_dyn*``. + +It is not possible to unregister fields or flags. + .. _direct_indirect_buffer: Direct and Indirect Buffers diff --git a/lib/librte_mbuf/rte_mbuf_core.h b/lib/librte_mbuf/rte_mbuf_core.h index b9a59c879c..22be41e520 100644 --- a/lib/librte_mbuf/rte_mbuf_core.h +++ b/lib/librte_mbuf/rte_mbuf_core.h @@ -12,6 +12,8 @@ * packet offload flags and some related macros. * For majority of DPDK entities, it is not recommended to include * this file directly, use include instead. + * + * New fields and flags should fit in the "dynamic space". */ #include -- 2.26.2