Re: [PATCH v3 1/3] ethdev: add description for KEEP CRC offload

[Stephen Hemminger <stephen@networkplumber.org>]

On Fri, 19 Jul 2024 17:04:13 +0800
Jie Hai <haijie1@huawei.com> wrote:

> From: Dengdui Huang <huangdengdui@huawei.com>
> 
> The data exceeds the pkt_len in mbuf is inavailable for user.
> When KEEP CRC offload is enabled, CRC field length should be
> included in the pkt_len in mbuf. However, almost of drivers
> supported KEEP CRC feature didn't add the CRC data length to
> pkt_len. So it is very necessary to add comments for this.
> 
> Fixes: 70815c9ecadd ("ethdev: add new offload flag to keep CRC")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Dengdui Huang <huangdengdui@huawei.com>
> Acked-by: Morten Brørup <mb@smartsharesystems.com>
> Acked-by: Huisong Li <lihuisong@huawei.com>
> Acked-by: Jie Hai <haijie1@huawei.com>
> ---
>  lib/ethdev/rte_ethdev.h | 6 ++++++
>  1 file changed, 6 insertions(+)
> 

If you put the information in doc, users would see it.
Something like this:

diff --git a/doc/guides/nics/features.rst b/doc/guides/nics/features.rst
index 0508f118fe..63b0331b06 100644
--- a/doc/guides/nics/features.rst
+++ b/doc/guides/nics/features.rst
@@ -470,8 +470,9 @@ protocol operations. See security library and PMD documentation for more details
 CRC offload
 -----------
 
-Supports CRC stripping by hardware.
-A PMD assumed to support CRC stripping by default. PMD should advertise if it supports keeping CRC.
+Supports including the CRC in the received packet.
+A PMD is assumed to support CRC stripping by default,
+PMD should only advertise if it supports keeping CRC.
 
 * **[uses] rte_eth_rxconf,rte_eth_rxmode**: ``offloads:RTE_ETH_RX_OFFLOAD_KEEP_CRC``.
 
diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst
index 4ad2a21f3f..bea9111ba4 100644
--- a/doc/guides/prog_guide/mbuf_lib.rst
+++ b/doc/guides/prog_guide/mbuf_lib.rst
@@ -207,6 +207,18 @@ 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.
 
+CRC offload
+~~~~~~~~~~~
+
+Normally the Ethernet Cyclic Redundancy Check (CRC) is *not* included in the mbuf.
+Some Poll Mode Driver's support keeping the received CRC in the mbuf.
+If a packet is received with keep CRC offload setting:
+- the CRC is in included in the mbuf pkt_len and data_len
+- the CRC is present but not checked
+- the mbuf should not be directly transmitted or the received CRC will be include
+  in the transmit
+
+
 Dynamic fields and flags
 ~~~~~~~~~~~~~~~~~~~~~~~~