[API-NEXT,v1,3/3] api: packet_io: refine rules for checksum calculation

Message ID 1504702806-13800-4-git-send-email-odpbot@yandex.ru
State New
Headers show
Series
  • [API-NEXT,v1,1/3] api: packet_io: refine packet format on output
Related show

Commit Message

Github ODP bot Sept. 6, 2017, 1 p.m.
From: Petri Savolainen <petri.savolainen@linaro.org>


An implementation must be able to check checksum for normal
IP packets. It's implementation defined if options or extension
headers are supported.

Parsing configuration must match the layers of checksum check
configuration.

Checksum insertion on packet output can expect well formed packet
headers from the application. Checksum calculation ignores possible
extra data in the packet.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>

---
/** Email created from pull request 167 (psavol:next-pkt-checksum)
 ** https://github.com/Linaro/odp/pull/167
 ** Patch: https://github.com/Linaro/odp/pull/167.patch
 ** Base sha: 4eae04e80a634c17ac276bb06bce468cbe28cde0
 ** Merge commit sha: fb1526ce83d639bbbd28205b31145e0e15153508
 **/
 include/odp/api/spec/ipsec.h     | 14 +++++++----
 include/odp/api/spec/packet.h    |  8 ++++++
 include/odp/api/spec/packet_io.h | 54 +++++++++++++++++++++++++++++++---------
 3 files changed, 59 insertions(+), 17 deletions(-)

Patch

diff --git a/include/odp/api/spec/ipsec.h b/include/odp/api/spec/ipsec.h
index 7085bc0d..0b36b864 100644
--- a/include/odp/api/spec/ipsec.h
+++ b/include/odp/api/spec/ipsec.h
@@ -156,7 +156,9 @@  typedef struct odp_ipsec_inbound_config_t {
 	odp_ipsec_proto_layer_t parse;
 
 	/** Flags to control IPSEC payload data checks up to the selected parse
-	 *  level. */
+	 *  level. Checksum checking status can be queried for each packet with
+	 *  odp_packet_l3_chksum_status() and odp_packet_l4_chksum_status().
+	 */
 	union {
 		/** Mapping for individual bits */
 		struct {
@@ -191,10 +193,12 @@  typedef struct odp_ipsec_inbound_config_t {
  */
 typedef struct odp_ipsec_outbound_config_t {
 	/** Flags to control L3/L4 checksum insertion as part of outbound
-	 *  packet processing. Packet must have set with valid L3/L4 offsets.
-	 *  Checksum configuration is ignored for packets that checksum cannot
-	 *  be computed for (e.g. IPv4 fragments). Application may use a packet
-	 *  metadata flag to disable checksum insertion per packet bases.
+	 *  packet processing. These flags control checksum insertion (for the
+	 *  payload packet) in the same way as the checksum flags in
+	 *  odp_pktout_config_opt_t control checksum insertion when sending
+	 *  packets out through a pktio interface. Also packet checksum override
+	 *  functions (e.g. odp_packet_l4_chksum_insert()) can be used in
+	 *  the same way.
 	 */
 	union {
 		/** Mapping for individual bits */
diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h
index b3e1449f..c498e2e2 100644
--- a/include/odp/api/spec/packet.h
+++ b/include/odp/api/spec/packet.h
@@ -1428,6 +1428,10 @@  odp_packet_chksum_status_t odp_packet_l4_chksum_status(odp_packet_t pkt);
  * overrides a higher level configuration for checksum insertion into a L3
  * header during packet output processing.
  *
+ * Calling this function is always allowed but the checksum will not be
+ * inserted if the packet is output through a pktio that does not have
+ * the relevant pktout chksum bit set in the pktio capability.
+ *
  * @param pkt     Packet handle
  * @param l3      0: do not insert L3 checksum
  *                1: insert L3 checksum
@@ -1441,6 +1445,10 @@  void odp_packet_l3_chksum_insert(odp_packet_t pkt, int l3);
  * overrides a higher level configuration for checksum insertion into a L4
  * header during packet output processing.
  *
+ * Calling this function is always allowed but the checksum will not be
+ * inserted if the packet is output through a pktio that does not have
+ * the relevant pktout chksum bit set in the pktio capability.
+ *
  * @param pkt     Packet handle
  * @param l4      0: do not insert L4 checksum
  *                1: insert L4 checksum
diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h
index 6040a831..b56a5205 100644
--- a/include/odp/api/spec/packet_io.h
+++ b/include/odp/api/spec/packet_io.h
@@ -256,11 +256,27 @@  typedef struct odp_pktio_param_t {
  * belong to time synchronization protocol (PTP).
  *
  * Packet input checksum checking may be enabled or disabled. When it is
- * enabled, implementation will verify checksum correctness on incoming packets
- * and depending on drop configuration either deliver erroneous packets with
- * appropriate flags set (e.g. odp_packet_has_l3_error()) or drop those.
- * When packet dropping is enabled, application will never receive a packet
- * with the specified error and may avoid to check the error flag.
+ * enabled, implementation will attempt to verify checksum correctness on
+ * incoming packets and depending on drop configuration either deliver erroneous
+ * packets with appropriate flags set (e.g. odp_packet_has_l3_error(),
+ * odp_packet_l3_chksum_status()) or drop those. When packet dropping is
+ * enabled, application will never receive a packet with the specified error
+ * and may avoid to check the error flag.
+ *
+ * If checksum checking is enabled, IPv4 header checksum checking is always
+ * done for packets that do not have IP options and L4 checksum checking
+ * is done for unfragmented packets that do not have IPv4 options or IPv6
+ * extension headers. In other cases checksum checking may or may not
+ * be done. For example, L4 checksum of fragmented packets is typically
+ * not checked.
+ *
+ * IPv4 checksum checking may be enabled only when parsing level is
+ * ODP_PKTIO_PARSER_LAYER_L3 or higher. Similarly, L4 level checksum checking
+ * may be enabled only with parsing level ODP_PKTIO_PARSER_LAYER_L4 or higher.
+ *
+ * Whether checksum checking was done and whether a checksum was correct
+ * can be queried for each received packet with odp_packet_l3_chksum_status()
+ * and odp_packet_l4_chksum_status().
  */
 typedef union odp_pktin_config_opt_t {
 	/** Option flags */
@@ -314,13 +330,27 @@  typedef union odp_pktin_config_opt_t {
  * Packet output configuration options listed in a bit field structure. Packet
  * output checksum insertion may be enabled or disabled. When it is enabled,
  * implementation will calculate and insert checksum into every outgoing packet
- * by default. Application may use a packet metadata flag to disable checksum
- * insertion per packet bases. 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, output checksum insertion should
- * be disabled for optimal performance.
+ * by default. Application may disable checksum insertion (e.g.
+ * odp_packet_l4_chksum_insert()) on per packet basis. 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, output checksum insertion
+ * should be disabled for optimal performance.
+ *
+ * Packet flags (odp_packet_has_*()) are ignored for the purpose of checksum
+ * insertion in packet output.
+ *
+ * UDP, TCP and SCTP checksum insertion must not be requested for IP fragments.
+ * Use checksum override function (odp_packet_l4_chksum_insert()) to disable
+ * checksumming when sending a fragment through a packet IO interface that has
+ * the relevant L4 checksum insertion enabled.
+ *
+ * Result of checksum insertion at packet output is undefined if the protocol
+ * headers required for checksum calculation are not well formed. Packet must
+ * contain at least as many data bytes after L3/L4 offsets as the headers
+ * indicate. Other data bytes of the packet are ignored for the checksum
+ * insertion.
  */
 typedef union odp_pktout_config_opt_t {
 	/** Option flags */