From: Bill Fischofer <bill.fischo...@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.fischo...@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: 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)
