From patchwork Tue May 3 20:41:10 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 67102 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp797481qge; Tue, 3 May 2016 13:44:17 -0700 (PDT) X-Received: by 10.107.173.158 with SMTP id m30mr6471821ioo.131.1462308253749; Tue, 03 May 2016 13:44:13 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id k188si665712itb.22.2016.05.03.13.44.13; Tue, 03 May 2016 13:44:13 -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 3EC2461587; Tue, 3 May 2016 20:44:13 +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_H2, 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 DE037615BF; Tue, 3 May 2016 20:44:06 +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 7A569610B1; Tue, 3 May 2016 20:43:21 +0000 (UTC) Received: from mail-oi0-f43.google.com (mail-oi0-f43.google.com [209.85.218.43]) by lists.linaro.org (Postfix) with ESMTPS id 982FE61094 for ; Tue, 3 May 2016 20:41:28 +0000 (UTC) Received: by mail-oi0-f43.google.com with SMTP id k142so41740239oib.1 for ; Tue, 03 May 2016 13:41:28 -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=QRDOQyrfmYvJIU2K+pVeNxVa1ni+OW1OM01K/qNobXg=; b=KmGbR9rx6jdbR5/vnSYYZoujx6Hp811h/WbYSsZuQJxujCrMZURBUsB5ybEk/FPYVe 5pq1yvnGkCq5uR3tWr0iVsIBb7XMKo7CTCGgBAnd9O6NvYfhm3kLn4IJlT25yW4RV+Ul 30pjevY6h/HQW0L6UgdrTIxFyzXxRNXeBoicjtbRu6lmPrXkK+90ghgATrDaJnb+6+O3 rea+xmHQukwQbJIRY7sJ3ERIZBUa0OzswcHzsK0JLhMrd8mP5ZjTKdAUNO8dK3EJsuz+ PWDQdp6obEjmh14Hxi4Od2uX/cHEnW3rDFkwhYY/eQT1Y+QPJnFeXP2YNB7bn+ZvXfpv rmvg== X-Gm-Message-State: AOPr4FXZRzq/Wvj0RXygJ97u2XxKh5wdrScS6SICUi+NUtrp1kous9Fqaotw/uG1txC0FzDeCoM= X-Received: by 10.202.74.10 with SMTP id x10mr2210115oia.157.1462308088106; Tue, 03 May 2016 13:41:28 -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.23 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 03 May 2016 13:41:25 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Tue, 3 May 2016 15:41:10 -0500 Message-Id: <1462308072-31150-4-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 4/6] doc: userguide: add extend/trunc doc 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" Add additional information about the new APIs: odp_packet_extend_head() / odp_packet_trunc_head() odp_packet_extend_tail() / odp_packet_trunc_tail() Signed-off-by: Bill Fischofer --- doc/users-guide/users-guide-packet.adoc | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/users-guide/users-guide-packet.adoc b/doc/users-guide/users-guide-packet.adoc index 32ba59d..0eadd6b 100644 --- a/doc/users-guide/users-guide-packet.adoc +++ b/doc/users-guide/users-guide-packet.adoc @@ -32,7 +32,7 @@ ODP implementations store that data. These concepts are shown in the following diagram: .ODP Packet Structure -image::../images/packet.svg[align="center"] +image::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 @@ -76,8 +76,8 @@ 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"] +.ODP Packet Segmentation and Manipulation +image::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 @@ -103,6 +103,17 @@ 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. +While the push/pull APIs permit applications to perform efficient manipulation +of packets within the current segment structure, ODP also provices APIs that +permit segments to be added or removed. The `odp_packet_extend_head()` and +`odp_packet_trunc_head()` APIs permit segments to be added or removed from +the beginning of a packet, while `odp_packet_extend_tail()` and +`odp_packet_trunc_tail()` permit segments to be added or removed from the end +of a packet. Extending a packet adds one or more segments to permit packets to +grow up to implementation-defined limits. Truncating a packet removes one or +more segments to shrink the size of a packet beyond its initial or final +segment. + === 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