From patchwork Mon Mar 21 21:43:39 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bill Fischofer X-Patchwork-Id: 64141 Delivered-To: patch@linaro.org Received: by 10.112.199.169 with SMTP id jl9csp1679062lbc; Mon, 21 Mar 2016 14:43:55 -0700 (PDT) X-Received: by 10.55.212.207 with SMTP id s76mr43074978qks.78.1458596634913; Mon, 21 Mar 2016 14:43:54 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id u82si5710059qki.124.2016.03.21.14.43.54; Mon, 21 Mar 2016 14:43:54 -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 Received: by lists.linaro.org (Postfix, from userid 109) id 27A81619DA; Mon, 21 Mar 2016 21:43:54 +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 D7A9A61845; Mon, 21 Mar 2016 21:43:49 +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 6D0156198B; Mon, 21 Mar 2016 21:43:46 +0000 (UTC) Received: from mail-oi0-f45.google.com (mail-oi0-f45.google.com [209.85.218.45]) by lists.linaro.org (Postfix) with ESMTPS id 1C03E61746 for ; Mon, 21 Mar 2016 21:43:45 +0000 (UTC) Received: by mail-oi0-f45.google.com with SMTP id l76so64318797oig.1 for ; Mon, 21 Mar 2016 14:43:45 -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; bh=1WBY6AaOkdSKM0zAUlDN/3NQgjwPSpMPcZ8DHBg9+Io=; b=c9z95Xx6Lhluxz+fJkj6CRTLStt6c9PjEMboKL56R67l6QSpI9VJ2aVMOqHU4Q31vD i7utssoc7Hgw68SREpTmBe5NuNW3LThPfm0SC3JTMZ+BdMPebN0QP/EheyXwYfvWARvX kUMjF6iwpQW5vT1phMB69of2yHzSbsIuhecupg2e2uBK8tmCNVH0/xpp3Q2helxh4DCj o4NfB3d6QC7MYpgrMYto953fEOP4mf9I3R3IsJ/96qHap3aUD/XdKUekyzxLRvwL51/+ Nnv5oJ+AQC+8iVC3kuWbtPrATi+HBCUtTzINB1BPMT8gkVTecd0/VoGc3inWuaW41cxh yDnQ== X-Gm-Message-State: AD7BkJLQ6KrnUZsPIKyi8n1puzOpv39SO4X9Hkp92ZBjpJ3B48t6HFZl9uRihmDjh/8/vA6PPSQ= X-Received: by 10.157.29.179 with SMTP id y48mr1085052otd.78.1458596624580; Mon, 21 Mar 2016 14:43:44 -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 du1sm12569273oeb.9.2016.03.21.14.43.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 21 Mar 2016 14:43:43 -0700 (PDT) From: Bill Fischofer To: lng-odp@lists.linaro.org Date: Mon, 21 Mar 2016 16:43:39 -0500 Message-Id: <1458596621-18381-1-git-send-email-bill.fischofer@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [API-NEXT PATCHv2 1/3] api: packet: update doxygen for multi-segment push/pull operations 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" Signed-off-by: Bill Fischofer --- include/odp/api/spec/packet.h | 52 +++++++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h index 9c63b5f..4fa5a73 100644 --- a/include/odp/api/spec/packet.h +++ b/include/odp/api/spec/packet.h @@ -294,9 +294,13 @@ void *odp_packet_tail(odp_packet_t pkt); * Push out packet head * * Increase packet data length by moving packet head into packet headroom. - * Packet headroom is decreased with the same amount. The packet head may be - * pushed out up to 'headroom' bytes. Packet is not modified if there's not - * enough headroom space. + * Packet headroom is decreased by the same amount. If there is insufficient + * headroom available in the current segment the packet MAY be extended with + * additional segment(s) to accommodate the push request. Note that such + * extension may change the segmentation of the packet but does not affect + * the packet handle. As a result, the entire requested length may not be + * contiguously addressable from the returned data pointer. Use + * odp_packet_offset() to obtain this information if needed. * * odp_packet_xxx: * seg_len += len @@ -304,12 +308,11 @@ void *odp_packet_tail(odp_packet_t pkt); * headroom -= len * data -= len * - * Operation does not modify packet segmentation or move data. Handles and - * pointers remain valid. User is responsible to update packet metadata - * offsets when needed. + * Following this operation packet handles and pointers remain valid. User is + * responsible to update packet metadata offsets when needed. * * @param pkt Packet handle - * @param len Number of bytes to push the head (0 ... headroom) + * @param len Number of bytes to push the head (0 or more) * * @return The new data pointer * @retval NULL Requested offset exceeds available headroom @@ -322,9 +325,8 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t len); * Pull in packet head * * Decrease packet data length by removing data from the head of the packet. - * Packet headroom is increased with the same amount. Packet head may be pulled - * in up to seg_len - 1 bytes (i.e. packet data pointer must stay in the - * first segment). Packet is not modified if there's not enough data. + * Packet headroom is increased with the same amount. Packet is not modified + * if there's not enough data. * * odp_packet_xxx: * seg_len -= len @@ -332,9 +334,8 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t len); * headroom += len * data += len * - * Operation does not modify packet segmentation or move data. Handles and - * pointers remain valid. User is responsible to update packet metadata - * offsets when needed. + * Following this operation packet handles and pointers remain valid. User is + * responsible to update packet metadata offsets when needed. * * @param pkt Packet handle * @param len Number of bytes to pull the head (0 ... seg_len - 1) @@ -350,9 +351,15 @@ void *odp_packet_pull_head(odp_packet_t pkt, uint32_t len); * Push out packet tail * * Increase packet data length by moving packet tail into packet tailroom. - * Packet tailroom is decreased with the same amount. The packet tail may be - * pushed out up to 'tailroom' bytes. Packet is not modified if there's not - * enough tailroom. + * Packet tailroom is decreased with the same amount. If the requested len + * exceeds the current tailroom, the packet MAY be extended with additional + * segment(s) to accommodate the push request. Note that such extension may + * change the segmentation of the packet but does not affect the packet + * handle. As a result, the entire requested length may not be contiguously + * addressable from the returned data pointer. Use odp_packet_offset() to + * obtain this information if needed. + * + * Packet is not modified if there's not enough tailroom. * * last_seg: * data_len += len @@ -362,8 +369,7 @@ void *odp_packet_pull_head(odp_packet_t pkt, uint32_t len); * tail += len * tailroom -= len * - * Operation does not modify packet segmentation or move data. Handles, - * pointers and offsets remain valid. + * Following this operation packet handles, pointers and offsets remain valid. * * @param pkt Packet handle * @param len Number of bytes to push the tail (0 ... tailroom) @@ -379,9 +385,8 @@ void *odp_packet_push_tail(odp_packet_t pkt, uint32_t len); * Pull in packet tail * * Decrease packet data length by removing data from the tail of the packet. - * Packet tailroom is increased with the same amount. Packet tail may be pulled - * in up to last segment data_len - 1 bytes. (i.e. packet tail must stay in the - * last segment). Packet is not modified if there's not enough data. + * Packet tailroom is increased with the same amount. Packet is not modified + * if there's not enough data. * * last_seg: * data_len -= len @@ -391,9 +396,8 @@ void *odp_packet_push_tail(odp_packet_t pkt, uint32_t len); * tail -= len * tailroom += len * - * Operation does not modify packet segmentation or move data. Handles and - * pointers remain valid. User is responsible to update packet metadata - * offsets when needed. + * Following this operation packet handles and pointers remain valid. User is + * responsible to update packet metadata offsets when needed. * * @param pkt Packet handle * @param len Number of bytes to pull the tail (0 ... last_seg:data_len - 1)