From patchwork Fri May 6 17:51:03 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 67293 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp442927qge; Fri, 6 May 2016 10:54:33 -0700 (PDT) X-Received: by 10.107.17.151 with SMTP id 23mr24713917ior.101.1462557273843; Fri, 06 May 2016 10:54:33 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id f83si18732732ioi.35.2016.05.06.10.54.33; Fri, 06 May 2016 10:54:33 -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 1C83261639; Fri, 6 May 2016 17:54:33 +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 8518D61642; Fri, 6 May 2016 17:53:05 +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 52C196162D; Fri, 6 May 2016 17:51:27 +0000 (UTC) Received: from mail-oi0-f47.google.com (mail-oi0-f47.google.com [209.85.218.47]) by lists.linaro.org (Postfix) with ESMTPS id 481CF6162E for ; Fri, 6 May 2016 17:51:13 +0000 (UTC) Received: by mail-oi0-f47.google.com with SMTP id x19so147207210oix.2 for ; Fri, 06 May 2016 10:51:13 -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=YxQ5zXlP1vZk/ZyhEMStwq5RfabN1hABqVJ/ptCpwFff9OtWusGgSu/7FzWgJdkHSs cfzdhc6tKpExFVIHy6tIAqumO2CRigYZKn+LgeN/ss5oCzyfy+pysCV4QpkXlyvc+wpy h3NKBj/aAGN35Y66iTfJxUdTkzbTzqUWg9o8KQAJ4Q44UMrUlG4fdeCSV7wjYwCtS86T HNmqo4hAeUNQdeMDQGaGdKF0RYXbq0Srh7DQ6lG1ozQd+C3BPZ4ayMtPMkudClNicKo/ Oqv1Uitc0ZbArTociWV2u9aH6uYIFq63yNQA0tgm21dmnSaSaDM3FagbYqmVK4Rt9bqP 3Jkw== X-Gm-Message-State: AOPr4FUN61uaO1ONQRlwziEn1iQfy+lF5VNB/6Fd2CKDVES8MdrNdeBNHRdQ8Do8vNBIZ3fkrbM= X-Received: by 10.157.11.106 with SMTP id p39mr10984581otd.117.1462557072771; Fri, 06 May 2016 10:51:12 -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 h7sm5082069oej.1.2016.05.06.10.51.11 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 06 May 2016 10:51:12 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Fri, 6 May 2016 12:51:03 -0500 Message-Id: <1462557065-14666-4-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 In-Reply-To: <1462557065-14666-1-git-send-email-bill.fischofer@linaro.org> References: <1462557065-14666-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [PATCHv4 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