From patchwork Thu Nov 26 18:55:57 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Zoltan Kiss X-Patchwork-Id: 57336 Delivered-To: patch@linaro.org Received: by 10.112.155.196 with SMTP id vy4csp678443lbb; Thu, 26 Nov 2015 10:56:18 -0800 (PST) X-Received: by 10.140.33.139 with SMTP id j11mr48841795qgj.49.1448564178041; Thu, 26 Nov 2015 10:56:18 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id b43si1038745qga.13.2015.11.26.10.56.17; Thu, 26 Nov 2015 10:56:17 -0800 (PST) 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; dkim=neutral (body hash did not verify) header.i=@linaro-org.20150623.gappssmtp.com Received: by lists.linaro.org (Postfix, from userid 109) id 4FBCE61A38; Thu, 26 Nov 2015 18:56: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.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID, 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 CB98D61971; Thu, 26 Nov 2015 18:56:12 +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 E4D64619C1; Thu, 26 Nov 2015 18:56:10 +0000 (UTC) Received: from mail-wm0-f53.google.com (mail-wm0-f53.google.com [74.125.82.53]) by lists.linaro.org (Postfix) with ESMTPS id 09DB2610F4 for ; Thu, 26 Nov 2015 18:56:10 +0000 (UTC) Received: by wmuu63 with SMTP id u63so31550424wmu.0 for ; Thu, 26 Nov 2015 10:56:09 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro-org.20150623.gappssmtp.com; s=20150623; h=from:to:subject:date:message-id; bh=4UAWUOKN40FpeC2e596taWTOAgIcPw1RNS27c8wGu8U=; b=KdUOVONky6hdTHktfr/NGbrLrlhfkI3U5dOjzkqiwqLl/8h7YFIUZRaS6pij2f2UcA doAufUHtJ07uMjS4DiDRCodZ+FpX5NR0T79t8q6rstO0YJlwt12dyc1bmK4VCesSGKum AG4s4BwuYiYc3Dlp5rEYkqve1pKixlwxlskoFZcLypySKzuAf+8lrThC3x/kD1zxJ0cd OCCJEyQKh1F/3mhW9jLo75bKtGbmgUEH42coJQZ01FAgvtj0n5g8HFBL+A44cDfRDzt1 oO8yWYadzyY315TKqyH9/8sQpm/AdudKOBc1a8+NvrH/F/XhhDBb5GJcdOoOxrSZWXvL zwRA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:subject:date:message-id; bh=4UAWUOKN40FpeC2e596taWTOAgIcPw1RNS27c8wGu8U=; b=kpmNiLLh5U3DktN1lppIIvlpKBO/Eddpb+fsC2CDpb8OBwtak98EJwQPObh6SeXMSG gvd036ZUB6nx7wFNSncRiOcFyjC0H2ruyeFB2AiTiDTxtYvgO6caIAleKTWODHevudIi aYpGkjvah4EX41I9mI32vOA0ImS1gNJC2eiYv9tMcSulveX6yv+WkmonKupWn4bAy23N qov8hNgVIM/dTS1hNJFkC+BlwRIapkv+YylL2ELbJ9fq4EboDSl7bglJ2+8ssDKJ4Ity mbW1EYtkwsQWqGBAPcJr7uIRWdMMYZ5wVIXdSHJgi+EZtC2p4noO78+P3XG9bnptEuDK oF8Q== X-Gm-Message-State: ALoCoQlmWO+1bkEgtNMxrDf33wojLkWisqhiTXRUBSIDg7187ueY7fLuv9YxEg9jDyEA6b44NGag X-Received: by 10.28.30.206 with SMTP id e197mr5174955wme.97.1448564169244; Thu, 26 Nov 2015 10:56:09 -0800 (PST) Received: from localhost.localdomain ([90.152.119.35]) by smtp.googlemail.com with ESMTPSA id kj3sm29400954wjb.19.2015.11.26.10.56.08 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 26 Nov 2015 10:56:08 -0800 (PST) From: Zoltan Kiss To: lng-odp@lists.linaro.org, petri.savolainen@nokia.com Date: Thu, 26 Nov 2015 18:55:57 +0000 Message-Id: <1448564157-13088-1-git-send-email-zoltan.kiss@linaro.org> X-Mailer: git-send-email 1.9.1 X-Topics: patch Subject: [lng-odp] [API-NEXT PATCH] api: pool: clarify user area initializer usage 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" Clarify when exactly the function should be called by a platform, and what is promised about the data modified by it. Signed-off-by: Zoltan Kiss --- Petri, please review this before 1.5. It contains the code I quoted in my answer to the original thread. This lingers around for 3 months now, it would be good to put an end to it. The lines were left intentionally unwrapped to ease review. I'll send an wrapped version once it gets reviewed. diff --git a/include/odp/api/packet.h b/include/odp/api/packet.h index 8651a47..45ff1cb 100644 --- a/include/odp/api/packet.h +++ b/include/odp/api/packet.h @@ -94,8 +94,9 @@ extern "C" { * the ODP_CONFIG_PACKET_HEADROOM and ODP_CONFIG_PACKET_TAILROOM defines in * odp_config.h. * @note Data changed in user area might be preserved by the platform from - * previous usage of the buffer, so values preset in uarea_init() are not - * guaranteed. + * previous usage of the packet (if the underlying memory were allocated at pool + * creation time), so values preset by packet pool parameter *uarea_init() are + * only guaranteed to be known if the application never changes them. */ odp_packet_t odp_packet_alloc(odp_pool_t pool, uint32_t len); diff --git a/include/odp/api/pool.h b/include/odp/api/pool.h index 01f770f..a7bce82 100644 --- a/include/odp/api/pool.h +++ b/include/odp/api/pool.h @@ -47,14 +47,19 @@ extern "C" { * @param pkt Handle of the packet * @param uarea_init_arg Opaque pointer defined in odp_pool_param_t * - * @note If the application specifies this pointer, it expects that every buffer - * is initialized exactly once with it when the underlying memory is allocated. + * @note If the application specifies this pointer, it expects that every packet handle's user area + * is initialised exactly once with it after the underlying memory is allocated and initialized. * It is not called from odp_packet_alloc(), unless the platform chooses to - * allocate the memory at that point. Applications can only assume that this + * allocate (or initialize) the memory at that point. Applications can only assume that this * callback is called once before the packet is first used. Any subsequent * change to the user area might be preserved after odp_packet_free() is called, - * so applications should take care of (re)initialization if they change data + * so applications should not change data * preset by this function. + * @note The packet is not in use when this function is called, so only the + * following functions could be called by the init function with this handle: + * odp_packet_pool() + * odp_packet_user_area() + * odp_packet_user_area_size() */ typedef void (odp_packet_uarea_init_t)(odp_packet_t pkt, void *uarea_init_arg);