From patchwork Wed Oct 25 03:00:06 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: 117009 Delivered-To: patch@linaro.org Received: by 10.140.22.164 with SMTP id 33csp360827qgn; Tue, 24 Oct 2017 20:01:07 -0700 (PDT) X-Google-Smtp-Source: ABhQp+QhF7sjDu4oz+QiL+gaGgHoqc/Lsi7pTF5+UitsMWA5jskcGkXkt88eHHygxVIm0BIF0uLV X-Received: by 10.237.36.209 with SMTP id u17mr26560096qtc.14.1508900467054; Tue, 24 Oct 2017 20:01:07 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1508900467; cv=none; d=google.com; s=arc-20160816; b=v8100Ua274QLCtJSgTjTJ3BG2o3sUZZbASb7L0LZ2H7Jq83uIRSMGVk7dhQ+5WAanR K0xbg6IZMti0Mo1rBUESEzv5lIRqsyUEzpkNC9FHpbzxnRirbCN0NtKnR8tkqWjrCgEl C49zdDTQpL/+RbXGK1CyuWm/cHLD2Js7rQQge+3Lj0CRo8g4NAL1Y71uyys3ebIIOFJ9 62TphSx8x1RJflg/EHhO58UXpUjcEJ/dPJK/T+10sCA5LmG7vdsvuZkB2+/OrvQF+NRh qmh3xFDksO+3gUE0ONwvlxIeFfLDecz75ETJ3j/LqkeNhWHadj5C/Slbnb4RpOwi9SAa cOdw== 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=nE+ci/c/jNTi6Pqp5K77SuyRD4HxAw4Z0QAece56km0=; b=rPCAtbBwgkrvZPggb15PzSze+1WGXVb/VyJEURHRg/TuTi36wWT0eOhz24x+TYhqgP RB3c8gSTMpiA0OBSeecOzPddw3cyh/1tIpKWoPAe8K6VCXostSwsFaD4uouocG6IeTKy qkDTk1rirpKhY5X4qoYgwWM+BZsf+5Ls7MCatM9LHzz7z/EooFtZUvlX+hFn2JWHlOCS OL/YpY99Pd7e5iuC5oCOpnWJCQW+L8cvze2+2Rv1bmfpRgunzo+bcgXNX0NAgt9xjhtB lb/5aHoROiHkri4YhpWUXrwSBJqqfLYxiX2zelASTO4lfWveXKEszMZ4E67AKRPjf6c0 scag== 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 i22si1563385qkh.292.2017.10.24.20.01.06; Tue, 24 Oct 2017 20: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 C3F15622CF; Wed, 25 Oct 2017 03:01:06 +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 6EAB362947; Wed, 25 Oct 2017 03:00:35 +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 EC45062295; Wed, 25 Oct 2017 03:00:31 +0000 (UTC) Received: from forward100o.mail.yandex.net (forward100o.mail.yandex.net [37.140.190.180]) by lists.linaro.org (Postfix) with ESMTPS id A1DA462295 for ; Wed, 25 Oct 2017 03:00:30 +0000 (UTC) Received: from mxback15g.mail.yandex.net (mxback15g.mail.yandex.net [IPv6:2a02:6b8:0:1472:2741:0:8b7:94]) by forward100o.mail.yandex.net (Yandex) with ESMTP id 890242A2334F for ; Wed, 25 Oct 2017 06:00:29 +0300 (MSK) Received: from smtp3p.mail.yandex.net (smtp3p.mail.yandex.net [2a02:6b8:0:1472:2741:0:8b6:8]) by mxback15g.mail.yandex.net (nwsmtp/Yandex) with ESMTP id nIgVwktc5T-0TniZYNf; Wed, 25 Oct 2017 06:00:29 +0300 Received: by smtp3p.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id yZC1QPSHKA-0S3GnT9C; Wed, 25 Oct 2017 06: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 06:00:06 +0300 Message-Id: <1508900406-6923-2-git-send-email-odpbot@yandex.ru> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1508900406-6923-1-git-send-email-odpbot@yandex.ru> References: <1508900406-6923-1-git-send-email-odpbot@yandex.ru> Github-pr-num: 257 Subject: [lng-odp] [PATCH v1 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: 833bbf49a60ec88e5b4b135a20ab569c1e75c55c **/ 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..f19f9d937 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 lattitude 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)