From patchwork Tue May 3 20:41:08 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 67100 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp796659qge; Tue, 3 May 2016 13:41:59 -0700 (PDT) X-Received: by 10.107.39.138 with SMTP id n132mr6513077ion.103.1462308119889; Tue, 03 May 2016 13:41:59 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id z18si934476igp.57.2016.05.03.13.41.59; Tue, 03 May 2016 13:41:59 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 5D5BE61579; Tue, 3 May 2016 20:41:59 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id ADE4D610B9; Tue, 3 May 2016 20:41:23 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id F35FC610A6; Tue, 3 May 2016 20:41:19 +0000 (UTC) Received: from mail-oi0-f42.google.com (mail-oi0-f42.google.com [209.85.218.42]) by lists.linaro.org (Postfix) with ESMTPS id 0620561094 for ; Tue, 3 May 2016 20:41:18 +0000 (UTC) Received: by mail-oi0-f42.google.com with SMTP id x201so41661214oif.3 for ; Tue, 03 May 2016 13:41:18 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=Th5GVGLP6Oir+wIWS/D0m79OZpXeVRxedMNI0XbfcXI=; b=C+H7JgZn7DWYn1puhn3OBe50ml94eud9z2WrMn5KptuSonJn3nYM/Udqsw7yuCEocp 5nzsZ3ztEBzBWwYk8fqJ49kFVOOsgbcc0k4d6PAEYpz3T1i6PEfERddmN+IRYNXba44q SMvD6RvzPZ8H3KSUDw0MJdQSdRlAk2Dm3ssXaj7ZGJmTB/Eigl1o+XfioWtZI71C/h50 jBfZWPQQ93S9i/ERoMsHIyoB3wmb+yeD14CPmYWKNsqFnllSAi6GBJpqPVYcLgR5s/E8 vyT112+gB2T+XaggmLJx0fAwx6RXL1fKc2BItufRED8QXj/7xYt0ICvQpZ1XSIaKbSA2 VDJg== X-Gm-Message-State: AOPr4FXTKUzzcPB/MXbVTMOC+E7j+ZzpiALqZ4lCS7O6p0TdjORQBSEht1u5ElbQuHKd3qsz7JE= X-Received: by 10.202.96.68 with SMTP id u65mr2280743oib.83.1462308077567; Tue, 03 May 2016 13:41:17 -0700 (PDT) Received: from Ubuntu15.localdomain (cpe-66-68-129-43.austin.res.rr.com. [66.68.129.43]) by smtp.gmail.com with ESMTPSA id u41sm92107otd.37.2016.05.03.13.41.16 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 03 May 2016 13:41:16 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Tue, 3 May 2016 15:41:08 -0500 Message-Id: <1462308072-31150-2-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 In-Reply-To: <1462308072-31150-1-git-send-email-bill.fischofer@linaro.org> References: <1462308072-31150-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [PATCHv3 2/6] doc: userguide: split packet section into its own sub document X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Split the packet section of the User's Guide into a separate sub-document for ease of maintenance. Signed-off-by: Bill Fischofer --- doc/users-guide/Makefile.am | 1 + doc/users-guide/users-guide-packet.adoc | 120 +++++++++++++++++++++++++++++++ doc/users-guide/users-guide.adoc | 121 +------------------------------- 3 files changed, 122 insertions(+), 120 deletions(-) create mode 100644 doc/users-guide/users-guide-packet.adoc diff --git a/doc/users-guide/Makefile.am b/doc/users-guide/Makefile.am index e374864..98e468c 100644 --- a/doc/users-guide/Makefile.am +++ b/doc/users-guide/Makefile.am @@ -2,6 +2,7 @@ include ../Makefile.inc SRC = $(top_srcdir)/doc/users-guide/users-guide.adoc \ $(top_srcdir)/doc/users-guide/users-guide-cls.adoc \ + $(top_srcdir)/doc/users-guide/users-guide-packet.adoc \ $(top_srcdir)/doc/users-guide/users-guide-pktio.adoc \ $(top_srcdir)/doc/users-guide/users-guide-tm.adoc TARGET = users-guide.html diff --git a/doc/users-guide/users-guide-packet.adoc b/doc/users-guide/users-guide-packet.adoc new file mode 100644 index 0000000..32ba59d --- /dev/null +++ b/doc/users-guide/users-guide-packet.adoc @@ -0,0 +1,120 @@ +== Packet Processing +ODP applications are designed to process packets, which are the basic unit of +data of interest in the data plane. To assist in processing packets, ODP +provides a set of APIs that enable applications to examine and manipulate +packet data and metadata. Packets are referenced by an abstract *odp_packet_t* +handle defined by each implementation. + +Packet objects are normally created at ingress when they arrive at a source +*odp_pktio_t* and are received by an application either directly or (more +typically) for a scheduled receive queue. They MAY be implicitly freed when +they are transmitted to an output *odp_pktio_t* via an associated transmit +queue, or freed directly via the `odp_packet_free()` API. + +Occasionally an application may originate a packet itself, either _de novo_ or +by deriving it from an existing packet, and APIs are provided to assist in +these cases as well. Application-created packets can be recycled back through +a _loopback interface_ to reparse and reclassify them, or the application can +do its own parsing as desired. + +Various attributes associated with a packet, such as parse results, are +stored as metadata and APIs are provided to permit applications to examine +and/or modify this information. + +=== Packet Structure and Concepts +A _packet_ consists of a sequence of octets conforming to an architected +format, such as Ethernet, that can be received and transmitted via the ODP +*pktio* abstraction. Packets of a _length_, which is the number of bytes in +the packet. Packet data in ODP is referenced via _offsets_ since these reflect +the logical contents and structure of a packet independent of how particular +ODP implementations store that data. + +These concepts are shown in the following diagram: + +.ODP Packet Structure +image::../images/packet.svg[align="center"] + +Packet data consists of zero or more _headers_ followed by 0 or more bytes of +_payload_, followed by zero or more _trailers_. Shown here are various APIs +that permit applications to examine and navigate various parts of a packet and +to manipulate its structure. + +To support packet manipulation, predefined _headroom_ and _tailroom_ +areas are logically associated with a packet. Packets can be adjusted by +_pulling_ and _pushing_ these areas. Typical packet processing might consist +of stripping headers from a packet via `odp_pull_head()` calls as part of +receive processing and then replacing them with new headers via +`odp_push_head()` calls as the packet is being prepared for transmit. + +=== Packet Segments and Addressing +ODP platforms use various methods and techniques to store and process packets +efficiently. These vary considerably from platform to platform, so to ensure +portability across them ODP adopts certain conventions for referencing +packets. + +ODP APIs use a handle of type *odp_packet_t* to refer to packet objects. +Associated with packets are various bits of system metadata that describe the +packet. By referring to the metadata, ODP applications accelerate packet +processing by minimizing the need to examine packet data. This is because the +metadata is populated by parsing and classification functions that are coupled +to ingress processing that occur prior to a packet being presented to the +application via the ODP scheduler. + +When an ODP application needs to examine the contents of a packet, it requests +addressability to it via an API call that makes the packet (or a contiguously +addressable _segment_ of it) available for coherent access by the application. +To ensure portability, ODP applications assume that the underlying +implementation stores packets in _segments_ of implementation-defined +and managed size. These represent the contiguously addressable portions of a +packet that the application may refer to via normal memory accesses. ODP +provides APIs that allow applications to operate on packet segments in an +efficient and portable manner as needed. By combining these with the metadata +provided by packets, ODP applications can operate in a fully +platform-independent manner while still achieving optimal performance across +the range of platforms that support ODP. + +The use of segments for packet addressing and their relationship to metadata +is shown in this diagram: + +.ODP Packet Segmentation +image::../images/segment.svg[align="center"] + +The packet metadata is set during parsing and identifies the starting offsets +of the various headers in the packet. The packet itself is physically stored +as a sequence of segments that area managed by the ODP implementation. +Segment 0 is the first segment of the packet and is where the packet's headroom +and headers typically reside. Depending on the length of the packet, +additional segments may be part of the packet and contain the remaining packet +payload and tailroom. The application need not concern itself with segments +except that when the application requires addressability to a packet it +understands that addressability is provided on a per-segment basis. So, for +example, if the application makes a call like `odp_packet_l4_ptr()` to obtain +addressability to the packet's Layer 4 header, the returned length from that +call is the number of bytes from the start of the Layer 4 header that are +contiguously addressable to the application from the returned pointer address. +This is because the following byte occupies a different segment and may be +stored elsewhere. To obtain access to those bytes, the application simply +requests addressability to that offset and it will be able to address the +packet bytes that occupy the next segment, etc. Note that the returned +length for any packet addressability call is always the lesser of the remaining +packet length or size of its containing segment. So a mapping for segment 2 +in the above figure, for example, would return a length that extends only to +the end of the packet since the remaining bytes are part of the tailroom +reserved for the packet and are not usable by the application until made +available to it by an appropriate API call. + +=== Metadata Processing +As noted, packet metadata is normally set by the parser as part of +classification that occurs during packet receive processing. It is important +to note that this metadata may be changed by the application to reflect +changes in the packet contents and/or structure as part of its processing of +the packet. While changing this metadata may effect some ODP APIs, changing +metadata is designed to _document_ application changes to the packet but +does not in itself _cause_ those changes to be made. For example, if an +application changes the Layer 3 offset by using the `odp_packet_l3_offset_set()` +API, the subsequent calls to `odp_packet_l3_ptr()` will return an address +starting from that changed offset, changing an attribute like +`odp_packet_has_udp_set()` will not, by itself, turn a non-UDP packet into +a valid UDP packet. Applications are expected to exercise appropriate care +when changing packet metadata to ensure that the resulting metadata changes +reflect the actual changed packet structure that the application has made. diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index a2e5058..622e27f 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -903,126 +903,7 @@ NOTE: Both ordered and parallel queues improve throughput over atomic queues due to parallel event processing, but require that the application take steps to ensure context data synchronization if needed. -== Packet Processing -ODP applications are designed to process packets, which are the basic unit of -data of interest in the data plane. To assist in processing packets, ODP -provides a set of APIs that enable applications to examine and manipulate -packet data and metadata. Packets are referenced by an abstract *odp_packet_t* -handle defined by each implementation. - -Packet objects are normally created at ingress when they arrive at a source -*odp_pktio_t* and are received by an application either directly or (more -typically) for a scheduled receive queue. They MAY be implicitly freed when -they are transmitted to an output *odp_pktio_t* via an associated transmit -queue, or freed directly via the +odp_packet_free()+ API. - -Occasionally an application may originate a packet itself, either _de novo_ or -by deriving it from an existing packet, and APIs are provided to assist in -these cases as well. Application-created packets can be recycled back through -a _loopback interface_ to reparse and reclassify them, or the application can -do its own parsing as desired. - -Various attributes associated with a packet, such as parse results, are -stored as metadata and APIs are provided to permit applications to examine -and/or modify this information. - -=== Packet Structure and Concepts -A _packet_ consists of a sequence of octets conforming to an architected -format, such as Ethernet, that can be received and transmitted via the ODP -*pktio* abstraction. Packets of a _length_, which is the number of bytes in -the packet. Packet data in ODP is referenced via _offsets_ since these reflect -the logical contents and structure of a packet independent of how particular -ODP implementations store that data. - -These concepts are shown in the following diagram: - -.ODP Packet Structure -image::../images/packet.svg[align="center"] - -Packet data consists of zero or more _headers_ followed by 0 or more bytes of -_payload_, followed by zero or more _trailers_. Shown here are various APIs -that permit applications to examine and navigate various parts of a packet and -to manipulate its structure. - -To support packet manipulation, predefined _headroom_ and _tailroom_ -areas are logically associated with a packet. Packets can be adjusted by -_pulling_ and _pushing_ these areas. Typical packet processing might consist -of stripping headers from a packet via +odp_pull_head()+ calls as part of -receive processing and then replacing them with new headers via -+odp_push_head()+ calls as the packet is being prepared for transmit. - -=== Packet Segments and Addressing -ODP platforms use various methods and techniques to store and process packets -efficiently. These vary considerably from platform to platform, so to ensure -portability across them ODP adopts certain conventions for referencing -packets. - -ODP APIs use a handle of type *odp_packet_t* to refer to packet objects. -Associated with packets are various bits of system metadata that describe the -packet. By referring to the metadata, ODP applications accelerate packet -processing by minimizing the need to examine packet data. This is because the -metadata is populated by parsing and classification functions that are coupled -to ingress processing that occur prior to a packet being presented to the -application via the ODP scheduler. - -When an ODP application needs to examine the contents of a packet, it requests -addressability to it via an API call that makes the packet (or a contiguously -addressable _segment_ of it) available for coherent access by the application. -To ensure portability, ODP applications assume that the underlying -implementation stores packets in _segments_ of implementation-defined -and managed size. These represent the contiguously addressable portions of a -packet that the application may refer to via normal memory accesses. ODP -provides APIs that allow applications to operate on packet segments in an -efficient and portable manner as needed. By combining these with the metadata -provided by packets, ODP applications can operate in a fully -platform-independent manner while still achieving optimal performance across -the range of platforms that support ODP. - -The use of segments for packet addressing and their relationship to metadata -is shown in this diagram: - -.ODP Packet Segmentation -image::../images/segment.svg[align="center"] - -The packet metadata is set during parsing and identifies the starting offsets -of the various headers in the packet. The packet itself is physically stored -as a sequence of segments that area managed by the ODP implementation. -Segment 0 is the first segment of the packet and is where the packet's headroom -and headers typically reside. Depending on the length of the packet, -additional segments may be part of the packet and contain the remaining packet -payload and tailroom. The application need not concern itself with segments -except that when the application requires addressability to a packet it -understands that addressability is provided on a per-segment basis. So, for -example, if the application makes a call like +odp_packet_l4_ptr()+ to obtain -addressability to the packet's Layer 4 header, the returned length from that -call is the number of bytes from the start of the Layer 4 header that are -contiguously addressable to the application from the returned pointer address. -This is because the following byte occupies a different segment and may be -stored elsewhere. To obtain access to those bytes, the application simply -requests addressability to that offset and it will be able to address the -packet bytes that occupy the next segment, etc. Note that the returned -length for any packet addressability call is always the lesser of the remaining -packet length or size of its containing segment. So a mapping for segment 2 -in the above figure, for example, would return a length that extends only to -the end of the packet since the remaining bytes are part of the tailroom -reserved for the packet and are not usable by the application until made -available to it by an appropriate API call. - -=== Metadata Processing -As noted, packet metadata is normally set by the parser as part of -classification that occurs during packet receive processing. It is important -to note that this metadata may be changed by the application to reflect -changes in the packet contents and/or structure as part of its processing of -the packet. While changing this metadata may effect some ODP APIs, changing -metadata is designed to _document_ application changes to the packet but -does not in itself _cause_ those changes to be made. For example, if an -application changes the Layer 3 offset by using the +odp_packet_l3_offset_set()+ -API, the subsequent calls to +odp_packet_l3_ptr()+ will return an address -starting from that changed offset, changing an attribute like -+odp_packet_has_udp_set()+ will not, by itself, turn a non-UDP packet into -a valid UDP packet. Applications are expected to exercise appropriate care -when changing packet metadata to ensure that the resulting metadata changes -reflect the actual changed packet structure that the application has made. +include::users-guide-packet.adoc[] include::users-guide-pktio.adoc[]