diff options
Diffstat (limited to 'include/odp/api')
| -rw-r--r-- | include/odp/api/abi-default/dma_types.h | 48 | ||||
| -rw-r--r-- | include/odp/api/abi-default/event.h | 1 | ||||
| -rw-r--r-- | include/odp/api/abi-default/timer_types.h (renamed from include/odp/api/abi-default/timer.h) | 4 | ||||
| -rw-r--r-- | include/odp/api/dma.h | 26 | ||||
| -rw-r--r-- | include/odp/api/dma_types.h | 28 | ||||
| -rw-r--r-- | include/odp/api/spec/classification.h | 10 | ||||
| -rw-r--r-- | include/odp/api/spec/crypto.h | 3 | ||||
| -rw-r--r-- | include/odp/api/spec/dma.h | 354 | ||||
| -rw-r--r-- | include/odp/api/spec/dma_types.h | 547 | ||||
| -rw-r--r-- | include/odp/api/spec/event.h | 2 | ||||
| -rw-r--r-- | include/odp/api/spec/ipsec.h | 16 | ||||
| -rw-r--r-- | include/odp/api/spec/packet_io.h | 7 | ||||
| -rw-r--r-- | include/odp/api/spec/pool_types.h | 12 | ||||
| -rw-r--r-- | include/odp/api/spec/random.h | 2 | ||||
| -rw-r--r-- | include/odp/api/spec/shared_memory.h | 24 | ||||
| -rw-r--r-- | include/odp/api/spec/std_types.h | 3 | ||||
| -rw-r--r-- | include/odp/api/spec/timer.h | 337 | ||||
| -rw-r--r-- | include/odp/api/spec/timer_types.h | 359 | ||||
| -rw-r--r-- | include/odp/api/timer.h | 6 | ||||
| -rw-r--r-- | include/odp/api/timer_types.h | 28 |
20 files changed, 1479 insertions, 338 deletions
diff --git a/include/odp/api/abi-default/dma_types.h b/include/odp/api/abi-default/dma_types.h new file mode 100644 index 000000000..c2b0eca64 --- /dev/null +++ b/include/odp/api/abi-default/dma_types.h @@ -0,0 +1,48 @@ +/* Copyright (c) 2021, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#ifndef ODP_ABI_DMA_TYPES_H_ +#define ODP_ABI_DMA_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <stdint.h> + +/** @internal Dummy type for strong typing */ +typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_dma_t; + +/** @internal Dummy type for strong typing */ +typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_dma_compl_t; + +/** @ingroup odp_dma + * @{ + */ + +typedef _odp_abi_dma_t *odp_dma_t; + +#define ODP_DMA_INVALID ((odp_dma_t)0) + +typedef _odp_abi_dma_t *odp_dma_compl_t; + +#define ODP_DMA_COMPL_INVALID ((odp_dma_compl_t)0) + +typedef uint32_t odp_dma_transfer_id_t; + +#define ODP_DMA_TRANSFER_ID_INVALID ((odp_dma_transfer_id_t)0) + +#define ODP_DMA_NAME_LEN 32 + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/abi-default/event.h b/include/odp/api/abi-default/event.h index 8976252f3..ecedda3bd 100644 --- a/include/odp/api/abi-default/event.h +++ b/include/odp/api/abi-default/event.h @@ -32,6 +32,7 @@ typedef enum { ODP_EVENT_IPSEC_STATUS = 5, ODP_EVENT_PACKET_VECTOR = 6, ODP_EVENT_PACKET_TX_COMPL = 7, + ODP_EVENT_DMA_COMPL = 8, } odp_event_type_t; typedef enum { diff --git a/include/odp/api/abi-default/timer.h b/include/odp/api/abi-default/timer_types.h index 566d199e0..a653dcbaa 100644 --- a/include/odp/api/abi-default/timer.h +++ b/include/odp/api/abi-default/timer_types.h @@ -10,8 +10,8 @@ * ODP timer service */ -#ifndef ODP_ABI_TIMER_H_ -#define ODP_ABI_TIMER_H_ +#ifndef ODP_ABI_TIMER_TYPES_H_ +#define ODP_ABI_TIMER_TYPES_H_ #ifdef __cplusplus extern "C" { diff --git a/include/odp/api/dma.h b/include/odp/api/dma.h new file mode 100644 index 000000000..4720f57c9 --- /dev/null +++ b/include/odp/api/dma.h @@ -0,0 +1,26 @@ +/* Copyright (c) 2021, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP DMA + */ + +#ifndef ODP_API_DMA_H_ +#define ODP_API_DMA_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/spec/dma.h> + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/dma_types.h b/include/odp/api/dma_types.h new file mode 100644 index 000000000..4a51371b4 --- /dev/null +++ b/include/odp/api/dma_types.h @@ -0,0 +1,28 @@ +/* Copyright (c) 2021, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP DMA + */ + +#ifndef ODP_API_DMA_TYPES_H_ +#define ODP_API_DMA_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/abi/dma_types.h> + +#include <odp/api/spec/dma_types.h> + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/spec/classification.h b/include/odp/api/spec/classification.h index ec15c8962..633963692 100644 --- a/include/odp/api/spec/classification.h +++ b/include/odp/api/spec/classification.h @@ -149,7 +149,8 @@ typedef union odp_cls_pmr_terms_t { typedef struct odp_red_param_t { /** A boolean to enable RED * When true, RED is enabled and configured with RED parameters. - * Otherwise, RED parameters are ignored. */ + * Otherwise, RED parameters are ignored. Default value is false. + */ odp_bool_t enable; /** Threshold parameters for RED @@ -166,7 +167,8 @@ typedef struct odp_red_param_t { typedef struct odp_bp_param_t { /** A boolean to enable Back pressure * When true, back pressure is enabled and configured with the BP - * parameters. Otherwise BP parameters are ignored. + * parameters. Otherwise BP parameters are ignored. Default value + * is false. */ odp_bool_t enable; @@ -329,6 +331,8 @@ typedef struct odp_cls_cos_param { * the class of service. * Depending on the implementation this number might be rounded-off to * nearest supported value (e.g power of 2) + * + * Default value is 1. */ uint32_t num_queue; @@ -695,7 +699,7 @@ typedef struct odp_pmr_param_t { /** Packet Matching Rule term */ odp_cls_pmr_term_t term; - /** True if the value is range and false if match */ + /** True if the value is range and false if match. Default is false. */ odp_bool_t range_term; /** Variant mappings for types of matches */ diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h index bfda0bcee..d3e3c9a07 100644 --- a/include/odp/api/spec/crypto.h +++ b/include/odp/api/spec/crypto.h @@ -1053,6 +1053,9 @@ int odp_crypto_auth_capability(odp_auth_alg_t auth, * default values. If call ends up with an error no new session will be * created. * + * The parameter structure as well as the key and IV data pointed to by it + * can be freed after the call. + * * @param param Session parameters * @param[out] session Created session else ODP_CRYPTO_SESSION_INVALID * @param[out] status Failure code if unsuccessful diff --git a/include/odp/api/spec/dma.h b/include/odp/api/spec/dma.h new file mode 100644 index 000000000..8ca506291 --- /dev/null +++ b/include/odp/api/spec/dma.h @@ -0,0 +1,354 @@ +/* Copyright (c) 2021, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP DMA + */ + +#ifndef ODP_API_SPEC_DMA_H_ +#define ODP_API_SPEC_DMA_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/dma_types.h> + +/** @addtogroup odp_dma + * @{ + */ + +/** + * Query DMA capabilities + * + * Outputs DMA capabilities on success. + * + * @param[out] capa Pointer to a capability structure for output + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_dma_capability(odp_dma_capability_t *capa); + +/** + * Initialize DMA session parameters + * + * Initialize an odp_dma_param_t to its default values. + * + * @param[out] param Parameter structure to be initialized + */ +void odp_dma_param_init(odp_dma_param_t *param); + +/** + * Create DMA session + * + * @param name DMA session name or NULL. Maximum string length is ODP_DMA_NAME_LEN. + * @param param DMA session parameters + * + * @return DMA session handle on success + * @retval ODP_DMA_INVALID on failure + */ +odp_dma_t odp_dma_create(const char *name, const odp_dma_param_t *param); + +/** + * Destroy DMA session + * + * A DMA session may be destroyed only when there are no active transfers in the session (all + * previously started transfers have completed). + * + * @param dma DMA session to be destroyed + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_dma_destroy(odp_dma_t dma); + +/** + * Find DMA session by name + * + * @param name DMA session name + * + * @return Handle of the first matching DMA session + * @retval ODP_DMA_INVALID DMA session could not be found + */ +odp_dma_t odp_dma_lookup(const char *name); + +/** + * Initialize DMA transfer parameters + * + * Initialize an odp_dma_transfer_param_t to its default values. + * + * @param[out] trs_param Parameter structure to be initialized + */ +void odp_dma_transfer_param_init(odp_dma_transfer_param_t *trs_param); + +/** + * Initialize DMA transfer completion parameters + * + * Initialize an odp_dma_compl_param_t to its default values. + * + * @param[out] compl_param Parameter structure to be initialized + */ +void odp_dma_compl_param_init(odp_dma_compl_param_t *compl_param); + +/** + * Perform DMA transfer + * + * Performs DMA transfer according to the session and transfer parameters. Returns 1 when + * the transfer was completed successfully. Returns 0 when the transfer was not performed + * due to resources being temporarily busy. In this case, the same transfer is likely to succeed + * after enough resources are available. Returns <0 on failure. + * + * The call outputs optionally transfer results on a non-zero return value. Use NULL as 'result' + * pointer if results are not required. + * + * @param dma DMA session + * @param trs_param Transfer parameters + * @param[out] result Pointer to transfer result structure for output, or NULL when not used + * + * @retval 1 when transfer completed successfully + * @retval 0 when resources are busy and transfer was not performed + * @retval <0 on failure + */ +int odp_dma_transfer(odp_dma_t dma, const odp_dma_transfer_param_t *trs_param, + odp_dma_result_t *result); + +/** + * Perform multiple DMA transfers + * + * Like odp_dma_transfer(), but performs 'num' transfers. + * + * @param dma DMA session + * @param trs_param Array of transfer parameter pointers + * @param[out] result Array of transfer result pointers for output, or NULL when not used + * @param num Number of transfers to perform. Both arrays have this many elements. + * + * @return Number of transfers completed successfully (1 ... num) + * @retval 0 when resources are busy and no transfers were performed + * @retval <0 on failure + */ +int odp_dma_transfer_multi(odp_dma_t dma, const odp_dma_transfer_param_t *trs_param[], + odp_dma_result_t *result[], int num); + +/** + * Start DMA transfer + * + * Starts asynchronous DMA transfer according to the session and transfer parameters. + * Completion parameters specify how transfer completion is reported. Returns 1 when the transfer + * was started successfully. Returns 0 when the transfer was not started due to resources being + * temporarily busy. In this case, the same transfer is likely to start successfully after enough + * resources are available. Returns <0 on failure. + * + * @param dma DMA session + * @param trs_param Transfer parameters + * @param compl_param Transfer completion parameters + * + * @retval 1 when transfer started successfully + * @retval 0 when resources are busy and transfer was not started + * @retval <0 on failure + * + * @see odp_dma_transfer_id_alloc(), odp_dma_transfer_done(), odp_dma_compl_result() + */ +int odp_dma_transfer_start(odp_dma_t dma, const odp_dma_transfer_param_t *trs_param, + const odp_dma_compl_param_t *compl_param); + +/** + * Start multiple DMA transfers + * + * Like odp_dma_transfer_start(), but starts 'num' transfers. + * + * @param dma DMA session + * @param trs_param Array of transfer parameter pointers + * @param compl_param Array of transfer completion parameter pointers + * @param num Number of transfers to start. Both parameter arrays have this many elements. + * + * @return Number of transfers started successfully (1 ... num) + * @retval 0 when resources are busy and no transfers were started + * @retval <0 on failure + */ +int odp_dma_transfer_start_multi(odp_dma_t dma, const odp_dma_transfer_param_t *trs_param[], + const odp_dma_compl_param_t *compl_param[], int num); + +/** + * Check if DMA transfer has completed + * + * Application must call this function for every transfer that was started in ODP_DMA_COMPL_POLL + * mode until a non-zero value is returned. The transfer identifier from completion parameters of + * the transfer start call is used. When a non-zero value is returned, the transfer is complete + * and the identifier may be freed or reused for another transfer. + * + * The call outputs optionally transfer results on a non-zero return value. Use NULL as 'result' + * pointer if results are not required. + * + * @param dma DMA session + * @param transfer_id Transfer identifier + * @param[out] result Pointer to transfer result structure for output, or NULL when not used. + * + * @retval 0 transfer has not finished + * @retval >0 transfer has finished successfully + * @retval <0 on failure + */ +int odp_dma_transfer_done(odp_dma_t dma, odp_dma_transfer_id_t transfer_id, + odp_dma_result_t *result); + +/** + * Allocate DMA transfer identifier + * + * Transfer identifiers are used in #ODP_DMA_COMPL_POLL mode. It identifies a previously started + * transfer for an odp_dma_transfer_done() call. The maximum number of transfer identifiers is + * implementation specific, but there are at least odp_dma_capability_t::max_transfers identifiers + * per session. + * + * @param dma DMA session + * + * @return Transfer identifier + * @retval ODP_DMA_TRANSFER_ID_INVALID Transfer identifier could not be allocated + */ +odp_dma_transfer_id_t odp_dma_transfer_id_alloc(odp_dma_t dma); + +/** + * Free DMA transfer identifier + * + * @param dma DMA session + * @param transfer_id DMA transfer identifier to be freed + */ +void odp_dma_transfer_id_free(odp_dma_t dma, odp_dma_transfer_id_t transfer_id); + +/** + * Get printable value for DMA session handle + * + * @param dma Handle to be converted for debugging + * + * @return uint64_t value that can be used to print/display this handle + */ +uint64_t odp_dma_to_u64(odp_dma_t dma); + +/** + * Print debug info about DMA session + * + * Print implementation defined information about DMA session to the ODP log. + * The information is intended to be used for debugging. + * + * @param dma DMA session handle + */ +void odp_dma_print(odp_dma_t dma); + +/** + * Check DMA completion event + * + * Reads DMA completion event (ODP_EVENT_DMA_COMPL), and returns if the transfer succeeded or + * failed. The call outputs optionally transfer results. Use NULL as 'result' pointer if results + * are not required. + * + * @param dma_compl DMA completion event + * @param[out] result Pointer to transfer result structure for output, or NULL when not used. + * + * @retval 0 Transfer was successful + * @retval <0 Transfer failed + */ +int odp_dma_compl_result(odp_dma_compl_t dma_compl, odp_dma_result_t *result); + +/** + * Convert event to DMA completion event + * + * Converts an ODP_EVENT_DMA_COMPL type event to a DMA completion event. + * + * @param ev Event handle + * + * @return DMA completion event handle + */ +odp_dma_compl_t odp_dma_compl_from_event(odp_event_t ev); + +/** + * Convert DMA completion event to event + * + * @param dma_compl DMA completion event handle + * + * @return Event handle + */ +odp_event_t odp_dma_compl_to_event(odp_dma_compl_t dma_compl); + +/** + * Get printable value for DMA completion event handle + * + * @param dma_compl Handle to be converted for debugging + * + * @return uint64_t value that can be used to print/display this handle + */ +uint64_t odp_dma_compl_to_u64(odp_dma_compl_t dma_compl); + +/** + * Allocate DMA completion event + * + * Allocates a DMA completion event from a pool. The pool must have been created with + * odp_dma_pool_create() call. All completion event metadata are set to their default values. + * + * @param pool Pool handle + * + * @return DMA completion event handle + * @retval ODP_DMA_COMPL_INVALID Completion event could not be allocated + */ +odp_dma_compl_t odp_dma_compl_alloc(odp_pool_t pool); + +/** + * Free DMA completion event + * + * Frees a DMA completion event into the pool it was allocated from. + * + * @param dma_compl DMA completion event handle + */ +void odp_dma_compl_free(odp_dma_compl_t dma_compl); + +/** + * Print DMA completion event debug information + * + * Prints implementation specific debug information about + * the completion event to the ODP log. + * + * @param dma_compl DMA completion event handle + */ +void odp_dma_compl_print(odp_dma_compl_t dma_compl); + +/** + * Initialize DMA completion event pool parameters + * + * Initialize an odp_dma_pool_param_t to its default values. + * + * @param[out] pool_param Parameter structure to be initialized + */ +void odp_dma_pool_param_init(odp_dma_pool_param_t *pool_param); + +/** + * Create DMA completion event pool + * + * Creates a pool of DMA completion events (ODP_EVENT_DMA_COMPL). Pool type is ODP_POOL_DMA_COMPL. + * The use of pool name is optional. Unique names are not required. However, odp_pool_lookup() + * returns only a single matching pool. Use odp_dma_pool_param_init() to initialize pool parameters + * into their default values. Parameters values must not exceed pool capabilities + * (@see odp_dma_pool_capability_t) + * + * @param name Name of the pool or NULL. Maximum string length is ODP_POOL_NAME_LEN. + * @param pool_param Pool parameters + * + * @return Handle of the created pool + * @retval ODP_POOL_INVALID Pool could not be created + */ +odp_pool_t odp_dma_pool_create(const char *name, const odp_dma_pool_param_t *pool_param); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif + diff --git a/include/odp/api/spec/dma_types.h b/include/odp/api/spec/dma_types.h new file mode 100644 index 000000000..563955395 --- /dev/null +++ b/include/odp/api/spec/dma_types.h @@ -0,0 +1,547 @@ +/* Copyright (c) 2021, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP DMA + */ + +#ifndef ODP_API_SPEC_DMA_TYPES_H_ +#define ODP_API_SPEC_DMA_TYPES_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/std_types.h> + +/** @defgroup odp_dma ODP DMA + * DMA offload + * @{ + */ + +/** + * @typedef odp_dma_t + * DMA session + */ + +/** + * @typedef odp_dma_transfer_id_t + * DMA transfer identifier + */ + +/** + * @typedef odp_dma_compl_t + * DMA completion event + */ + +/** + * @def ODP_DMA_INVALID + * Invalid DMA session + */ + +/** + * @def ODP_DMA_TRANSFER_ID_INVALID + * Invalid DMA transfer identifier + */ + +/** + * @def ODP_DMA_COMPL_INVALID + * Invalid DMA completion event + */ + +/** + * @def ODP_DMA_NAME_LEN + * Maximum DMA name length in chars including null char + */ + +/** + * DMA completion event pool capabilities + * + * Pool statistics are not supported with DMA completion event pools. + */ +typedef struct odp_dma_pool_capability_t { + /** Maximum number of DMA completion event pools */ + uint32_t max_pools; + + /** Maximum number of DMA completion events in a pool */ + uint32_t max_num; + + /** Minimum size of thread local cache */ + uint32_t min_cache_size; + + /** Maximum size of thread local cache */ + uint32_t max_cache_size; + +} odp_dma_pool_capability_t; + +/** + * DMA completion event pool parameters + */ +typedef struct odp_dma_pool_param_t { + /** Number of DMA completion events in the pool + * + * Maximum value is defined by 'max_num' pool capability */ + uint32_t num; + + /** Maximum number of events cached locally per thread + * + * See odp_pool_param_t::cache_size documentation for details. Valid values range from + * 'min_cache_size' to 'max_cache_size' capability. The default value is implementation + * specific and set by odp_dma_pool_param_init(). + */ + uint32_t cache_size; + +} odp_dma_pool_param_t; + +/* Includes pool_types.h, which depends on odp_dma_pool_param_t. */ +#include <odp/api/queue.h> + +/** + * DMA transfer direction + * + * Transfer direction defines source and destination memory type of DMA transfers. API specification + * defines only one option (#ODP_DMA_MAIN_TO_MAIN) for the transfer direction. It is used for + * transfers within the main memory. Some implementations may extend this enumeration with + * implementation specific directions and memory types (e.g. from main memory to a device, etc.). + */ +typedef uint32_t odp_dma_direction_t; + +/** DMA transfer within the main memory */ +#define ODP_DMA_MAIN_TO_MAIN 0x1u + +/** + * DMA transfer type + * + * Transfer type defines how DMA transfers operate data. Currently, only one transfer type is + * defined (#ODP_DMA_TYPE_COPY). + * + */ +typedef uint32_t odp_dma_transfer_type_t; + +/** Copy data + * + * Copy all data from source segment(s) to destination segment(s). There may be different + * number of source and destination segments in a transfer, but total length of all source + * segments must be equal to total length of all destination segments. Segments must not + * point to overlapping memory addresses. There are no alignment requirements for + * segment addresses or lengths. Data transfer from source to destination may happen + * in any segment and byte order. + */ +#define ODP_DMA_TYPE_COPY 0x1u + +/** + * DMA transfer completion mode + * + * Transfer completion mode defines how transfer completion is reported to the application. + * Completion modes are: #ODP_DMA_COMPL_NONE, #ODP_DMA_COMPL_SYNC, #ODP_DMA_COMPL_EVENT, and + * #ODP_DMA_COMPL_POLL + * + * If not otherwise specified, a DMA transfer is complete when memory reads and writes are complete + * for all its segments, and writes are visible to all memory observers (threads and + * HW accelerators). + */ +typedef uint32_t odp_dma_compl_mode_t; + +/** No completion indication + * + * Application uses odp_dma_transfer_start() call to start a DMA transfer, but does + * not request a completion notification for it. This can be useful for example when application + * starts a burst of transfers, but requests a completion event only on the last one + * (none on others). + */ +#define ODP_DMA_COMPL_NONE 0x1u + +/** Synchronous transfer + * + * Application uses odp_dma_transfer() call for DMA transfers. Each call performs + * the requested transfer and returns when the transfer is complete. + */ +#define ODP_DMA_COMPL_SYNC 0x2u + +/** Asynchronous transfer with completion event + * + * Application uses odp_dma_transfer_start() call to start a DMA transfer. The + * transfer is complete when application receives the completion event. + */ +#define ODP_DMA_COMPL_EVENT 0x4u + +/** Asynchronous transfer with completion polling + * + * Application uses odp_dma_transfer_start() call to start a DMA transfer and uses + * odp_dma_transfer_done() call to check if the transfer has completed. + */ +#define ODP_DMA_COMPL_POLL 0x8u + +/** + * DMA transfer data format + */ +typedef enum { + /** Data format is raw memory address */ + ODP_DMA_FORMAT_ADDR = 0, + + /** Data format is odp_packet_t */ + ODP_DMA_FORMAT_PACKET + +} odp_dma_data_format_t; + +/** + * DMA transfer ordering + * + * These options specify ordering of consecutive DMA transfers within a session. Transfer order + * is defined by the order of consecutive transfer (start) calls and the order of transfers + * within each multi-transfer call. Note that ordering option matters also when using + * odp_dma_transfer_multi() call, as ODP_DMA_ORDER_NONE allows implementation to perform transfers + * in parallel. + * + * These options do not apply to data (segment or byte) processing order within a transfer. + * If two transfers read/write overlapping memory areas, an appropriate transfer ordering option + * (e.g. ODP_DMA_ORDER_ALL) needs to be used for correct operation. + */ +typedef enum { + /** No specific ordering between transfers + * + * This may result the best performance (maximum implementation parallelism) as + * transfers may start and complete in any order. */ + ODP_DMA_ORDER_NONE = 0, + + /** Report transfer completions in order + * + * Transfers may be performed in any order, but transfer completions must be reported + * in the same order they were started within a session. This allows application to + * start multiple transfers and wait only completion of the last one. */ + ODP_DMA_ORDER_COMPL, + + /** Perform all transfers in order + * + * Perform transfers and report their completions in the same order they were started + * within a session. This enables for example a subsequent transfer to read data + * written by a previous transfer. */ + ODP_DMA_ORDER_ALL + +} odp_dma_transfer_order_t; + +/** + * DMA transfer multi-thread safeness + */ +typedef enum { + /** Multi-thread safe operation + * + * Multiple threads may perform DMA transfers concurrently on the same DMA session. + */ + ODP_DMA_MT_SAFE = 0, + + /** Application serializes operations + * + * Multiple threads may perform DMA transfers on the same DMA session, but application + * serializes all transfer related calls (odp_dma_transfer(), odp_dma_transfer_start(), + * _start_multi(), _done() and _result()). Threads do not call any of these operations + * concurrently. + */ + ODP_DMA_MT_SERIAL + +} odp_dma_mt_mode_t; + +/** + * DMA capabilities + */ +typedef struct odp_dma_capability_t { + /** Maximum number of DMA sessions + * + * The value of zero means that DMA offload is not available. + */ + uint32_t max_sessions; + + /** Maximum number of transfers per DMA session + * + * Maximum number of transfers that can be in-flight (started but not yet completed) + * per session. When this limit is reached, new transfer requests may not be accepted + * until some previously started transfers are complete. */ + uint32_t max_transfers; + + /** Maximum number of source segments in a single transfer */ + uint32_t max_src_segs; + + /** Maximum number of destination segments in a single transfer */ + uint32_t max_dst_segs; + + /** Maximum number of destination and source segments combined in a single transfer */ + uint32_t max_segs; + + /** Maximum segment length in bytes + * + * This is the maximum length of any source or destination segment. */ + uint32_t max_seg_len; + + /** Supported completion modes + * + * Each supported completion mode has a corresponding flag set in the mask. + * Synchronous transfer (ODP_DMA_COMPL_SYNC) is always supported. + */ + odp_dma_compl_mode_t compl_mode_mask; + + /** + * Scheduled queue support + * + * 0: Scheduled queues are not supported as DMA completion queues + * 1: Scheduled queues are supported as DMA completion queues + */ + odp_bool_t queue_type_sched; + + /** + * Plain queue support + * + * 0: Plain queues are not supported as DMA completion queues + * 1: Plain queues are supported as DMA completion queues + */ + odp_bool_t queue_type_plain; + + /** DMA completion event pool capabilities */ + odp_dma_pool_capability_t pool; + +} odp_dma_capability_t; + +/** + * DMA session parameters + */ +typedef struct odp_dma_param_t { + /** Transfer direction + * + * The default value is ODP_DMA_MAIN_TO_MAIN. + */ + odp_dma_direction_t direction; + + /** Transfer type + * + * The default value is ODP_DMA_TYPE_COPY. + */ + odp_dma_transfer_type_t type; + + /** Transfer completion modes + * + * Specify the completion modes application will use within the session. + * + * Multiple modes may be selected, but it is implementation specific which combinations + * are supported. If an unsupported combination is requested odp_dma_create() returns + * a failure. See odp_dma_capability_t::compl_mode_mask for the supported modes. + */ + odp_dma_compl_mode_t compl_mode_mask; + + /** Transfer operation multi-thread safeness + * + * The default value is ODP_DMA_MT_SAFE. + */ + odp_dma_mt_mode_t mt_mode; + + /** Transfer ordering + * + * The default value is ODP_DMA_ORDER_NONE. + */ + odp_dma_transfer_order_t order; + +} odp_dma_param_t; + +/** + * DMA segment + */ +typedef struct odp_dma_seg_t { + /** Segment start */ + union { + /** Segment start address in memory + * + * Defines segment start when data format is ODP_DMA_FORMAT_ADDR. Ignored with + * other data formats. + */ + void *addr; + + /** Segment start as an offset into a packet */ + struct { + /** Packet handle + * + * Defines the packet when data format is ODP_DMA_FORMAT_PACKET. Ignored + * with other data formats. */ + odp_packet_t packet; + + /** Segment start offset into the packet + * + * Defines segment start when data format is ODP_DMA_FORMAT_PACKET. + * The offset is calculated from odp_packet_data() position, and the value + * must not exceed odp_packet_len(). + */ + uint32_t offset; + }; + }; + + /** Segment length in bytes + * + * Defines segment length with all data formats. The maximum value is defined by + * max_seg_len capability. When data format is ODP_DMA_FORMAT_PACKET, the value must not + * exceed odp_packet_len() - 'offset'. + */ + uint32_t len; + + /** Segment hints + * + * Depending on the implementation, setting these hints may improve performance. + * Initialize all unused bits to zero. + */ + union { + /** Segment hints bit field */ + struct { + /** Allow full cache line access + * + * When set to 1, data on the same cache line with the destination segment + * is allowed to be overwritten. This hint is ignored on source segments. + */ + uint16_t full_lines : 1; + }; + + /** All bits of the bit field structure + * + * This can be used to set/clear all bits, or to perform bitwise operations + * on those. + */ + uint16_t all_hints; + }; + +} odp_dma_seg_t; + +/** + * DMA transfer parameters + * + * These parameters define data sources and destinations for a DMA transfer. Capabilities specify + * the maximum number of segments and the maximum segment length that are supported. + * + * The selected data format specifies how segment structure fields are used. When data format is + * ODP_DMA_FORMAT_ADDR, set segment start address (odp_dma_seg_t::addr) and + * length (odp_dma_seg_t::len). When data format is ODP_DMA_FORMAT_PACKET, set packet + * handle (odp_dma_seg_t::packet), segment start offset (odp_dma_seg_t::offset) and length. + * If a DMA segment spans over multiple packet segments, it is considered as equally many + * DMA segments. So, take packet segmentation into account when making sure that the maximum + * number of DMA segments capabilities are not exceeded. + */ +typedef struct odp_dma_transfer_param_t { + /** Source data format + * + * The default value is ODP_DMA_FORMAT_ADDR. + */ + odp_dma_data_format_t src_format; + + /** Destination data format + * + * The default value is ODP_DMA_FORMAT_ADDR. + */ + odp_dma_data_format_t dst_format; + + /** Number of source segments + * + * The default value is 1. + */ + uint32_t num_src; + + /** Number of destination segments + * + * The default value is 1. + */ + uint32_t num_dst; + + /** Table of source segments + * + * The table has 'num_src' entries. Data format is defined by 'src_format'. + */ + odp_dma_seg_t *src_seg; + + /** Table of destination segments + * + * The table has 'num_dst' entries. Data format is defined by 'dst_format'. + */ + odp_dma_seg_t *dst_seg; + +} odp_dma_transfer_param_t; + +/** + * DMA transfer completion parameters + */ +typedef struct odp_dma_compl_param_t { + /** Completion mode + * + * Select a completion mode: #ODP_DMA_COMPL_EVENT, #ODP_DMA_COMPL_POLL or + * #ODP_DMA_COMPL_NONE. The mode must match one of the modes selected in session creation + * parameters (odp_dma_param_t::compl_mode_mask). + * + * ODP_DMA_COMPL_NONE can be used to specify that completion indication is not requested. + * Application may for example start a series of transfers and request completion + * indication only on the last one. + */ + odp_dma_compl_mode_t compl_mode; + + /** Transfer identifier + * + * Transfer identifier is used in ODP_DMA_COMPL_POLL mode. Application passes the same + * identifier here and to a later odp_dma_transfer_done() call to check transfer + * completion status. Identifiers are allocated with odp_dma_transfer_id_alloc(). + * The identifier of a completed transfer may be reused for another transfer. + */ + odp_dma_transfer_id_t transfer_id; + + /** Completion event + * + * When a transfer is started in ODP_DMA_COMPL_EVENT mode, this event is sent to + * the completion queue when the transfer is complete. The event type must be + * ODP_EVENT_DMA_COMPL. Use odp_dma_compl_result() to retrieve transfer results from + * the event. + */ + odp_event_t event; + + /** Completion queue + * + * The completion event is sent into this queue in ODP_DMA_COMPL_EVENT mode. + */ + odp_queue_t queue; + + /** User context pointer + * + * User defined context pointer which is copied to transfer results + * (@see odp_dma_result_t). The value does not need to represent a valid address + * (any intptr_t value is allowed). + * + * The default value is NULL. + */ + void *user_ptr; + +} odp_dma_compl_param_t; + +/** DMA transfer results */ +typedef struct odp_dma_result_t { + /** DMA transfer success + * + * true: DMA transfer was successful + * false: DMA transfer failed + */ + odp_bool_t success; + + /** User context pointer + * + * User defined context pointer value from transfer completion parameters + * (@see odp_dma_compl_param_t). The default value is NULL. + */ + void *user_ptr; + +} odp_dma_result_t; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif + diff --git a/include/odp/api/spec/event.h b/include/odp/api/spec/event.h index 32fd37c29..dc99f35c7 100644 --- a/include/odp/api/spec/event.h +++ b/include/odp/api/spec/event.h @@ -63,6 +63,8 @@ extern "C" { * - ODP_EVENT_PACKET_TX_COMPL * - Packet Tx completion event (odp_packet_tx_compl_t) generated as a result of a Packet Tx * completion. + * - ODP_EVENT_DMA_COMPL + * - DMA completion event (odp_dma_compl_t) indicates that a DMA transfer has finished */ /** diff --git a/include/odp/api/spec/ipsec.h b/include/odp/api/spec/ipsec.h index f66758341..11cbfe65d 100644 --- a/include/odp/api/spec/ipsec.h +++ b/include/odp/api/spec/ipsec.h @@ -364,6 +364,9 @@ typedef struct odp_ipsec_capability_t { * be used for many SAs. */ uint32_t max_queues; + /** Support for returning completion packets as vectors */ + odp_pktin_vector_capability_t vector; + /** Maximum anti-replay window size. */ uint32_t max_antireplay_ws; @@ -455,6 +458,16 @@ typedef struct odp_ipsec_config_t { */ odp_bool_t stats_en; + /** + * Packet vector configuration for async and inline operations + * + * This packet vector configuration affects packets delivered to + * the application through the default queue and the SA destination + * queues. It does not affect packets delivered through pktio + * input queues. + */ + odp_pktin_vector_config_t vector; + } odp_ipsec_config_t; /** @@ -1178,6 +1191,9 @@ void odp_ipsec_sa_param_init(odp_ipsec_sa_param_t *param); * * Create a new IPSEC SA according to the parameters. * + * The parameter structure as well as all key, address and other memory + * buffers pointed to by it can be freed after the call. + * * @param param IPSEC SA parameters * * @return IPSEC SA handle diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h index 0d5938e9e..b2bad8621 100644 --- a/include/odp/api/spec/packet_io.h +++ b/include/odp/api/spec/packet_io.h @@ -181,7 +181,9 @@ typedef struct odp_pktin_vector_config_t { * * When true, packet input vector is enabled and configured with vector * config parameters. Otherwise, packet input vector configuration - * parameters are ignored. + * parameters are ignored. When vectors are enabled, packets may + * be delivered both as packet vector events and packet events. + * The default value is false. */ odp_bool_t enable; @@ -267,7 +269,8 @@ typedef struct odp_pktin_queue_param_t { * These are used for input queue creation in ODP_PKTIN_MODE_QUEUE * or ODP_PKTIN_MODE_SCHED modes. Scheduler parameters are considered * only in ODP_PKTIN_MODE_SCHED mode. Default values are defined in - * odp_queue_param_t documentation. + * odp_queue_param_t documentation. The type field is ignored + * and the queue type is deduced from the pktio input mode. * When classifier is enabled in odp_pktin_queue_config() this * value is ignored. */ odp_queue_param_t queue_param; diff --git a/include/odp/api/spec/pool_types.h b/include/odp/api/spec/pool_types.h index 583a81b67..b0d5b37c9 100644 --- a/include/odp/api/spec/pool_types.h +++ b/include/odp/api/spec/pool_types.h @@ -19,6 +19,7 @@ extern "C" { #endif #include <odp/api/std_types.h> +#include <odp/api/dma_types.h> /** @addtogroup odp_pool * @{ @@ -324,7 +325,10 @@ typedef enum odp_pool_type_t { * Each vector holds an array of generic types of the same type. * @see ODP_EVENT_PACKET_VECTOR */ - ODP_POOL_VECTOR = (ODP_POOL_TIMEOUT + 1) + ODP_POOL_VECTOR, + + /** DMA completion event pool */ + ODP_POOL_DMA_COMPL } odp_pool_type_t; @@ -710,6 +714,9 @@ typedef struct odp_pool_ext_param_t { * Used to get information about a pool. */ typedef struct odp_pool_info_t { + /** Pool type */ + odp_pool_type_t type; + /** Pool name */ const char *name; @@ -727,6 +734,9 @@ typedef struct odp_pool_info_t { /** Copy of external memory pool parameters. This is set when pool_ext is 1. */ odp_pool_ext_param_t pool_ext_param; + + /** Copy of pool parameters when pool type is ODP_POOL_DMA_COMPL. */ + odp_dma_pool_param_t dma_pool_param; }; /** Additional info for packet pools */ diff --git a/include/odp/api/spec/random.h b/include/odp/api/spec/random.h index 80f71c473..3cd297249 100644 --- a/include/odp/api/spec/random.h +++ b/include/odp/api/spec/random.h @@ -18,6 +18,8 @@ extern "C" { #endif +#include <odp/api/std_types.h> + /** @defgroup odp_random ODP RANDOM * Random number generation. * @{ diff --git a/include/odp/api/spec/shared_memory.h b/include/odp/api/spec/shared_memory.h index 6d4066f15..6ba6f7fc2 100644 --- a/include/odp/api/spec/shared_memory.h +++ b/include/odp/api/spec/shared_memory.h @@ -1,5 +1,5 @@ -/* Copyright (c) 2019, Nokia - * Copyright (c) 2013-2018, Linaro Limited +/* Copyright (c) 2013-2018, Linaro Limited + * Copyright (c) 2019-2021, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -92,12 +92,20 @@ extern "C" { * When set, this flag guarantees that the reserved memory is accessible * by both CPUs and HW accelerators of the device. This may require e.g. that * the odp_shm_reserve() call configures the memory to be accessible through - * an Input-Output Memory Management Unit (IOMMU). The reserve call will return - * failure if such configuration is not supported. + * an Input-Output Memory Management Unit (IOMMU). */ #define ODP_SHM_HW_ACCESS 0x20 /** + * Don't use huge pages + * + * When set, this flag guarantees that the memory reserved by odp_shm_reserve() + * is not allocated from huge pages. This flag must not be combined with + * ODP_SHM_HP. + */ +#define ODP_SHM_NO_HP 0x40 + +/** * Shared memory block info */ typedef struct odp_shm_info_t { @@ -139,6 +147,14 @@ typedef struct odp_shm_capability_t { * available memory size. */ uint64_t max_align; + /** Supported shared memory flags + * + * A bit mask of supported ODP_SHM_* flags. Depending on the + * implementation some flag combinations may not be supported. In this + * case odp_shm_reserve() will fail. + */ + uint32_t flags; + } odp_shm_capability_t; /** diff --git a/include/odp/api/spec/std_types.h b/include/odp/api/spec/std_types.h index 41f436065..accbd81d8 100644 --- a/include/odp/api/spec/std_types.h +++ b/include/odp/api/spec/std_types.h @@ -134,6 +134,9 @@ typedef union odp_feature_t { /** Crypto APIs, e.g., odp_crypto_xxx() */ uint32_t crypto:1; + /** DMA APIs, e.g., odp_dma_xxx() */ + uint32_t dma:1; + /** IPsec APIs, e.g., odp_ipsec_xxx() */ uint32_t ipsec:1; diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h index 319f5e029..c16ac6d64 100644 --- a/include/odp/api/spec/timer.h +++ b/include/odp/api/spec/timer.h @@ -20,258 +20,14 @@ extern "C" { #endif -/** @defgroup odp_timer ODP TIMER - * Timer generating timeout events. - * @{ - */ - -/** - * @typedef odp_timer_pool_t - * ODP timer pool handle - */ - -/** - * @def ODP_TIMER_POOL_INVALID - * Invalid timer pool handle - */ - -/** - * Clock sources for timer pools - * - * ODP_CLOCK_DEFAULT is the default clock source and it is supported always. It is implementation - * defined which other clock sources are supported. See from implementation documentation how the - * supported clock sources are mapped into these enumerations. - */ -typedef enum { - /** Clock source number 0 */ - ODP_CLOCK_SRC_0, - - /** Clock source number 1 */ - ODP_CLOCK_SRC_1, - - /** Clock source number 2 */ - ODP_CLOCK_SRC_2, - - /** Clock source number 3 */ - ODP_CLOCK_SRC_3, - - /** Clock source number 4 */ - ODP_CLOCK_SRC_4, - - /** Clock source number 5 */ - ODP_CLOCK_SRC_5, - - /** Number of clock source enumerations */ - ODP_CLOCK_NUM_SRC - -} odp_timer_clk_src_t; - -/** The default clock source */ -#define ODP_CLOCK_DEFAULT ODP_CLOCK_SRC_0 - -/** For backwards compatibility, ODP_CLOCK_CPU is synonym of ODP_CLOCK_DEFAULT. - * This will be deprecated in the future. */ -#define ODP_CLOCK_CPU ODP_CLOCK_DEFAULT - -/** For backwards compatibility, ODP_CLOCK_EXT is synonym of ODP_CLOCK_SRC_1. - * This will be deprecated in the future. */ -#define ODP_CLOCK_EXT ODP_CLOCK_SRC_1 - -/** - * @typedef odp_timer_t - * ODP timer handle - */ - -/** - * @def ODP_TIMER_INVALID - * Invalid timer handle - */ - -/** - * @typedef odp_timeout_t - * ODP timeout handle - */ - -/** - * @def ODP_TIMEOUT_INVALID - * Invalid timeout handle - */ - -/** - * Return values of timer set calls. - */ -typedef enum { - /** Timer set operation succeeded */ - ODP_TIMER_SUCCESS = 0, +#include <odp/api/timer_types.h> +#include <odp/api/event.h> +#include <odp/api/queue_types.h> +#include <odp/api/pool.h> - /** Timer set operation failed because expiration time is too near to - * the current time. */ - ODP_TIMER_TOO_NEAR = -1, - - /** Timer set operation failed because expiration time is too far from - * the current time. */ - ODP_TIMER_TOO_FAR = -2, - - /** Timer set operation failed */ - ODP_TIMER_FAIL = -3 - -} odp_timer_set_t; - -/** For backwards compatibility, ODP_TIMER_TOOEARLY is synonym of ODP_TIMER_TOO_NEAR. - * This will be deprecated in the future. */ -#define ODP_TIMER_TOOEARLY ODP_TIMER_TOO_NEAR - -/** For backwards compatibility, ODP_TIMER_TOOLATE is synonym of ODP_TIMER_TOO_FAR. - * This will be deprecated in the future. */ -#define ODP_TIMER_TOOLATE ODP_TIMER_TOO_FAR - -/** For backwards compatibility, ODP_TIMER_NOEVENT is synonym of ODP_TIMER_FAIL. - * This will be deprecated in the future. */ -#define ODP_TIMER_NOEVENT ODP_TIMER_FAIL - -/** - * @def ODP_TIMER_POOL_NAME_LEN - * Maximum timer pool name length in chars including null char - */ - -/** - * Timer pool parameters - */ -typedef struct { - /** Timeout resolution in nanoseconds. Timer pool must serve timeouts - * with this or higher resolution. The minimum valid value (highest - * resolution) is defined by timer resolution capability. When this - * parameter is used, set 'res_hz' to zero. */ - uint64_t res_ns; - - /** Timeout resolution in hertz. This may be used to specify the highest - * required resolution in hertz instead of nanoseconds. When this - * parameter is used, set 'res_ns' to zero. */ - uint64_t res_hz; - - /** Minimum relative timeout in nanoseconds. All requested timeouts - * will be at least this many nanoseconds after the current - * time of the timer pool. Timer set functions return an error, if too - * short timeout was requested. The value may be also smaller than - * the requested resolution. */ - uint64_t min_tmo; - - /** Maximum relative timeout in nanoseconds. All requested timeouts - * will be at most this many nanoseconds after the current - * time of the timer pool. Timer set functions return an error, if too - * long timeout was requested. */ - uint64_t max_tmo; - - /** Number of timers needed. Application will create in maximum this - * many concurrent timers from the timer pool. */ - uint32_t num_timers; - - /** Thread private timer pool. When zero, multiple thread may use the - * timer pool concurrently. When non-zero, only single thread uses the - * timer pool (concurrently). */ - int priv; - - /** Clock source for timers */ - odp_timer_clk_src_t clk_src; - -} odp_timer_pool_param_t; - -/** - * Timer resolution capability +/** @addtogroup odp_timer + * @{ */ -typedef struct { - /** Timeout resolution in nanoseconds */ - uint64_t res_ns; - - /** Timeout resolution in hertz */ - uint64_t res_hz; - - /** Minimum relative timeout in nanoseconds */ - uint64_t min_tmo; - - /** Maximum relative timeout in nanoseconds */ - uint64_t max_tmo; - -} odp_timer_res_capability_t; - -/** - * Timer capability - */ -typedef struct { - /** Maximum number of timer pools over all clock sources - * - * The total number of timer pools that can be created combining - * different clock sources. - */ - uint32_t max_pools_combined; - - /** Maximum number of timer pools for the requested clock source */ - uint32_t max_pools; - - /** Maximum number of timers in a pool - * - * The value of zero means that limited only by the available - * memory size for the pool. */ - uint32_t max_timers; - - /** Highest timer resolution in nanoseconds. - * - * This defines the highest resolution supported by a timer. - * It's the minimum valid value for 'res_ns' timer pool - * parameter. - * - * This value is equal to 'max_res.res_ns' capability. - */ - uint64_t highest_res_ns; - - /** - * Maximum resolution - * - * This defines the highest resolution supported by a timer, with - * limits to min/max timeout values. The highest resolution for a timer - * pool is defined by 'max_res.res_ns' in nanoseconds and - * 'max_res.res_hz' in hertz. - * When this resolution is used: - * - 'min_tmo' parameter value must be in minimum 'max_res.min_tmo' - * - 'max_tmo' parameter value must be in maximum 'max_res.max_tmo' - */ - odp_timer_res_capability_t max_res; - - /** - * Maximum timeout length - * - * This defines the maximum relative timeout value supported by a timer, - * with limits to min timeout and max resolution values. The maximum - * value for 'max_tmo' timer pool parameter is defined by - * 'max_tmo.max_tmo'. When this max timeout value is used: - * - 'min_tmo' parameter value must be in minimum 'max_tmo.min_tmo' - * - 'res_ns' parameter value must be in minimum 'max_tmo.res_ns' or - * - 'res_hz' parameter value must be in maximum 'max_tmo.res_hz' - */ - odp_timer_res_capability_t max_tmo; - - /** - * Scheduled queue destination support - * - * This defines whether schedule queues are supported as timeout - * destination queues. - * 0: Scheduled queues are not supported as timeout destination queues - * 1: Scheduled queues are supported as timeout destination queues - * @see odp_timer_alloc() - */ - odp_bool_t queue_type_sched; - - /** - * Plain queue destination support - * - * This defines whether plain queues are supported as timeout - * destination queues. - * 0: Plain queues are not supported as timeout destination queues - * 1: Plain queues are supported as timeout destination queues - * @see odp_timer_alloc() - */ - odp_bool_t queue_type_plain; -} odp_timer_capability_t; /** * Query timer capabilities per clock source @@ -311,9 +67,19 @@ int odp_timer_res_capability(odp_timer_clk_src_t clk_src, odp_timer_res_capability_t *res_capa); /** + * Initialize timer pool parameters + * + * Initialize an odp_timer_pool_param_t to its default values for all fields. + * + * @param[out] param Pointer to the odp_timer_pool_param_t structure to be initialized + */ +void odp_timer_pool_param_init(odp_timer_pool_param_t *param); + +/** * Create a timer pool * - * The use of pool name is optional. Unique names are not required. + * The use of pool name is optional. Unique names are not required. Use odp_timer_pool_param_init() + * to initialize timer pool parameters into their default values. * * @param name Name of the timer pool or NULL. Maximum string length is * ODP_TIMER_POOL_NAME_LEN. @@ -375,75 +141,6 @@ uint64_t odp_timer_ns_to_tick(odp_timer_pool_t timer_pool, uint64_t ns); uint64_t odp_timer_current_tick(odp_timer_pool_t timer_pool); /** - * Timer tick information - */ -typedef struct odp_timer_tick_info_t { - /** - * Timer tick frequency in hertz - * - * Timer tick frequency expressed as a fractional number. The integer part contains - * full hertz. The fraction part (numerator / denominator) contains parts of - * a hertz to be added with the integer. - * - * For example, a timer tick frequency of 333 333 and 1/3 Hz could be presented with - * these values: integer = 333 333, numer = 1, denom = 3. Implementation may choose numer - * and denom values freely. - */ - odp_fract_u64_t freq; - - /** - * One timer tick in nanoseconds - * - * Nanoseconds per tick is expressed as a fractional number. The integer part contains - * full nanoseconds. The fraction part (numerator / denominator) contains parts of - * a nanosecond to be added with the integer. - * - * For example, a timer tick period of 3.125 nanoseconds (320MHz) could be presented with - * these values: integer = 3, numer = 125 000 000, denom = 1 000 000 000. Implementation - * may choose numer and denom values freely. - */ - odp_fract_u64_t nsec; - - /** - * One timer tick in source clock cycles - * - * The clock cycle count is expressed as a fractional number. The integer part contains - * full clock cycles. The fraction part (numerator / denominator) contains parts of - * a clock cycle to be added with the integer. - * - * For example, a timer tick period of 42 and 1/3 source clock cycles could be presented - * with these values: integer = 42, numer = 1, denom = 3. Implementation may choose numer - * and denom values freely. - * - * The value is zero, when there is no direct connection between tick and the source - * clock signal. - */ - odp_fract_u64_t clk_cycle; - -} odp_timer_tick_info_t; - -/** - * ODP timer pool information and configuration - */ -typedef struct { - /** Parameters specified at creation */ - odp_timer_pool_param_t param; - - /** Number of currently allocated timers */ - uint32_t cur_timers; - - /** High watermark of allocated timers */ - uint32_t hwm_timers; - - /** Name of timer pool */ - const char *name; - - /** Timer pool tick information */ - odp_timer_tick_info_t tick_info; - -} odp_timer_pool_info_t; - -/** * Query timer pool configuration and current state * * @param timer_pool Timer pool diff --git a/include/odp/api/spec/timer_types.h b/include/odp/api/spec/timer_types.h new file mode 100644 index 000000000..2fad1b372 --- /dev/null +++ b/include/odp/api/spec/timer_types.h @@ -0,0 +1,359 @@ +/* Copyright (c) 2013-2018, Linaro Limited + * Copyright (c) 2019-2021, Nokia + * + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP timer API type definitions + */ + +#ifndef ODP_API_SPEC_TIMER_TYPES_H_ +#define ODP_API_SPEC_TIMER_TYPES_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/std_types.h> + +/** @defgroup odp_timer ODP TIMER + * Timer generating timeout events. + * @{ + */ + +/** + * @typedef odp_timer_pool_t + * ODP timer pool handle + */ + +/** + * @def ODP_TIMER_POOL_INVALID + * Invalid timer pool handle + */ + +/** + * @typedef odp_timer_t + * ODP timer handle + */ + +/** + * @def ODP_TIMER_INVALID + * Invalid timer handle + */ + +/** + * @typedef odp_timeout_t + * ODP timeout handle + */ + +/** + * @def ODP_TIMEOUT_INVALID + * Invalid timeout handle + */ + +/** + * @def ODP_TIMER_POOL_NAME_LEN + * Maximum timer pool name length in chars including null char + */ + +/** + * Timer resolution capability + */ +typedef struct { + /** Timeout resolution in nanoseconds */ + uint64_t res_ns; + + /** Timeout resolution in hertz */ + uint64_t res_hz; + + /** Minimum relative timeout in nanoseconds */ + uint64_t min_tmo; + + /** Maximum relative timeout in nanoseconds */ + uint64_t max_tmo; + +} odp_timer_res_capability_t; + +/** + * Timer capability + */ +typedef struct { + /** Maximum number of timer pools over all clock sources + * + * The total number of timer pools that can be created combining + * different clock sources. + */ + uint32_t max_pools_combined; + + /** Maximum number of timer pools for the requested clock source */ + uint32_t max_pools; + + /** Maximum number of timers in a pool + * + * The value of zero means that limited only by the available + * memory size for the pool. */ + uint32_t max_timers; + + /** Highest timer resolution in nanoseconds. + * + * This defines the highest resolution supported by a timer. + * It's the minimum valid value for 'res_ns' timer pool + * parameter. + * + * This value is equal to 'max_res.res_ns' capability. + */ + uint64_t highest_res_ns; + + /** + * Maximum resolution + * + * This defines the highest resolution supported by a timer, with + * limits to min/max timeout values. The highest resolution for a timer + * pool is defined by 'max_res.res_ns' in nanoseconds and + * 'max_res.res_hz' in hertz. + * When this resolution is used: + * - 'min_tmo' parameter value must be in minimum 'max_res.min_tmo' + * - 'max_tmo' parameter value must be in maximum 'max_res.max_tmo' + */ + odp_timer_res_capability_t max_res; + + /** + * Maximum timeout length + * + * This defines the maximum relative timeout value supported by a timer, + * with limits to min timeout and max resolution values. The maximum + * value for 'max_tmo' timer pool parameter is defined by + * 'max_tmo.max_tmo'. When this max timeout value is used: + * - 'min_tmo' parameter value must be in minimum 'max_tmo.min_tmo' + * - 'res_ns' parameter value must be in minimum 'max_tmo.res_ns' or + * - 'res_hz' parameter value must be in maximum 'max_tmo.res_hz' + */ + odp_timer_res_capability_t max_tmo; + + /** + * Scheduled queue destination support + * + * This defines whether schedule queues are supported as timeout + * destination queues. + * 0: Scheduled queues are not supported as timeout destination queues + * 1: Scheduled queues are supported as timeout destination queues + * @see odp_timer_alloc() + */ + odp_bool_t queue_type_sched; + + /** + * Plain queue destination support + * + * This defines whether plain queues are supported as timeout + * destination queues. + * 0: Plain queues are not supported as timeout destination queues + * 1: Plain queues are supported as timeout destination queues + * @see odp_timer_alloc() + */ + odp_bool_t queue_type_plain; + +} odp_timer_capability_t; + +/** + * Clock sources for timer pools + * + * ODP_CLOCK_DEFAULT is the default clock source and it is supported always. It is implementation + * defined which other clock sources are supported. See from implementation documentation how the + * supported clock sources are mapped into these enumerations. + */ +typedef enum { + /** Clock source number 0 */ + ODP_CLOCK_SRC_0, + + /** Clock source number 1 */ + ODP_CLOCK_SRC_1, + + /** Clock source number 2 */ + ODP_CLOCK_SRC_2, + + /** Clock source number 3 */ + ODP_CLOCK_SRC_3, + + /** Clock source number 4 */ + ODP_CLOCK_SRC_4, + + /** Clock source number 5 */ + ODP_CLOCK_SRC_5, + + /** Number of clock source enumerations */ + ODP_CLOCK_NUM_SRC + +} odp_timer_clk_src_t; + +/** The default clock source */ +#define ODP_CLOCK_DEFAULT ODP_CLOCK_SRC_0 + +/** For backwards compatibility, ODP_CLOCK_CPU is synonym of ODP_CLOCK_DEFAULT. + * This will be deprecated in the future. */ +#define ODP_CLOCK_CPU ODP_CLOCK_DEFAULT + +/** For backwards compatibility, ODP_CLOCK_EXT is synonym of ODP_CLOCK_SRC_1. + * This will be deprecated in the future. */ +#define ODP_CLOCK_EXT ODP_CLOCK_SRC_1 + +/** + * Timer pool parameters + */ +typedef struct { + /** Timeout resolution in nanoseconds. Timer pool must serve timeouts + * with this or higher resolution. The minimum valid value (highest + * resolution) is defined by timer resolution capability. When this + * parameter is used, set 'res_hz' to zero. The default value is zero. */ + uint64_t res_ns; + + /** Timeout resolution in hertz. This may be used to specify the highest + * required resolution in hertz instead of nanoseconds. When this + * parameter is used, set 'res_ns' to zero. The default value is zero. */ + uint64_t res_hz; + + /** Minimum relative timeout in nanoseconds. All requested timeouts + * will be at least this many nanoseconds after the current + * time of the timer pool. Timer set functions return an error, if too + * short timeout was requested. The value may be also smaller than + * the requested resolution. The default value is zero. */ + uint64_t min_tmo; + + /** Maximum relative timeout in nanoseconds. All requested timeouts + * will be at most this many nanoseconds after the current + * time of the timer pool. Timer set functions return an error, if too + * long timeout was requested. */ + uint64_t max_tmo; + + /** Number of timers needed. Application will create in maximum this + * many concurrent timers from the timer pool. */ + uint32_t num_timers; + + /** Thread private timer pool. When zero, multiple thread may use the + * timer pool concurrently. When non-zero, only single thread uses the + * timer pool (concurrently). The default value is zero. */ + int priv; + + /** Clock source for timers + * + * The default value is ODP_CLOCK_DEFAULT. */ + odp_timer_clk_src_t clk_src; + +} odp_timer_pool_param_t; + +/** + * Return values of timer set calls. + */ +typedef enum { + /** Timer set operation succeeded */ + ODP_TIMER_SUCCESS = 0, + + /** Timer set operation failed because expiration time is too near to + * the current time. */ + ODP_TIMER_TOO_NEAR = -1, + + /** Timer set operation failed because expiration time is too far from + * the current time. */ + ODP_TIMER_TOO_FAR = -2, + + /** Timer set operation failed */ + ODP_TIMER_FAIL = -3 + +} odp_timer_set_t; + +/** For backwards compatibility, ODP_TIMER_TOOEARLY is synonym of ODP_TIMER_TOO_NEAR. + * This will be deprecated in the future. */ +#define ODP_TIMER_TOOEARLY ODP_TIMER_TOO_NEAR + +/** For backwards compatibility, ODP_TIMER_TOOLATE is synonym of ODP_TIMER_TOO_FAR. + * This will be deprecated in the future. */ +#define ODP_TIMER_TOOLATE ODP_TIMER_TOO_FAR + +/** For backwards compatibility, ODP_TIMER_NOEVENT is synonym of ODP_TIMER_FAIL. + * This will be deprecated in the future. */ +#define ODP_TIMER_NOEVENT ODP_TIMER_FAIL + +/** + * Timer tick information + */ +typedef struct odp_timer_tick_info_t { + /** + * Timer tick frequency in hertz + * + * Timer tick frequency expressed as a fractional number. The integer part contains + * full hertz. The fraction part (numerator / denominator) contains parts of + * a hertz to be added with the integer. + * + * For example, a timer tick frequency of 333 333 and 1/3 Hz could be presented with + * these values: integer = 333 333, numer = 1, denom = 3. Implementation may choose numer + * and denom values freely. + */ + odp_fract_u64_t freq; + + /** + * One timer tick in nanoseconds + * + * Nanoseconds per tick is expressed as a fractional number. The integer part contains + * full nanoseconds. The fraction part (numerator / denominator) contains parts of + * a nanosecond to be added with the integer. + * + * For example, a timer tick period of 3.125 nanoseconds (320MHz) could be presented with + * these values: integer = 3, numer = 125 000 000, denom = 1 000 000 000. Implementation + * may choose numer and denom values freely. + */ + odp_fract_u64_t nsec; + + /** + * One timer tick in source clock cycles + * + * The clock cycle count is expressed as a fractional number. The integer part contains + * full clock cycles. The fraction part (numerator / denominator) contains parts of + * a clock cycle to be added with the integer. + * + * For example, a timer tick period of 42 and 1/3 source clock cycles could be presented + * with these values: integer = 42, numer = 1, denom = 3. Implementation may choose numer + * and denom values freely. + * + * The value is zero, when there is no direct connection between tick and the source + * clock signal. + */ + odp_fract_u64_t clk_cycle; + +} odp_timer_tick_info_t; + +/** + * ODP timer pool information and configuration + */ +typedef struct { + /** Parameters specified at creation */ + odp_timer_pool_param_t param; + + /** Number of currently allocated timers */ + uint32_t cur_timers; + + /** High watermark of allocated timers */ + uint32_t hwm_timers; + + /** Name of timer pool */ + const char *name; + + /** Timer pool tick information */ + odp_timer_tick_info_t tick_info; + +} odp_timer_pool_info_t; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif diff --git a/include/odp/api/timer.h b/include/odp/api/timer.h index 7c0dd95b6..3041594f5 100644 --- a/include/odp/api/timer.h +++ b/include/odp/api/timer.h @@ -17,12 +17,6 @@ extern "C" { #endif -#include <odp/api/std_types.h> -#include <odp/api/abi/event.h> -#include <odp/api/abi/pool.h> -#include <odp/api/abi/queue_types.h> -#include <odp/api/abi/timer.h> - #include <odp/api/spec/timer.h> #ifdef __cplusplus diff --git a/include/odp/api/timer_types.h b/include/odp/api/timer_types.h new file mode 100644 index 000000000..8d3385594 --- /dev/null +++ b/include/odp/api/timer_types.h @@ -0,0 +1,28 @@ +/* Copyright (c) 2021, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP timer service + */ + +#ifndef ODP_API_TIMER_TYPES_H_ +#define ODP_API_TIMER_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/abi/timer_types.h> + +#include <odp/api/spec/timer_types.h> + +#ifdef __cplusplus +} +#endif + +#endif |