From patchwork Sun May 1 21:23:45 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 66993 Delivered-To: patch@linaro.org Received: by 10.140.93.198 with SMTP id d64csp778639qge; Sun, 1 May 2016 14:26:00 -0700 (PDT) X-Received: by 10.107.172.135 with SMTP id v129mr12929775ioe.5.1462137960836; Sun, 01 May 2016 14:26:00 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id q1si251766igm.99.2016.05.01.14.26.00; Sun, 01 May 2016 14:26:00 -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 462E5615CC; Sun, 1 May 2016 21:26:00 +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 8F196615E2; Sun, 1 May 2016 21:24:07 +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 E29CE615C2; Sun, 1 May 2016 21:23:55 +0000 (UTC) Received: from mail-oi0-f53.google.com (mail-oi0-f53.google.com [209.85.218.53]) by lists.linaro.org (Postfix) with ESMTPS id 486DC6158B for ; Sun, 1 May 2016 21:23:54 +0000 (UTC) Received: by mail-oi0-f53.google.com with SMTP id x19so171496575oix.2 for ; Sun, 01 May 2016 14:23:54 -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=pa2Jo0CdGCNK7AFmyUCnCOZoZQ+xeQco1m2CaEtYG0g=; b=FHqXMCVTHVfsIZawtZ6uEYSU44FZQnY2hW4FFvC9ibbtScBSRn1/HFXjY+d+lX/LEc GiauDR7Ay8dXmdRtSAYOYIMq+mYQsxYU6ZkGsGVIGvN2NGEwGJbm6wx3pn+8ef4r84zs tGtDg/FcVAnZ0Nw124/M2mm2+rMruCUkHmFG8cIzPsfXHYbjp8a76fdcsBlCgt+Tmuze 39R1jPS8Wrp5t6I4JAaplEZpg0nbt3YAwghuCvM5X/UhZvJwSsFHuPiKmttLLr8UBtA5 QlCgYfTznNjzuG4J5JnNBfwyuu2c3v8z2RZ0iv60uoDJ/47BYpeAtQqbMv7Ojr6YZdOT /OOA== X-Gm-Message-State: AOPr4FXNbqGlNzdtLkLiHbbcu5gfzv3WeecWsexmwVVZiknFY/8TnfAofoCxNTJE8nX4KCTpt6k= X-Received: by 10.202.190.65 with SMTP id o62mr12647483oif.109.1462137833883; Sun, 01 May 2016 14:23:53 -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 u41sm7605123otd.37.2016.05.01.14.23.53 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 01 May 2016 14:23:53 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Sun, 1 May 2016 16:23:45 -0500 Message-Id: <1462137827-26836-4-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 In-Reply-To: <1462137827-26836-1-git-send-email-bill.fischofer@linaro.org> References: <1462137827-26836-1-git-send-email-bill.fischofer@linaro.org> X-Topics: patch Subject: [lng-odp] [API-NEXT PATCHv2 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 ce665a3..1bb0793 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