diff mbox series

[v2,1/1] doc: userguide: add section on api specification principles

Message ID 1508904005-8012-2-git-send-email-odpbot@yandex.ru
State New
Headers show
Series [v2,1/1] doc: userguide: add section on api specification principles | expand

Commit Message

Github ODP bot Oct. 25, 2017, 4 a.m. UTC 
From: Bill Fischofer <bill.fischofer@linaro.org>


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 <bill.fischofer@linaro.org>

---
/** 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 mbox series

Patch

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)