api: pktio: change Tx checksum insertion API semantics

Existing API spec requires application to just provide L3 offset and
and L4 offset and expects platform either in SW or HW parse the packet in
Tx and identify L3 and L4 protocols and then generate checksum if
requested. Since not all platforms have support for packet parsing in HW
in Tx, they depend on software to provide L3 and L4 types in addition to
existing L3 and L4 protocol offsets. Doing the parsing in platform SW for
such cases brings down performance and is counter productive.
Since similar to L3 and L4 offsets, even L3 and L4 proto types are provided
by HW parser in packet ingress, making use of the same information in Tx is
benefitial for performance.

So this patch changes Tx checksum insertion semantics by mandating that
application should have valid packet metadata for L3 and L4 type
along with existing requirement of L3 and L4 offsets, and platform will
make use of the same information for checksum calculation and insertion.

Signed-off-by: Nithin Dabilpuram <ndabilpuram@marvell.com>
Reviewed-by: Petri Savolainen <petri.savolainen@nokia.com>
Reviewed-by: Janne Peltonen <janne.peltonen@nokia.com>

2 files changed, 22 insertions, 8 deletions

diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
index b2dcf28f2..924658e34 100644
--- a/include/odp/api/spec/packet.h
+++ b/include/odp/api/spec/packet.h
@@ -1830,9 +1830,14 @@ odp_packet_chksum_status_t odp_packet_l4_chksum_status(odp_packet_t pkt);
  * inserted if the packet is output through a pktio that does not have
  * the relevant checksum insertion enabled.
  *
+ * L3 type and L3 offset in packet metadata should provide valid protocol
+ * and header offset for checksum insertion purposes.
+ *
  * @param pkt     Packet handle
  * @param insert  0: do not insert L3 checksum
  *                1: insert L3 checksum
+ *
+ * @see odp_packet_l3_offset(), odp_packet_has_ipv4(), odp_packet_has_ipv6()
  */
 void odp_packet_l3_chksum_insert(odp_packet_t pkt, int insert);
 
@@ -1847,9 +1852,16 @@ void odp_packet_l3_chksum_insert(odp_packet_t pkt, int insert);
  * inserted if the packet is output through a pktio that does not have
  * the relevant checksum insertion enabled.
  *
+ * L3 type, L4 type, L3 offset and L4 offset in packet metadata should provide
+ * valid protocols and header offsets for checksum insertion purposes.
+ *
  * @param pkt     Packet handle
  * @param insert  0: do not insert L4 checksum
  *                1: insert L4 checksum
+ *
+ * @see odp_packet_l3_offset(), odp_packet_has_ipv4(), odp_packet_has_ipv6()
+ * @see odp_packet_l4_offset(), odp_packet_has_tcp(), odp_packet_has_udp()
+ * @see odp_packet_has_sctp()
  */
 void odp_packet_l4_chksum_insert(odp_packet_t pkt, int insert);
 
diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h
index c4dd26a51..a361e8452 100644
--- a/include/odp/api/spec/packet_io.h
+++ b/include/odp/api/spec/packet_io.h
@@ -365,14 +365,16 @@ typedef union odp_pktin_config_opt_t {
  * These defaults may be overridden on per packet basis using e.g.
  * odp_packet_l4_chksum_insert().
  *
- * For correct operation, packet metadata must provide valid offsets for the
- * appropriate protocols. For example, UDP checksum calculation needs both L3
- * and L4 offsets (to access IP and UDP headers). When application
- * (e.g. a switch) does not modify L3/L4 data and thus checksum does not need
- * to be updated, checksum insertion should be disabled for optimal performance.
- *
- * Packet flags (odp_packet_has_*()) are ignored for the purpose of checksum
- * insertion in packet output.
+ * For correct operation, packet metadata must provide valid offsets and type
+ * flags for the appropriate layer 3 and layer 4 protocols.  L3 and L4 offsets
+ * can be updated with odp_packet_l3_offset_set() and odp_packet_l4_offset_set()
+ * calls. L3 and L4 type flags can be updated using odp_packet_has_*_set() calls
+ * For example, UDP checksum calculation needs both L3 and L4 types (IP and UDP) and
+ * L3 and L4 offsets (to access IP and UDP headers), while IP checksum
+ * calculation only needs L3 type (IP) and L3 offset (to access IP header).
+ * When application (e.g. a switch) does not modify L3/L4 data and thus checksum
+ * does not need to be updated, checksum insertion should be disabled for optimal
+ * performance.
  *
  * UDP, TCP and SCTP checksum insertion must not be requested for IP fragments.
  * Use checksum override function (odp_packet_l4_chksum_insert()) to disable