From patchwork Thu Feb 22 14:00:06 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Github ODP bot X-Patchwork-Id: 129247 Delivered-To: patch@linaro.org Received: by 10.46.66.2 with SMTP id p2csp626854lja; Thu, 22 Feb 2018 06:01:18 -0800 (PST) X-Google-Smtp-Source: AH8x225j6hC4j3gTNiCQKrJuO/riHnMvu0i1q5qW/YjlVTgj0aSYbo5hoibYr0j588Eknb5Uyn/n X-Received: by 2002:a25:c2c3:: with SMTP id s186-v6mr4573582ybf.205.1519308078110; Thu, 22 Feb 2018 06:01:18 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1519308078; cv=none; d=google.com; s=arc-20160816; b=yL2cSXgj7FSd28PoViQDImWF+3boqielj3feJnAg2nGZF6Mng+mGrzmmY17kvJgXuG HR+FX0lJOjNv7B7oHrql2nF+VVyL5reDZtxvXPHVWjhVLQbJKvCzeusDWYbkdA7xqgtd Qnsu6i5UlfSotPttZBHGl8b2nXL1PffUOih/flsM5KY4htj/IDD641q++tWXFXtIVEUw mTnvR0Nn1HYHJujdw1Q9q0wRm/FwJOFPclAVCQODYCPvXBw1iyWiOvs/hrb5EZLKgcKL 9BWFaKQ+bM8X/YQeP3XLrds4Ci9E+deaFvZIFInqUmcj4JM5W+Nn2ecGLu0DqGioUi3j hUFg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:github-pr-num :references:in-reply-to:message-id:date:to:from:delivered-to :arc-authentication-results; bh=BG8zIQ06vNUlWt7y/ht+Bjo5Rkk2f3zFgt3e0Dt6pvg=; b=d8Lb+iRhiWWxcFZz4CVF2WrXZm01NEZp8xrUVtLjLJvGXjO/QPE34h616oUH+NfVM0 9GScjTHpCitpf9yGXg6gPaey5eA0XKB1Awfn9hRnoEfIFk1wPGWwcAq4A51QBqB8NzvJ x4DR8200/XHT8jfx7m6LiHxwQ5UcqRkxlQeDhxrsIqoYu3aUmrAtkYBOytlKUXrccybD j3VX3o/ZxWuJ2iIFNW+ejq0bxN0n8rup9XfDrcXKh28jo5ZE2Fp+iGUGnApHdXrA9eqa +wo69PDLVa7X26kYuDbna8MTeQV+POKdBp4SoUe58ztezPlMnbd7QTs0iTOZOFpZueAq PMlA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=yandex.ru Return-Path: Received: from lists.linaro.org (ec2-54-197-127-237.compute-1.amazonaws.com. [54.197.127.237]) by mx.google.com with ESMTP id q37si124412qtj.451.2018.02.22.06.01.17; Thu, 22 Feb 2018 06:01:18 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) client-ip=54.197.127.237; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=yandex.ru Received: by lists.linaro.org (Postfix, from userid 109) id BCBA46171D; Thu, 22 Feb 2018 14:01:17 +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,FREEMAIL_FROM, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2 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 191BE60743; Thu, 22 Feb 2018 14:00:28 +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 9605661724; Thu, 22 Feb 2018 14:00:18 +0000 (UTC) Received: from forward105p.mail.yandex.net (forward105p.mail.yandex.net [77.88.28.108]) by lists.linaro.org (Postfix) with ESMTPS id 4A348616E4 for ; Thu, 22 Feb 2018 14:00:13 +0000 (UTC) Received: from mxback7g.mail.yandex.net (mxback7g.mail.yandex.net [IPv6:2a02:6b8:0:1472:2741:0:8b7:168]) by forward105p.mail.yandex.net (Yandex) with ESMTP id 0392C40849D6 for ; Thu, 22 Feb 2018 17:00:12 +0300 (MSK) Received: from smtp3o.mail.yandex.net (smtp3o.mail.yandex.net [2a02:6b8:0:1a2d::27]) by mxback7g.mail.yandex.net (nwsmtp/Yandex) with ESMTP id Ns6dm8Nrh1-0BdKcpGd; Thu, 22 Feb 2018 17:00:11 +0300 Received: by smtp3o.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id IAwM2n92hm-0BY4bEcC; Thu, 22 Feb 2018 17:00:11 +0300 (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (Client certificate not present) From: Github ODP bot To: lng-odp@lists.linaro.org Date: Thu, 22 Feb 2018 17:00:06 +0300 Message-Id: <1519308009-12837-2-git-send-email-odpbot@yandex.ru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1519308009-12837-1-git-send-email-odpbot@yandex.ru> References: <1519308009-12837-1-git-send-email-odpbot@yandex.ru> Github-pr-num: 497 Subject: [lng-odp] [PATCH API-NEXT v1 1/4] api: packet: improve segmented packet documentation 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: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" From: Petri Savolainen Improve documentation text to be more explicit that packets may be segmented. Signed-off-by: Petri Savolainen --- /** Email created from pull request 497 (psavol:next-packet-data-doc) ** https://github.com/Linaro/odp/pull/497 ** Patch: https://github.com/Linaro/odp/pull/497.patch ** Base sha: ea2afab619ae74108a03798bc358fdfcd29fdd88 ** Merge commit sha: d1c9a3d36dfe9e38ecfe7d4a52bebe13d0c01098 **/ include/odp/api/spec/packet.h | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h index 079a1ae1b..746f6fbf7 100644 --- a/include/odp/api/spec/packet.h +++ b/include/odp/api/spec/packet.h @@ -401,30 +401,39 @@ uint32_t odp_packet_buf_len(odp_packet_t pkt); /** * Packet data pointer * - * Returns the current packet data pointer. When a packet is received - * from packet input, this points to the first byte of the received - * packet. Packet level offsets are calculated relative to this position. + * Returns pointer to the first byte of packet data. When packet is segmented, + * only a portion of packet data follows the pointer. When unsure, use e.g. + * odp_packet_seg_len() to check the data length following the pointer. Packet + * level offsets are calculated relative to this position. * - * User can adjust the data pointer with head_push/head_pull (does not modify - * segmentation) and add_data/rem_data calls (may modify segmentation). + * When a packet is received from packet input, this points to the first byte + * of the received packet. Pool configuration parameters may be used to ensure + * that the first packet segment contains all/most of the data relevant to the + * application. + * + * User can adjust the data pointer with e.g. push_head/pull_head (does not + * modify segmentation) and extend_head/trunc_head (may modify segmentation) + * calls. * * @param pkt Packet handle * * @return Pointer to the packet data * - * @see odp_packet_l2_ptr(), odp_packet_seg_len() + * @see odp_packet_seg_len(), odp_packet_push_head(), odp_packet_extend_head() */ void *odp_packet_data(odp_packet_t pkt); /** - * Packet segment data length + * Packet data length following the data pointer * - * Returns number of data bytes following the current data pointer - * (odp_packet_data()) location in the segment. + * Returns number of data bytes (in the segment) following the current data + * pointer position. When unsure, use this function to check how many bytes + * can be accessed linearly after data pointer (odp_packet_data()). This + * equals to odp_packet_len() for single segment packets. * * @param pkt Packet handle * - * @return Segment data length in bytes (pointed by odp_packet_data()) + * @return Segment data length in bytes following odp_packet_data() * * @see odp_packet_data() */ @@ -433,11 +442,14 @@ uint32_t odp_packet_seg_len(odp_packet_t pkt); /** * Packet data length * - * Returns sum of data lengths over all packet segments. + * Returns total data length over all packet segments. This equals the sum of + * segment level data lengths (odp_packet_seg_data_len()). * * @param pkt Packet handle * * @return Packet data length + * + * @see odp_packet_seg_len(), odp_packet_data(), odp_packet_seg_data_len() */ uint32_t odp_packet_len(odp_packet_t pkt);