Here is a list of all related documentation pages:

API Developer Guidelines
API Principles	SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2017 Linaro Limited Copyright (c) 2023 Nokia # ODP specification ODP specification consists of several types of files, which together provide full list of types, values and functions that ODP implementation MUST provide. ## API Principles 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) and would just crash. Many ODP component areas provide an odp_xxx_capability() API that returns platform-specific information regarding supported features in that component. For best portability applications should always use these capability APIs. ODP APIs are described using opaque data types of which definition are left up to the ODP implementation. For example, ODP packets are referenced by 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 and applications cannot make assumptions about the underlying type. Application gains ODP handle ownership when it receives it from an ODP API call. For example, application can receive an odp_event_t handle from `odp_schedule()` call. The ownership ends when the handle is passed back to ODP, for example with `odp_queue_enq()` call. Application MUST NOT use the handle anymore after it has lost the ownership. ## API headers ODP API headers are divided into the following directories. ``` include/ ├── odp_api.h └── odp/ ├── api/ │ ├── abi-default/ │ └── spec/ └── arch/ └── @ARCH_ABI@/ └── odp/ └── api/ └── abi/ platform/ └── @with_platform@/ ├── include/ └── include-abi/ └── odp/ └── api/ └── abi/ ``` ### Application header This header found at `include/odp_api.h` is an entry point for an application. Application MUST include only odp_api.h, nothing else. This file includes all files from ODP specification. ### API specification These are the files from `include/odp/api/spec` directory. They specify a set of function prototypes, types, type names, enumerations, etc. that MUST be provided by ODP implementation. Doxygen comments inside these files document the API specification. Content of some types and value of some enumerations are left undefined in API spec. These are defined either in ABI spec or implementation specific (non-ABI compatible) headers. An implementation MUST use these headers AS IS, without any modifications to be compatible with ODP specification. ### ABI compatibility specification These are the files from `include/odp/arch/@ARCH_ABI@/odp/api/abi/` directory. They specify a set of types and values that MUST be used AS IS without any modifications by an implementation if it supports and is compiled for ABI-compatibility mode. ### Default ABI headers These are the files from `include/odp/api/abi-default` directory. They provide default specification for ODP types and values for ABI compatibility. CPU architecture specific ABI compatibility files heavily depend on these headers. These files MUST NOT be changed by an implementation. ### Additional API headers These are the files from `include/odp/api` directory. They glue together API and ABI specification headers. Although they are not part of ODP specification itself, they provide an easy way for an implementation to use ODP API/ABI header files. An implementation SHOULD use these headers AS IS unless it has strong reason not to do so. ## Platform-specific headers ### Platform ABI headers These are the headers found at `platform/@with_platform@/include-abi/odp/api/abi` directory. They are used by the rest of ODP code if implementation is compiled with ABI compatibility disabled. They should implement at least a set of types and values documented in ODP API specification headers. They are permitted to provide any platform specific optimizations (i.e. they might provide types and/or values that map directly onto the hardware details, they might provide inline functions to speed up execution of the application, etc.). These headers MAY use ODP default ABI headers if they do fit. ### Additional platform-specific headers Platform MAY provide additional headers at `platform/@with_platform/include`. However, these headers SHOULD NOT be used directly by an application, because this will tie it to the exact implementation details. Application MUST include only <odp_api.h> header. Platform ABI headers MAY use these headers to implement platform-specific optimizations.
Contributing Guidelines	:doctitle: OpenDataPlane (ODP) CONTRIBUTING :description: This document is intended to guide a new application developer + in understanding the contributing requirements for ODP :imagesdir: ../images :toc: :numbered!: [abstract] == Abstract This document is intended to guide a new application developer in understanding the contributing requirements for ODP == New Development ODP code shall be written with the kernel coding style https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst[Kernel Coding Style] ODP code shall be documented using the doxygen style described in the "Documenting the code" section. Check patch script/checkpatch.pl shall be used before submitting a patch. == ODP patch expectations as an open source project While specific to the Linux kernel development, the following reference could also be considered a general guide for any Open Source development http://ldn.linuxfoundation.org/book/how-participate-linux-community[Participating in the Community] and is relevant to ODP. Many of the guidelines in this ODP document are related to the items in that information. Pay particular attention to section 5.3 that talks about patch preparation. The key thing to remember is to break up your changes into logical sections. Otherwise you run the risk of not being able to even explain the purpose of a change in the patch headers! In addition section 5.4 explains the purpose of the Signed-off-by: tag line as discussed in later parts of this document. Due to the importance of the Signed-off-by: tag line a copy of the description follows: Signed-off-by: this is a developer's certification that he or she has the right to submit the patch for inclusion into the [project]. It is an agreement to the Developer's Certificate of Origin, the full text of which can be found in https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst[Submitting Patches] Code without a proper signoff cannot be merged into the mainline. == Common Errors in Patch and Commit Messages - Avoid starting the summary line with a capital letter, unless the component being referred to also begins with a capital letter. - Don't have one huge patch, split your change into logical subparts. It's easier to track down problems afterward using tools such as git bisect. It also makes it easy for people to cherry-pick changes into things like stable branches. - Don't simply translate your change into English for a commit log. The log "Change compare from zero to one" is bad because it describes only the code change in the patch; we can see that from reading the patch itself. Let the code tell the story of the mechanics of the change (as much as possible), and let your comment tell the other details -- i.e. what the problem was, how it manifested itself (symptoms), and if necessary, the justification for why the fix was done in manner that it was. In other words, the long commit message must describe why the change was needed (instead of what has changed). - Don't start your commit log with "This patch..." -- we already know it is a patch. - Don't repeat your short log in the long log. If you really really don't have anything new and informational to add in as a long log, then don't put a long log at all. This should be uncommon -- i.e. the only acceptable cases for no long log would be something like: "Documentation/README: Fix spelling mistakes". - Don't put absolute paths to source files that are specific to your site. - Always use the most significant ramification of the change in the words of your subject/shortlog. For example, don't say "fix compile warning in foo" when the compiler warning was really telling us that we were dereferencing complete garbage off in the weeds that could in theory cause an OOPS under some circumstances. When people are choosing commits for backports to stable or distro kernels, the shortlog will be what they use for an initial sorting selection. If they see "Fix possible OOPS in...." then these people will look closer, whereas they most likely will skip over simple warning fixes. - Don't put in the full 20 or more lines of a backtrace when really it is just the last 5 or so function calls that are relevant to the crash/fix. If the entry point, or start of the trace is relevant (i.e. a syscall or similar), you can leave that, and then replace a chunk of the intermediate calls in the middle with a single [...] - Don't include timestamps or other unnecessary information, unless they are relevant to the situation (i.e. indicating an unacceptable delay in a driver initialization etc.) - Don't use links to temporary resources like pastebin and friends. The commit message may be read long after this resource timed out. - Don't reference mirrors, but instead always reference original authoritative sources. - Avoid punctuation in the short log. == Documenting - References to wikipedia are not permitted. === Documenting the code - Allow doxygen to use all its default behaviors to identify tagged information but where a doxygen tag must be specified use @ - The first line is by default the brief summary. - The next paragraph is by default the detailed summary - Doxygen shall generate the layout, no additional formatting should be inserted - Normal comment sections should be before the code block and start with /** on its own line and finish with / on its own line. The exception to this rule is a case where the comment is very small, for example [source,doxygen] ---- /* macro description / #define SOME_MACRO 0 ---- - Commenting on the end of a line for macros and struct members is allowed using: /< <text> / for example [source,doxygen] ---- #define SOME_MACRO 0 /*< <text> / ---- - Files should start with a files description using @file - Functions should specify their parameters with @param[in] and @param[out] - Functions return values should all be specified using @return or @retval - There should be no doxygen warnings or errors generated. === Documenting the user docs - Users guides are stored in asciidoctor format in the odp/docs directory and in sub directories of it as appropriate. - ODP code references such as types and enums are highlighted using the ` syntax. For example text referring to the type odp_pktio_t would decorate the type thus: [source,asciidoc] ---- `odp_pktio_t` ---- - Section heading use the = syntax. For example:- [source,asciidoc] ---- == Level 1 Text. === Level 2 Text. ---- - Code and scripting excerpts are decorated with the block syntax:- [source,asciidoc] ---- .Optional Title [source,perl] ---- <code here> ---- ---- - Images are decorated with :- [source,asciidoc] ---- .Optional Title image::../<image name>.svg[align="center"] ---- - The images are stored in the doc/images directory as svg files, src for image generators such as .gv and .msg should also render to .svg - Body text shall wrap at the 80 char point. - No warnings may be generated by the asciidoctor tool.
Release Management
Deprecated List