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.