From patchwork Wed Oct 25 04:00:05 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Github ODP bot X-Patchwork-Id: 117010 Delivered-To: patch@linaro.org Received: by 10.140.22.164 with SMTP id 33csp397747qgn; Tue, 24 Oct 2017 21:01:07 -0700 (PDT) X-Google-Smtp-Source: ABhQp+SimjzypBlsQIvm1dVtnTpEKcxWUxxC7DiEXrRfMa5e6vPJY3rKQ7l9XSyN07kDKZrQgH8C X-Received: by 10.55.159.77 with SMTP id i74mr1138414qke.329.1508904067851; Tue, 24 Oct 2017 21:01:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1508904067; cv=none; d=google.com; s=arc-20160816; b=b+TYoizQ38+Sf39m+DBjMM6Ijal40KxiTQk+Zcammb8OpXfBdfNgor/wpjQE4FSKEB Amc9F1wiVsWGPBHNjusCfxdvBQTVY36mGFGd9NmFk37b40pkM9lUOqby7b8L2/3nTbUx VG9txbK3Hzk4Rii3C0InQagtZtdoAZNgnYlswY8CfMHtMzhCpOAs42pLawif0rWF06G1 hAwwFCw0M+bXxvnGapt2RZyVd95gv2zOW6to2KyBw45qjlOZQohhOzd7tw+qX/2qzeaP LCxOOv2JjDrgVlDKLeyxs8SK+RPsjyOyA0rSMHpd1LR/YsDlmpoWqUTmBIJoSxR28yKk hUeA== 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=Ml313a9TpcaEEULqOr8ixUogWctK/jYpwoFM+gLTfS0=; b=aaoEc4i2nbjfMdaPk07gm9abXSnK1m5Edj7iWTWH83hokWIComW/xuuJDjG1DypdU3 HIViyq1ogYBFVuFgyjG6kMnd58I5xOZuKhuklcpjEHLerbSa6bD38wDfxKXPkwUR/0rm lPDsVztNXzsLX4mhU1ndZXbt39+i2Kc8hzPD3Nvyq0H57JY1EPBse0o7Rgrg0qp/10OW 2TyLY167II2hJOfr3zmquyH7gHifFN22qz+w1QQMas2bK3d5WX9HyFjbD5HnUrYm/o7O RZARR5quUeCOl05ZCWLbf/HOqdCAstXw6//NfaqhnPuiDmZQR/OCzqMEyAoTh82m3hCP QsRw== 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 e5si1554491qkf.27.2017.10.24.21.01.07; Tue, 24 Oct 2017 21:01:07 -0700 (PDT) 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 82EF46294D; Wed, 25 Oct 2017 04:01:07 +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_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 C30B162951; Wed, 25 Oct 2017 04:00:41 +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 8329D6294F; Wed, 25 Oct 2017 04:00:35 +0000 (UTC) Received: from forward103p.mail.yandex.net (forward103p.mail.yandex.net [77.88.28.106]) by lists.linaro.org (Postfix) with ESMTPS id 88C7260D73 for ; Wed, 25 Oct 2017 04:00:33 +0000 (UTC) Received: from mxback16j.mail.yandex.net (mxback16j.mail.yandex.net [IPv6:2a02:6b8:0:1619::92]) by forward103p.mail.yandex.net (Yandex) with ESMTP id 64874218414C for ; Wed, 25 Oct 2017 07:00:29 +0300 (MSK) Received: from smtp1p.mail.yandex.net (smtp1p.mail.yandex.net [2a02:6b8:0:1472:2741:0:8b6:6]) by mxback16j.mail.yandex.net (nwsmtp/Yandex) with ESMTP id z41gdmbJ59-0TU8GgaI; Wed, 25 Oct 2017 07:00:29 +0300 Received: by smtp1p.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id wG1VrSTp3j-0SNCMcKW; Wed, 25 Oct 2017 07:00:28 +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: Wed, 25 Oct 2017 07:00:05 +0300 Message-Id: <1508904005-8012-2-git-send-email-odpbot@yandex.ru> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1508904005-8012-1-git-send-email-odpbot@yandex.ru> References: <1508904005-8012-1-git-send-email-odpbot@yandex.ru> Github-pr-num: 257 Subject: [lng-odp] [PATCH v2 1/1] doc: userguide: add section on api specification principles 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: Bill Fischofer Add section to the User Guide that highlights that unless otherwise documented, API behavior is undefined if applications pass invalid parameters to them. Signed-off-by: Bill Fischofer --- /** Email created from pull request 257 (Bill-Fischofer-Linaro:api-usage-doc) ** https://github.com/Linaro/odp/pull/257 ** Patch: https://github.com/Linaro/odp/pull/257.patch ** Base sha: e826613858543e50a2ec74598f8c2c6fd4bfa064 ** Merge commit sha: 170459d661a78366fe3a32451ad377cb38b3f08b **/ doc/users-guide/users-guide.adoc | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 18d8cb8fb..0d1e5eb78 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -40,11 +40,29 @@ by abstract handles of type `odp_packet_t`, and packet-related APIs take arguments of this type. What an `odp_packet_t` actually is is not part of the ODP API specification--that is the responsibility of each ODP implementation. +.API Specification Principles +The ODP API specification is designed to permit wide latitude on the part of +implementations while at the same time supporting highly efficient processing, +especially for APIs that are executed frequently. + +Both applications and implementations must comply with the API +specification. If not otherwise documented, results are undefined if an +application acts against the specification. For example, if an application +passes bad parameters to an ODP API one implementation may report an error, +while another may not check them (to maximize performance) but would just +crash while using the bad values. + +Note that many ODP component areas provide an `odp_xxx_capability()` API that +returns platform-specific information regarding valid input to other APIs in +that component. For best portability applications should always use these +capability APIs to determine valid parameter input. + .Summary: ODP API attributes: * Open Source, open contribution, BSD-3 licensed. * Vendor and platform neutral. * Application-centric. Covers functional needs of data plane applications. * Ensures portability by specifying the functional behavior of ODP. +* Both applications and implementations must conform to the API specification. * Defined jointly and openly by application writers and platform implementers. * Architected to be implementable on a wide range of platforms efficiently * Sponsored, governed, and maintained by the Linaro Networking Group (LNG)