doc: userguide: add pktio capability and config info

Update PktIO section of Users Guide to cover pktio capability
and input/output/parser configuration features.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>
Reviewed-by: Josep Puigdemont <josep.puigdemont@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 298 insertions, 0 deletions

diff --git a/doc/users-guide/users-guide-pktio.adoc b/doc/users-guide/users-guide-pktio.adoc
index 79d6b1a20..73d6e0485 100644
--- a/doc/users-guide/users-guide-pktio.adoc
+++ b/doc/users-guide/users-guide-pktio.adoc
@@ -132,6 +132,304 @@ use for packet allocation if not overridden by the classifier due to a
 specific or default Class-of-Service (CoS) match on the packet. The *param*
 struct, in turn, specifies the input and output *modes* of the PktIO.
 
+=== PktIO Capabilities and PktIn/PktOut Configuration
+Associated with each PktIO is a set of _capabilities_ that provide information
+such as the maximum number of input/output queues it supports, its configuration
+options, and the operations is supports. These are aggregated into
+the struct:
+[source,c]
+-----
+/**
+ * Packet IO capabilities
+ */
+typedef struct odp_pktio_capability_t {
+	/** Maximum number of input queues */
+	unsigned max_input_queues;
+
+	/** Maximum number of output queues */
+	unsigned max_output_queues;
+
+	/** Supported pktio configuration options */
+	odp_pktio_config_t config;
+
+	/** Supported set operations
+	 *
+	 * A bit set to one indicates a supported operation. All other bits are
+	 * set to zero. */
+	odp_pktio_set_op_t set_op;
+
+	/** @deprecated Use enable_loop inside odp_pktin_config_t */
+	odp_bool_t ODP_DEPRECATE(loop_supported);
+} odp_pktio_capability_t;
+-----
+That is returned by the `odp_pktio_capability()` API. This returns the
+limits and default values for these capabilities which can in turn be set
+via the `odp_pktio_config()` API, which takes as input the struct:
+[source,c]
+-----
+/**
+ * Packet IO configuration options
+ *
+ * Packet IO interface level configuration options. Use odp_pktio_capability()
+ * to see which options are supported by the implementation.
+ * Use odp_pktio_config_init() to initialize the structure with default values.
+ */
+typedef struct odp_pktio_config_t {
+	/** Packet input configuration options bit field
+	 *
+	 *  Default value for all bits is zero. */
+	odp_pktin_config_opt_t pktin;
+
+	/** Packet output configuration options bit field
+	 *
+	 *  Default value for all bits is zero. */
+	odp_pktout_config_opt_t pktout;
+
+	/** Packet input parser configuration */
+	odp_pktio_parser_config_t parser;
+
+	/** Interface loopback mode
+	 *
+	 * In this mode the packets sent out through the interface is
+	 * looped back to input of the same interface. Supporting loopback mode
+	 * is an optional feature per interface and should be queried in the
+	 * interface capability before enabling the same. */
+	odp_bool_t enable_loop;
+
+	/** Inbound IPSEC inlined with packet input
+	 *
+	 *  Enable/disable inline inbound IPSEC operation. When enabled packet
+	 *  input directs all IPSEC packets automatically to IPSEC inbound
+	 *  processing. IPSEC configuration is done through the IPSEC API.
+	 *  Packets that are not (recognized as) IPSEC are processed
+	 *  according to the packet input configuration.
+	 *
+	 *  0: Disable inbound IPSEC inline operation (default)
+	 *  1: Enable inbound IPSEC inline operation
+	 *
+	 *  @see odp_ipsec_config(), odp_ipsec_sa_create()
+	 */
+	odp_bool_t inbound_ipsec;
+
+	/** Outbound IPSEC inlined with packet output
+	 *
+	 *  Enable/disable inline outbound IPSEC operation. When enabled IPSEC
+	 *  outbound processing can send outgoing IPSEC packets directly
+	 *  to the pktio interface for output. IPSEC configuration is done
+	 *  through the IPSEC API.
+	 *
+	 *  Outbound IPSEC inline operation cannot be combined with traffic
+	 *  manager (ODP_PKTOUT_MODE_TM).
+	 *
+	 *  0: Disable outbound IPSEC inline operation (default)
+	 *  1: Enable outbound IPSEC inline operation
+	 *
+	 *  @see odp_ipsec_config(), odp_ipsec_sa_create()
+	 */
+	odp_bool_t outbound_ipsec;
+
+} odp_pktio_config_t;
+-----
+The IPsec related configurations will be discussed later in the IPsec chapter,
+but for now we'll focus on the PktIn/PktOut configuration and the
+parser configuration.
+
+==== PktIn Configuration
+For PktIOs that will receive packets, the `odp_pktin_config_opt_t` struct
+controls RX processing to be performed on these packets as they are received:
+[source,c]
+-----
+/**
+ * Packet input configuration options bit field
+ *
+ * Packet input configuration options listed in a bit field structure. Packet
+ * input timestamping may be enabled for all packets or at least for those that
+ * belong to time synchronization protocol (PTP).
+ *
+ * Packet input checksum checking may be enabled or disabled. When it is
+ * 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_PROTO_LAYER_L3 or higher. Similarly, L4 level checksum checking
+ * may be enabled only with parsing level ODP_PROTO_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 */
+	struct {
+		/** Timestamp all packets on packet input */
+		uint64_t ts_all        : 1;
+
+		/** Timestamp (at least) IEEE1588 / PTP packets
+		  * on packet input */
+		uint64_t ts_ptp        : 1;
+
+		/** Check IPv4 header checksum on packet input */
+		uint64_t ipv4_chksum   : 1;
+
+		/** Check UDP checksum on packet input */
+		uint64_t udp_chksum    : 1;
+
+		/** Check TCP checksum on packet input */
+		uint64_t tcp_chksum    : 1;
+
+		/** Check SCTP checksum on packet input */
+		uint64_t sctp_chksum   : 1;
+
+		/** Drop packets with an IPv4 error on packet input */
+		uint64_t drop_ipv4_err : 1;
+
+		/** Drop packets with an IPv6 error on packet input */
+		uint64_t drop_ipv6_err : 1;
+
+		/** Drop packets with a UDP error on packet input */
+		uint64_t drop_udp_err  : 1;
+
+		/** Drop packets with a TCP error on packet input */
+		uint64_t drop_tcp_err  : 1;
+
+		/** Drop packets with a SCTP error on packet input */
+		uint64_t drop_sctp_err : 1;
+
+	} bit;
+
+	/** All bits of the bit field structure
+	  *
+	  * This field can be used to set/clear all flags, or bitwise
+	  * operations over the entire structure. */
+	uint64_t all_bits;
+} odp_pktin_config_opt_t;
+-----
+These are used to control packet timestamping as well as default packet checkum
+verification processing.
+
+==== PktIO Parsing Configuration
+For RX processing, packets may also be parsed automatically as part of
+receipt as controlled by the `odp_pktio_parser_config_t` struct:
+[source,c]
+-----
+/**
+ * Parser configuration
+ */
+typedef struct odp_pktio_parser_config_t {
+	/** Protocol parsing level in packet input
+	  *
+	  * Application requires that protocol headers in a packet are checked
+	  * up to this layer during packet input. Use ODP_PROTO_LAYER_ALL for
+	  * all layers. Packet metadata for this and all preceding layers are
+	  * set. In addition, offset (and pointer) to the next layer is set.
+	  * Other layer/protocol specific metadata have undefined values.
+	  *
+	  * The default value is ODP_PROTO_LAYER_ALL. */
+	odp_proto_layer_t layer;
+
+} odp_pktio_parser_config_t;
+-----
+Note that parsing is automatically done whenever classification is enabled
+for an RX interface (see below).
+
+==== PktOut Configuration
+For PktIOs that will transmit packets, the `odp_pktout_config_opt_t` struct
+controls TX processing to be performed on these packets as they are
+transmitted:
+[source,c]
+-----
+/**
+ * Packet output configuration options bit field
+ *
+ * Packet output configuration options listed in a bit field structure. Packet
+ * output checksum insertion may be enabled or disabled (e.g. ipv4_chksum_ena):
+ *
+ *  0: Disable checksum insertion. Application will not request checksum
+ *     insertion for any packet. This is the default value for xxx_chksum_ena
+ *     bits.
+ *  1: Enable checksum insertion. Application will request checksum insertion
+ *     for some packets.
+ *
+ * When checksum insertion is enabled, application may use configuration options
+ * to set the default behaviour on packet output (e.g. ipv4_chksum):
+ *
+ *  0: Do not insert checksum by default. This is the default value for
+ *     xxx_chksum bits.
+ *  1: Calculate and insert checksum by default.
+ *
+ * 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.
+ *
+ * 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 for packet output */
+	struct {
+		/** Enable IPv4 header checksum insertion. */
+		uint64_t ipv4_chksum_ena : 1;
+
+		/** Enable UDP checksum insertion */
+		uint64_t udp_chksum_ena  : 1;
+
+		/** Enable TCP checksum insertion */
+		uint64_t tcp_chksum_ena  : 1;
+
+		/** Enable SCTP checksum insertion */
+		uint64_t sctp_chksum_ena : 1;
+
+		/** Insert IPv4 header checksum by default */
+		uint64_t ipv4_chksum     : 1;
+
+		/** Insert UDP checksum on packet by default */
+		uint64_t udp_chksum      : 1;
+
+		/** Insert TCP checksum on packet by default */
+		uint64_t tcp_chksum      : 1;
+
+		/** Insert SCTP checksum on packet by default */
+		uint64_t sctp_chksum     : 1;
+
+	} bit;
+
+	/** All bits of the bit field structure
+	  *
+	  * This field can be used to set/clear all flags, or bitwise
+	  * operations over the entire structure. */
+	uint64_t all_bits;
+} odp_pktout_config_opt_t;
+-----
+These are used to control default checksum generation processing for
+transmitted packets.
+
 === PktIO Input and Output Modes
 PktIO objects support four different Input and Output modes, that may be
 specified independently at *open* time.