diff options
Diffstat (limited to 'include/odp/api')
55 files changed, 1905 insertions, 57 deletions
diff --git a/include/odp/api/abi-default/align.h b/include/odp/api/abi-default/align.h index 0fa058549..fa95d728b 100644 --- a/include/odp/api/abi-default/align.h +++ b/include/odp/api/abi-default/align.h @@ -17,7 +17,7 @@ extern "C" { #include <odp/api/abi/cpu.h> -/** @ingroup odp_compiler_optim +/** @addtogroup odp_compiler_optim * @{ */ diff --git a/include/odp/api/abi-default/buffer_types.h b/include/odp/api/abi-default/buffer_types.h index 59588224f..9179ae321 100644 --- a/include/odp/api/abi-default/buffer_types.h +++ b/include/odp/api/abi-default/buffer_types.h @@ -13,7 +13,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_buffer_t; -/** @ingroup odp_buffer +/** @addtogroup odp_buffer * @{ */ diff --git a/include/odp/api/abi-default/classification.h b/include/odp/api/abi-default/classification.h index e7519329a..fdc98f252 100644 --- a/include/odp/api/abi-default/classification.h +++ b/include/odp/api/abi-default/classification.h @@ -15,7 +15,7 @@ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_cos_t; /** Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_pmr_t; -/** @ingroup odp_classification +/** @addtogroup odp_classification * @{ */ diff --git a/include/odp/api/abi-default/comp.h b/include/odp/api/abi-default/comp.h index b5638eba8..3f936aa20 100644 --- a/include/odp/api/abi-default/comp.h +++ b/include/odp/api/abi-default/comp.h @@ -14,7 +14,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_comp_session_t; -/** @ingroup odp_compression +/** @addtogroup odp_compression * @{ */ diff --git a/include/odp/api/abi-default/crypto_types.h b/include/odp/api/abi-default/crypto_types.h index 58898dfea..8d860b6ef 100644 --- a/include/odp/api/abi-default/crypto_types.h +++ b/include/odp/api/abi-default/crypto_types.h @@ -12,7 +12,7 @@ extern "C" { #include <stdint.h> -/** @ingroup odp_crypto +/** @addtogroup odp_crypto * @{ */ diff --git a/include/odp/api/abi-default/dma_types.h b/include/odp/api/abi-default/dma_types.h index 1d27a11aa..005ba3d16 100644 --- a/include/odp/api/abi-default/dma_types.h +++ b/include/odp/api/abi-default/dma_types.h @@ -17,7 +17,7 @@ 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 +/** @addtogroup odp_dma * @{ */ diff --git a/include/odp/api/abi-default/event_types.h b/include/odp/api/abi-default/event_types.h index d6231a98f..e5b50d9c0 100644 --- a/include/odp/api/abi-default/event_types.h +++ b/include/odp/api/abi-default/event_types.h @@ -1,6 +1,6 @@ /* SPDX-License-Identifier: BSD-3-Clause * Copyright (c) 2017-2018 Linaro Limited - * Copyright (c) 2022 Nokia + * Copyright (c) 2022-2023 Nokia */ #ifndef ODP_ABI_EVENT_TYPES_H_ @@ -15,7 +15,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_event_t; -/** @ingroup odp_event +/** @addtogroup odp_event * @{ */ @@ -31,6 +31,7 @@ typedef enum { ODP_EVENT_PACKET_VECTOR = 6, ODP_EVENT_PACKET_TX_COMPL = 7, ODP_EVENT_DMA_COMPL = 8, + ODP_EVENT_ML_COMPL = 9 } odp_event_type_t; typedef enum { @@ -38,7 +39,9 @@ typedef enum { ODP_EVENT_PACKET_BASIC = 1, ODP_EVENT_PACKET_CRYPTO = 2, ODP_EVENT_PACKET_IPSEC = 3, - ODP_EVENT_PACKET_COMP = 4 + ODP_EVENT_PACKET_COMP = 4, + ODP_EVENT_ML_COMPL_LOAD = 5, + ODP_EVENT_ML_COMPL_RUN = 6 } odp_event_subtype_t; /** diff --git a/include/odp/api/abi-default/ipsec_types.h b/include/odp/api/abi-default/ipsec_types.h index 737f67153..9d099b80d 100644 --- a/include/odp/api/abi-default/ipsec_types.h +++ b/include/odp/api/abi-default/ipsec_types.h @@ -15,7 +15,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_ipsec_sa_t; -/** @ingroup odp_ipsec +/** @addtogroup odp_ipsec * @{ */ diff --git a/include/odp/api/abi-default/ml_types.h b/include/odp/api/abi-default/ml_types.h new file mode 100644 index 000000000..723beb1bc --- /dev/null +++ b/include/odp/api/abi-default/ml_types.h @@ -0,0 +1,48 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2021-2023 Nokia + */ + +#ifndef ODP_ABI_ML_TYPES_H_ +#define ODP_ABI_ML_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +/** @internal Dummy type for strong typing */ +typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_ml_model_t; + +/** @internal Dummy type for strong typing */ +typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_ml_compl_t; + +/** @internal Implementation specific ML parameters */ +struct _odp_ml_model_extra_param_t { + /** @internal Dummy field to avoid empty struct */ + char dummy; +}; + +/** @addtogroup odp_ml + * @{ + */ + +typedef _odp_abi_ml_model_t *odp_ml_model_t; +typedef _odp_abi_ml_compl_t *odp_ml_compl_t; +typedef struct _odp_ml_model_extra_param_t odp_ml_model_extra_param_t; + +#define ODP_ML_MODEL_INVALID ((odp_ml_model_t)0) +#define ODP_ML_COMPL_INVALID ((odp_ml_compl_t)0) + +#define ODP_ML_MODEL_NAME_LEN 64 +#define ODP_ML_MODEL_IO_NAME_LEN 64 +#define ODP_ML_SHAPE_NAME_LEN 16 +#define ODP_ML_EXTRA_STAT_NAME_LEN 64 + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/abi-default/packet_io_types.h b/include/odp/api/abi-default/packet_io_types.h index ddf8c3a3f..1aa1cf816 100644 --- a/include/odp/api/abi-default/packet_io_types.h +++ b/include/odp/api/abi-default/packet_io_types.h @@ -25,7 +25,6 @@ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_pktio_t; typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_lso_profile_t; /** @addtogroup odp_packet_io - * Operations on a packet. * @{ */ diff --git a/include/odp/api/abi-default/packet_types.h b/include/odp/api/abi-default/packet_types.h index 300eaf177..e8b2c8484 100644 --- a/include/odp/api/abi-default/packet_types.h +++ b/include/odp/api/abi-default/packet_types.h @@ -27,7 +27,7 @@ typedef struct { char dummy; /**< *internal Dummy */ } _odp_abi_packet_vector_t; /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< *internal Dummy */ } _odp_abi_packet_tx_compl_t; -/** @ingroup odp_packet +/** @addtogroup odp_packet * @{ */ diff --git a/include/odp/api/abi-default/pool_types.h b/include/odp/api/abi-default/pool_types.h index e4ca40422..ce1042c12 100644 --- a/include/odp/api/abi-default/pool_types.h +++ b/include/odp/api/abi-default/pool_types.h @@ -13,7 +13,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_pool_t; -/** @ingroup odp_pool +/** @addtogroup odp_pool * @{ */ diff --git a/include/odp/api/abi-default/proto_stats_types.h b/include/odp/api/abi-default/proto_stats_types.h index 0d87012f3..e17adf886 100644 --- a/include/odp/api/abi-default/proto_stats_types.h +++ b/include/odp/api/abi-default/proto_stats_types.h @@ -15,8 +15,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_proto_stats_t; -/** @ingroup odp_proto_stats - * Operations on a proto stats object. +/** @addtogroup odp_proto_stats * @{ */ diff --git a/include/odp/api/abi-default/queue_types.h b/include/odp/api/abi-default/queue_types.h index 5a1dc40d9..677348c18 100644 --- a/include/odp/api/abi-default/queue_types.h +++ b/include/odp/api/abi-default/queue_types.h @@ -13,7 +13,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_queue_t; -/** @ingroup odp_queue +/** @addtogroup odp_queue * @{ */ diff --git a/include/odp/api/abi-default/shared_memory.h b/include/odp/api/abi-default/shared_memory.h index f4930da27..70d6e906f 100644 --- a/include/odp/api/abi-default/shared_memory.h +++ b/include/odp/api/abi-default/shared_memory.h @@ -12,7 +12,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_shm_t; -/** @ingroup odp_shared_memory +/** @addtogroup odp_shared_memory * @{ */ diff --git a/include/odp/api/abi-default/stash_types.h b/include/odp/api/abi-default/stash_types.h index 10db242d3..6779f3af6 100644 --- a/include/odp/api/abi-default/stash_types.h +++ b/include/odp/api/abi-default/stash_types.h @@ -12,7 +12,7 @@ extern "C" { /** @internal Dummy type for strong typing */ typedef struct { char dummy; /**< @internal Dummy */ } _odp_abi_stash_t; -/** @ingroup odp_stash +/** @addtogroup odp_stash * @{ */ diff --git a/include/odp/api/abi-default/thread_types.h b/include/odp/api/abi-default/thread_types.h index 1511f488d..d8c27fb98 100644 --- a/include/odp/api/abi-default/thread_types.h +++ b/include/odp/api/abi-default/thread_types.h @@ -9,7 +9,7 @@ extern "C" { #endif -/** @ingroup odp_thread +/** @addtogroup odp_thread * @{ */ diff --git a/include/odp/api/abi-default/time_types.h b/include/odp/api/abi-default/time_types.h index 32d9384dd..afbe6d188 100644 --- a/include/odp/api/abi-default/time_types.h +++ b/include/odp/api/abi-default/time_types.h @@ -11,7 +11,7 @@ extern "C" { #include <stdint.h> -/** @ingroup odp_time +/** @addtogroup odp_time * @{ **/ diff --git a/include/odp/api/ml.h b/include/odp/api/ml.h new file mode 100644 index 000000000..55213dd52 --- /dev/null +++ b/include/odp/api/ml.h @@ -0,0 +1,24 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2021 Nokia + */ + +/** + * @file + * + * ODP Machine Learning (ML) offload + */ + +#ifndef ODP_API_ML_H_ +#define ODP_API_ML_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/spec/ml.h> + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/ml_quantize.h b/include/odp/api/ml_quantize.h new file mode 100644 index 000000000..cab2a3f22 --- /dev/null +++ b/include/odp/api/ml_quantize.h @@ -0,0 +1,24 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2023 Nokia + */ + +/** + * @file + * + * ODP Machine Learning (ML) offload + */ + +#ifndef ODP_API_ML_QUANTIZE_H_ +#define ODP_API_ML_QUANTIZE_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/spec/ml_quantize.h> + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/ml_types.h b/include/odp/api/ml_types.h new file mode 100644 index 000000000..3c3f8a416 --- /dev/null +++ b/include/odp/api/ml_types.h @@ -0,0 +1,26 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2021 Nokia + */ + +/** + * @file + * + * ODP Machine Learning (ML) types + */ + +#ifndef ODP_API_ML_TYPES_H_ +#define ODP_API_ML_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/abi/ml_types.h> + +#include <odp/api/spec/ml_types.h> + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/spec/buffer.h b/include/odp/api/spec/buffer.h index 11750136d..5ce2355b8 100644 --- a/include/odp/api/spec/buffer.h +++ b/include/odp/api/spec/buffer.h @@ -22,7 +22,7 @@ extern "C" { #include <odp/api/pool_types.h> #include <odp/api/std_types.h> -/** @defgroup odp_buffer ODP BUFFER +/** @addtogroup odp_buffer * Buffer event metadata and operations. * @{ */ diff --git a/include/odp/api/spec/buffer_types.h b/include/odp/api/spec/buffer_types.h index 7b0e80584..7307e72f7 100644 --- a/include/odp/api/spec/buffer_types.h +++ b/include/odp/api/spec/buffer_types.h @@ -17,7 +17,7 @@ extern "C" { #endif -/** @addtogroup odp_buffer +/** @defgroup odp_buffer ODP BUFFER * @{ */ diff --git a/include/odp/api/spec/crypto.h b/include/odp/api/spec/crypto.h index 49bc29ee4..8b7d1df54 100644 --- a/include/odp/api/spec/crypto.h +++ b/include/odp/api/spec/crypto.h @@ -21,7 +21,7 @@ extern "C" { #endif -/** @defgroup odp_crypto ODP CRYPTO +/** @addtogroup odp_crypto * Data ciphering and authentication. * @{ */ diff --git a/include/odp/api/spec/crypto_types.h b/include/odp/api/spec/crypto_types.h index 31214c0e9..579022762 100644 --- a/include/odp/api/spec/crypto_types.h +++ b/include/odp/api/spec/crypto_types.h @@ -20,7 +20,7 @@ extern "C" { #endif -/** @addtogroup odp_crypto +/** @defgroup odp_crypto ODP CRYPTO * @{ */ diff --git a/include/odp/api/spec/debug.h b/include/odp/api/spec/debug.h index 0cf5179a8..4a3365a3e 100644 --- a/include/odp/api/spec/debug.h +++ b/include/odp/api/spec/debug.h @@ -15,6 +15,10 @@ extern "C" { #endif +/** @addtogroup odp_initialization + * @{ + */ + /** * @def ODP_STATIC_ASSERT * Compile time assertion macro. Fails compilation and outputs message 'msg' @@ -26,6 +30,10 @@ extern "C" { * @param msg Compile time error message to be displayed if cond is false */ +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/include/odp/api/spec/event.h b/include/odp/api/spec/event.h index 220c955c3..69464125b 100644 --- a/include/odp/api/spec/event.h +++ b/include/odp/api/spec/event.h @@ -21,7 +21,7 @@ extern "C" { #include <odp/api/packet_types.h> #include <odp/api/pool_types.h> -/** @defgroup odp_event ODP EVENT +/** @addtogroup odp_event * Generic event metadata and operations. * @{ */ diff --git a/include/odp/api/spec/event_types.h b/include/odp/api/spec/event_types.h index 9df5e03ef..b967e2871 100644 --- a/include/odp/api/spec/event_types.h +++ b/include/odp/api/spec/event_types.h @@ -1,6 +1,6 @@ /* SPDX-License-Identifier: BSD-3-Clause * Copyright (c) 2015-2018 Linaro Limited - * Copyright (c) 2022 Nokia + * Copyright (c) 2022-2023 Nokia */ /** @@ -17,7 +17,7 @@ extern "C" { #endif -/** @addtogroup odp_event +/** @defgroup odp_event ODP EVENT * @{ */ @@ -59,6 +59,8 @@ extern "C" { * completion. * - ODP_EVENT_DMA_COMPL * - DMA completion event (odp_dma_compl_t) indicates that a DMA transfer has finished + * - ODP_EVENT_ML_COMPL + * - ML completion event (odp_ml_compl_t) indicates that an ML operation has finished */ /** @@ -92,6 +94,12 @@ extern "C" { * packet metadata. * - ODP_EVENT_NO_SUBTYPE * - An event type does not have any subtypes defined + * - ODP_EVENT_ML_COMPL_LOAD + * - ML completion event (odp_ml_compl_t) that contains results from a completed model load or + * unload operation. + * - ODP_EVENT_ML_COMPL_RUN + * - ML completion event (odp_ml_compl_t) that contains results from a completed model run + * operation. */ /** diff --git a/include/odp/api/spec/ipsec.h b/include/odp/api/spec/ipsec.h index b66e9a1ca..cdb18116b 100644 --- a/include/odp/api/spec/ipsec.h +++ b/include/odp/api/spec/ipsec.h @@ -23,7 +23,7 @@ extern "C" { #include <odp/api/packet_types.h> #include <odp/api/std_types.h> -/** @defgroup odp_ipsec ODP IPSEC +/** @addtogroup odp_ipsec * IPSEC protocol offload. * @{ */ diff --git a/include/odp/api/spec/ipsec_types.h b/include/odp/api/spec/ipsec_types.h index 00fd944f5..71b53a770 100644 --- a/include/odp/api/spec/ipsec_types.h +++ b/include/odp/api/spec/ipsec_types.h @@ -24,7 +24,7 @@ extern "C" { #include <odp/api/std_types.h> #include <odp/api/traffic_mngr.h> -/** @addtogroup odp_ipsec +/** @defgroup odp_ipsec ODP IPSEC * @{ */ diff --git a/include/odp/api/spec/ml.h b/include/odp/api/spec/ml.h new file mode 100644 index 000000000..1a7710ab3 --- /dev/null +++ b/include/odp/api/spec/ml.h @@ -0,0 +1,699 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2021-2023 Nokia + * Copyright (c) 2021 Marvell + */ + +/** + * @file + * + * ODP Machine Learning (ML) offload + */ + +#ifndef ODP_API_SPEC_ML_H_ +#define ODP_API_SPEC_ML_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/event_types.h> +#include <odp/api/ml_types.h> +#include <odp/api/pool_types.h> +#include <odp/api/std_types.h> + +/** + * @addtogroup odp_ml + * Machine Learning (ML) offload + * @{ + * + * <b> ML API call sequence </b> + * + * Before ML offload can be used, it must be configured with an odp_ml_config() call. An application + * fills in configuration parameters to describe its intended ML offload usage. The parameter + * values may help ODP implementation to optimize memory and other HW resource usage. The + * application may use odp_ml_capability() to check ML capabilities both before and after the + * configuration step. + * + * After configuration, an ML model binary is passed with other parameters to odp_ml_model_create() + * call which checks and prepares the model for usage. The application may use odp_ml_model_info(), + * odp_ml_model_input_info() and odp_ml_model_output_info() calls to check model input and output + * data formats. Before the application can use the model for inference, it loads the model with + * an odp_ml_model_load() or odp_ml_model_load_start() call. After a successful load, the + * application may use e.g. odp_ml_run() or odp_ml_run_start() to perform inferences. + * + * When all previously started inference operations are complete, application uses + * odp_ml_model_unload() or odp_ml_model_unload_start() to unload the model. After a successful + * unload, the model may be destroyed with an odp_ml_model_destroy() call, or loaded again. + * + * <b> Completion identifiers </b> + * + * Completion identifiers are used with ML operations in asynchronous poll mode + * (#ODP_ML_COMPL_MODE_POLL). Application declares the maximum identifier value it will + * use per model with odp_ml_model_param_t.max_compl_id parameter. It cannot exceed + * the implementation capability of odp_ml_capability_t.max_compl_id. Completion identifier + * values are model specific. The same value can be used simultaneously with two different + * models, but cannot be used simultaneously in two ML operations on the same model. A value may be + * reused for the next ML operation (on the same model) only after the previous operation is + * complete. Within those limitations, application may use/reuse completion identifier + * values from 0 to max_compl_id range freely. + */ + +/** + * Query ML capabilities + * + * Outputs ML capabilities on success. Use this capability call to check ML offload implementation + * limits and its support of various ML API features. When ML offload is not available, + * odp_ml_capability_t.max_models is zero. + * + * @param[out] capa Pointer to a capability structure for output + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ml_capability(odp_ml_capability_t *capa); + +/** + * Initialize ML configuration parameters + * + * Initialize an odp_ml_config_t to its default values. + * + * @param[out] config Configuration structure to be initialized + */ +void odp_ml_config_init(odp_ml_config_t *config); + +/** + * Configure ML offload + * + * Initializes and configures ML offload according to the configuration parameters. This function + * must be called only once and before any ML resources are created. Use odp_ml_capability() to + * query configuration capabilities and odp_ml_config_init() to initialize configuration + * parameters into their default values. + * + * @param config ML configuration parameters + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ml_config(const odp_ml_config_t *config); + +/** + * Initialize ML model parameters + * + * Initialize an odp_ml_model_param_t to its default values. + * + * @param[out] param Parameters structure to be initialized + */ +void odp_ml_model_param_init(odp_ml_model_param_t *param); + +/** + * Create an ML model + * + * Creates an ML model according to the parameters. Use odp_ml_model_param_init() to initialize + * parameters into their default values. The use of model name is optional. Unique names are not + * required. However, odp_ml_model_lookup() returns only a single matching model. Maximum name + * string length is #ODP_ML_MODEL_NAME_LEN. + * + * The call copies the model binary and prepares it for loading. Application may free memory + * buffers pointed by the parameters when the call returns. Use odp_ml_model_load() + * or odp_ml_model_load_start() to load the model. A model is ready for inference runs + * (see e.g. odp_ml_run()) after it has been loaded successfully. + * + * When model metadata misses some details of model input / output data format, user can + * pass those with odp_ml_model_param_t.extra_info. Some ODP implementations may define + * implementation specific extra parameters (e.g. hints about HW resource usage), user can pass + * those with odp_ml_model_param_t.extra_param when applicable. + * + * @param name Name of the model, or NULL + * @param param ML model parameters + * + * @return ML model handle on success + * @retval ODP_ML_MODEL_INVALID on failure + */ +odp_ml_model_t odp_ml_model_create(const char *name, const odp_ml_model_param_t *param); + +/** + * Destroy an ML model + * + * Destroys a model and releases the resources reserved for it. If the model has been loaded, it + * must be unloaded (see odp_ml_model_unload() or odp_ml_model_unload_start()) prior to calling + * this function. + * + * @param model ML model to be destroyed + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ml_model_destroy(odp_ml_model_t model); + +/** + * Find a model by name + * + * @param name Name of the model + * + * @return Handle of the first matching ML model + * @retval ODP_ML_MODEL_INVALID Model could not be found + */ +odp_ml_model_t odp_ml_model_lookup(const char *name); + +/** + * Load ML model + * + * Loads ML model in synchronous mode. When the call returns, load is complete and the model is + * ready for inference requests. A loaded model must be unloaded before it can be destroyed. + * The same model can be loaded and unloaded multiple times before being destroyed. + * + * The call optionally outputs results. Use NULL as 'result' pointer if results are not required. + * + * Application should not try to keep loaded more than configured number of models + * (odp_ml_config_t.max_models_loaded). Check ML capabilities for maximum number of loaded + * models (odp_ml_capability_t.max_models_loaded) and support of load completion modes + * (odp_ml_capability_t.load). + * + * @param model ML model to be loaded + * @param[out] result Pointer to load result structure for output, or NULL + * + * @retval 0 Model load was successful + * @retval <0 on failure + */ +int odp_ml_model_load(odp_ml_model_t model, odp_ml_load_result_t *result); + +/** + * Start asynchronous model load + * + * Otherwise like odp_ml_model_load(), but loads the model asynchronously. A successful call + * requests the model to be loaded, but does not wait for load completion. Completion parameters + * are used to select if load completion is reported in poll (#ODP_ML_COMPL_MODE_POLL) or event + * (#ODP_ML_COMPL_MODE_EVENT) mode. For poll mode, odp_ml_model_load_status() is called to check + * for completion. For event mode, ML offload sends the completion event into the completion + * queue when the load is complete. Use odp_ml_compl_param_init() to initialize completion + * parameters into their default values. + * + * @param model ML model to be loaded + * @param compl_param Completion parameters for load + * + * @retval 0 Model load started successfully + * @retval <0 on failure + */ +int odp_ml_model_load_start(odp_ml_model_t model, const odp_ml_compl_param_t *compl_param); + +/** + * Check model load completion + * + * Checks if a previously started model load (in #ODP_ML_COMPL_MODE_POLL mode) has completed. + * The completion identifier value from load operation completion parameters + * (odp_ml_compl_param_t.compl_id) is passed as a parameter. It specifies the load operation to be + * checked. Initially 0 is returned for all configured (but unused) completion identifier values. + * An odp_ml_model_load_start() call clears the previous completion status of an identifier, and + * this function returns 0 while the load is in progress. When the load is successfully + * complete, >0 is returned. If the load completed with a failure, -1 is returned. The same + * value is returned until the next start operation that reuses the identifier (with the same + * model). The completion identifier may be reused only after >0 or -1 is returned. + * + * Optionally, outputs more detailed operation results into odp_ml_load_result_t structure. + * Use NULL as 'result' pointer if these results are not required. + * + * @param model ML model being loaded + * @param compl_id Completion identifier that was used in load start + * @param[out] result Pointer to load result structure for output, or NULL + * + * @retval >0 Model load was successful + * @retval 0 Model load has not finished + * @retval -1 Model load failed + * @retval <-1 Failed to read completion status (e.g. bad handle) + */ +int odp_ml_model_load_status(odp_ml_model_t model, uint32_t compl_id, odp_ml_load_result_t *result); + +/** + * Unload ML model + * + * Unloads ML model in synchronous mode. All previously started inference operations must have been + * completed before model unload is attempted. When the call returns, unload is complete and the + * model is ready to be destroyed or loaded again. + * + * The call optionally outputs results. Use NULL as 'result' pointer if results are not required. + * + * @param model ML model to be unloaded + * @param[out] result Pointer to load result structure for output, or NULL + * + * @retval 0 Model unload was successful + * @retval <0 on failure + */ +int odp_ml_model_unload(odp_ml_model_t model, odp_ml_load_result_t *result); + +/** + * Start asynchronous model unload + * + * Otherwise like odp_ml_model_unload(), but unloads the model asynchronously. A successful call + * requests the model to be unloaded, but does not wait for unload completion. Completion + * parameters are used to select if unload completion is reported in poll (#ODP_ML_COMPL_MODE_POLL) + * or event (#ODP_ML_COMPL_MODE_EVENT) mode. For poll mode, odp_ml_model_unload_status() is called + * to check for completion. For event mode, ML offload sends the completion event into the + * completion queue when the unload is complete. Use odp_ml_compl_param_init() to initialize + * completion parameters into their default values. + * + * @param model ML model to be unloaded + * @param compl_param Completion parameters for unload + * + * @retval 0 Model unload started successfully + * @retval <0 on failure + */ +int odp_ml_model_unload_start(odp_ml_model_t model, const odp_ml_compl_param_t *compl_param); + +/** + * Check model unload completion + * + * Checks if a previously started model unload (in #ODP_ML_COMPL_MODE_POLL mode) has completed. + * The completion identifier value from unload operation completion parameters + * (odp_ml_compl_param_t.compl_id) is passed as a parameter. It specifies the unload operation to be + * checked. Initially 0 is returned for all configured (but unused) completion identifier values. + * An odp_ml_model_unload_start() call clears the previous completion status of an identifier, and + * this function returns 0 while the unload is in progress. When the unload is successfully + * complete, >0 is returned. If the unload completed with a failure, -1 is returned. The same + * value is returned until the next start operation that reuses the identifier (with the same + * model). The completion identifier may be reused only after >0 or -1 is returned. + * + * Optionally, outputs more detailed operation results into odp_ml_load_result_t structure. + * Use NULL as 'result' pointer if these results are not required. + * + * @param model ML model being unloaded + * @param compl_id Completion identifier that was used in unload start + * @param[out] result Pointer to load result structure for output, or NULL + * + * @retval >0 Model unload was successful + * @retval 0 Model unload has not finished + * @retval -1 Model unload failed + * @retval <-1 Failed to read completion status (e.g. bad handle) + */ +int odp_ml_model_unload_status(odp_ml_model_t model, uint32_t compl_id, + odp_ml_load_result_t *result); + +/** + * Initialize model run parameters + * + * Initialize an odp_ml_run_param_t to its default values. + * + * @param[out] param Model run parameters structure to be initialized + */ +void odp_ml_run_param_init(odp_ml_run_param_t *param); + +/** + * Run the model in synchronous mode + * + * Performs an ML inference operation using the model and input data pointed by the data descriptor. + * A successful operation writes inference output data into memory buffers pointed by the data + * descriptor. Input/output data buffers are described as an array of segment descriptors. Each + * segment descriptor specifies a memory buffer used with only one model input/output. Multiple + * subsequent descriptors may be used to specify segmented data for the same input/output. + * When the model has multiple inputs/outputs, descriptor order in the array follows the model + * input/output order reported by odp_ml_model_input_info() and odp_ml_model_output_info() calls. + * All memory buffers for the first input/output are specified before any buffers for the second + * input/output, and so on. + * + * When some model inputs/outputs have #ODP_ML_SHAPE_BATCH shape type, the batch size is specified + * in run parameters (odp_ml_run_param_t.batch_size). The same batch size is used for all such + * inputs/outputs. Application may request additional operation results by setting 'result' pointer + * in run parameters. Use odp_ml_run_param_init() to initialize run parameters into their default + * values. Default run parameter values are used when 'param' is NULL. + * + * Returns 1 when model run completed successfully. Returns 0 when the operation was not performed + * due to ML offload resources being temporarily busy. Returns <0 on failure. + * + * @param model ML model to be run + * @param data Model input/output data descriptor + * @param param Model run parameters, or NULL + * + * @retval 1 Model run completed successfully + * @retval 0 Resources are busy and model was not run + * @retval <0 on failure + */ +int odp_ml_run(odp_ml_model_t model, const odp_ml_data_t *data, const odp_ml_run_param_t *param); + +/** + * Run the model multiple times in synchronous mode + * + * Otherwise like odp_ml_run(), but runs the model 'num' times with different input/output + * data buffers. Output data buffers of one ML inference operation must not overlap with + * input/output data buffers of another one. + * + * Returns number of model runs successfully completed. When return value is less than 'num', + * the remaining runs were not performed due to ML offload resources being temporarily busy. + * Returns <0 on failure. + * + * @param model ML model to be run + * @param data Array of model input/output data descriptors. The array has 'num' elements. + * @param param Array of model run parameters, or NULL. The array has 'num' elements + * when used. + * @param num Number of model runs to perform + * + * @return Number of model runs completed successfully (1 ... num) + * @retval 0 Resources are busy and model was not run + * @retval <0 on failure + */ +int odp_ml_run_multi(odp_ml_model_t model, const odp_ml_data_t data[], + const odp_ml_run_param_t param[], int num); + +/** + * Start model run in asynchronous mode + * + * Otherwise like odp_ml_run(), but runs the model asynchronously. A successful call + * requests the model to be run, but does not wait for run completion. Completion parameters + * select if run completion is reported in poll (#ODP_ML_COMPL_MODE_POLL) or event + * (#ODP_ML_COMPL_MODE_EVENT) mode. For poll mode, odp_ml_run_status() is called to check + * for completion. For event mode, ML offload sends the completion event into the completion queue + * when the run is complete. Use odp_ml_compl_param_init() to initialize completion parameters + * into their default values. + * + * Additional operation results (odp_ml_run_result_t) are available through the status call + * (odp_ml_run_status()) or completion event (odp_ml_compl_run_result()). Results are + * not output through the run parameters structure (i.e. odp_ml_run_param_t.result is ignored). + * + * Returns 1 when model run was started successfully. Returns 0 when model run was not started + * due to ML offload resources being temporarily busy. Returns <0 on failure. + * + * @param model ML model to be run + * @param data Model input/output data descriptor + * @param compl_param Completion parameters + * @param run_param Model run parameters, or NULL + * + * @retval 1 Model run started successfully + * @retval 0 Resources are busy and model run was not started + * @retval <0 on failure + */ +int odp_ml_run_start(odp_ml_model_t model, const odp_ml_data_t *data, + const odp_ml_compl_param_t *compl_param, const odp_ml_run_param_t *run_param); + +/** + * Start multiple model runs in asynchronous mode + * + * Otherwise like odp_ml_run_start(), but starts 'num' model runs with different input/output + * data buffers. Output data buffers of one ML inference operation must not overlap with + * input/output data buffers of another one. + * + * Returns number of model runs started successfully. When return value is less than 'num', + * the remaining runs were not started due to ML offload resources being temporarily busy. + * Returns <0 on failure. + * + * @param model ML model to be run + * @param data Array of model input/output data descriptors. The array has 'num' elements. + * @param compl_param Array of completion parameters. The array has 'num' elements. + * @param run_param Array of model run parameters, or NULL. The array has 'num' elements + * when used. + * @param num Number of model runs to start + * + * @return Number of model runs started successfully (1 ... num) + * @retval 0 Resources are busy and model runs were not started + * @retval <0 on failure + */ +int odp_ml_run_start_multi(odp_ml_model_t model, const odp_ml_data_t data[], + const odp_ml_compl_param_t compl_param[], + const odp_ml_run_param_t run_param[], int num); + +/** + * Check model run completion + * + * Checks if a previously started model run (in #ODP_ML_COMPL_MODE_POLL mode) has completed. + * The completion identifier value from run operation completion parameters + * (odp_ml_compl_param_t.compl_id) is passed as a parameter. It specifies the run operation to be + * checked. Initially 0 is returned for all configured (but unused) completion identifier values. + * An odp_ml_run_start() call clears the previous completion status of an identifier, and + * this function returns 0 while the run is in progress. When the run is successfully + * complete, >0 is returned. If the run completed with a failure, -1 is returned. The same + * value is returned until the next start operation that reuses the identifier (with the same + * model). The completion identifier may be reused only after >0 or -1 is returned. + * + * Optionally, outputs more detailed operation results into odp_ml_run_result_t structure. + * Use NULL as 'result' pointer if these results are not required. + * + * @param model ML model running + * @param compl_id Completion identifier that was used in run start + * @param[out] result Pointer to run result structure for output, or NULL + * + * @retval >0 Model run was successful + * @retval 0 Model run has not finished + * @retval -1 Model run failed + * @retval <-1 Failed to read completion status (e.g. bad handle) + */ +int odp_ml_run_status(odp_ml_model_t model, uint32_t compl_id, odp_ml_run_result_t *result); + +/** + * Initialize ML completion event pool parameters + * + * Initialize an odp_ml_compl_pool_param_t to its default values. + * + * @param[out] param Parameter structure to be initialized + */ +void odp_ml_compl_pool_param_init(odp_ml_compl_pool_param_t *param); + +/** + * Create ML completion event pool + * + * Creates a pool of ML completion events (ODP_EVENT_ML_COMPL). Pool type is ODP_POOL_ML_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_ml_compl_pool_param_init() to initialize pool + * parameters into their default values. Parameters values must not exceed pool capabilities + * (see odp_ml_compl_pool_capability_t). + * + * @param name Name of the pool or NULL. Maximum string length is #ODP_POOL_NAME_LEN. + * @param param Pool parameters + * + * @return Pool handle on success + * @retval ODP_POOL_INVALID on failure + */ +odp_pool_t odp_ml_compl_pool_create(const char *name, const odp_ml_compl_pool_param_t *param); + +/** + * Allocate ML completion event + * + * Allocates an ML completion event from a pool. The pool must have been created with + * odp_ml_compl_pool_create() call. All completion event metadata are set to their default values. + * + * @param pool ML completion event pool + * + * @return ML completion event handle + * @retval ODP_ML_COMPL_INVALID Completion event could not be allocated + */ +odp_ml_compl_t odp_ml_compl_alloc(odp_pool_t pool); + +/** + * Free ML completion event + * + * Frees an ML completion event into the pool it was allocated from. + * + * @param ml_compl ML completion event handle + */ +void odp_ml_compl_free(odp_ml_compl_t ml_compl); + +/** + * Check ML model run results from completion event + * + * Reads model run results from an ML completion event (ODP_EVENT_ML_COMPL). The event indicates + * completion of a previously started inference operation. Subtype of the completion event must be + * ODP_EVENT_ML_COMPL_RUN. Function return value indicates if the model run succeeded or failed. + * Additionally, outputs more detailed results into the provided odp_ml_run_result_t + * structure. Use NULL as 'result' pointer if those results are not required. + * + * @param ml_compl ML completion event (subtype ODP_EVENT_ML_COMPL_RUN) + * @param[out] result Pointer to ML run result structure for output, or NULL. + * + * @retval 0 Model run was successful + * @retval -1 Model run failed + * @retval <-1 Failed to read results from the event (e.g. bad handle) + */ +int odp_ml_compl_run_result(odp_ml_compl_t ml_compl, odp_ml_run_result_t *result); + +/** + * Check ML model load / unload results from completion event + * + * Reads model load / unload results from an ML completion event (ODP_EVENT_ML_COMPL). The event + * indicates completion of a previously started model load / unload operation. Subtype of the + * completion event must be ODP_EVENT_ML_COMPL_LOAD. Function return value indicates if the model + * load / unload succeeded or failed. Additionally, outputs more detailed results into the provided + * odp_ml_load_result_t structure. Use NULL as 'result' pointer if those results are not required. + * + * @param ml_compl ML completion event (subtype ODP_EVENT_ML_COMPL_LOAD) + * @param[out] result Pointer to model load / unload result structure for output, or NULL. + * + * @retval 0 Model load / unload was successful + * @retval -1 Model load / unload failed + * @retval <-1 Failed to read results from the event (e.g. bad handle) + */ +int odp_ml_compl_load_result(odp_ml_compl_t ml_compl, odp_ml_load_result_t *result); + +/** + * ML completion event user area + * + * Returns pointer to the user area associated with the completion event. Size of the area is + * fixed and defined in pool parameters. + * + * @param ml_compl ML completion event + * + * @return Pointer to the user area of the completion event + * @retval NULL The completion event does not have user area + */ +void *odp_ml_compl_user_area(odp_ml_compl_t ml_compl); + +/** + * Convert event to ML completion event + * + * Converts an ODP_EVENT_ML_COMPL type event to an ML completion event. + * + * @param event Event handle + * + * @return ML completion event handle + */ +odp_ml_compl_t odp_ml_compl_from_event(odp_event_t event); + +/** + * Convert ML completion event to event + * + * @param ml_compl ML completion event handle + * + * @return Event handle + */ +odp_event_t odp_ml_compl_to_event(odp_ml_compl_t ml_compl); + +/** + * Convert ML completion event handle to a uint64_t value for debugging + * + * @param ml_compl ML completion event handle to be converted + * + * @return uint64_t value that can be used for debugging (e.g. printed) + */ +uint64_t odp_ml_compl_to_u64(odp_ml_compl_t ml_compl); + +/** + * Initialize ML completion parameters + * + * Initialize an odp_ml_compl_param_t to its default values. + * + * @param[out] param Address of parameters structure to be initialized + */ +void odp_ml_compl_param_init(odp_ml_compl_param_t *param); + +/** + * Retrieve model information + * + * Retrieve information about the model. Model information includes e.g. version numbers and + * number of model inputs/outputs. Information about each input and output can be retrieved with + * odp_ml_model_input_info() and odp_ml_model_output_info() calls. + * + * @param model ML model handle + * @param[out] info Pointer to model information structure for output + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_ml_model_info(odp_ml_model_t model, odp_ml_model_info_t *info); + +/** + * Retrieve model input information + * + * Writes information about each model input into the array. If there are more inputs than array + * elements, writes only 'num' elements. Returns the number of model inputs on success, and zero on + * failure. When 'num' is zero, ignores value of 'info' and returns normally. + * + * @param model ML model handle + * @param[out] info Pointer to model input information array for output + * @param num Number of elements in the array + * + * @return Number of model inputs + * @retval 0 on failure + */ +uint32_t odp_ml_model_input_info(odp_ml_model_t model, odp_ml_input_info_t info[], uint32_t num); + +/** + * Retrieve model output information + * + * Writes information about each model output into the array. If there are more outputs than array + * elements, writes only 'num' elements. Returns the number of model outputs on success, and zero on + * failure. When 'num' is zero, ignores value of 'info' and returns normally. + * + * @param model ML model handle + * @param[out] info Pointer to model output information array for output + * @param num Number of elements in the array + * + * @return Number of model outputs + * @retval 0 on failure + */ +uint32_t odp_ml_model_output_info(odp_ml_model_t model, odp_ml_output_info_t info[], uint32_t num); + +/** + * Convert ML model handle to a uint64_t value for debugging + * + * @param model ML model handle + * + * @return uint64_t value that can be used for debugging (e.g. printed) + */ +uint64_t odp_ml_model_to_u64(odp_ml_model_t model); + +/** + * Print debug information about the model. + * + * Print implementation defined information about ML model to the ODP log. The information is + * intended to be used for debugging. + + * @param model ML model handle + */ +void odp_ml_model_print(odp_ml_model_t model); + +/** + * Print ML debug information + * + * Print implementation defined information about ML offload to the ODP log. The information is + * intended to be used for debugging. + */ +void odp_ml_print(void); + +/** + * Extra statistics counter information + * + * Returns the number of extra statistics counters supported by the ML offload, and outputs + * information (e.g. name) about those. Counters are implementation specific and maintained + * per model. Statistics counting is enabled through model create parameters. + * + * When 'info' pointer is not NULL, fills in up to 'num' counter info structures. If the return + * value is larger than 'num', there are more counters than the function was allowed to output. + * If the return value N is less than 'num' (on success), only first N structures have been written. + * + * Info array elements are filled in the same order than odp_ml_model_extra_stats() outputs + * counter values. + * + * @param model ML model + * @param[out] info Pointer to extra statistics counter information array for output. + * NULL may be used to query only the number of counters. + * @param num Number of elements in the array + * + * @return Number of extra statistics counters + * @retval <0 on failure + */ +int odp_ml_model_extra_stat_info(odp_ml_model_t model, odp_ml_extra_stat_info_t info[], int num); + +/** + * Read extra statistics counter values + * + * Reads extra statistics counter values and returns the number of supported counters. Outputs + * up to 'num' counter values into 'stats' array. If the return value is larger than 'num', + * there are more counters than the function was allowed to output. If the return value N is less + * than 'num' (on success), only first N counters have been written. The order of counters in + * the array matches the counter information array order on odp_ml_model_extra_stat_info() output. + * + * @param model ML model + * @param[out] stats Pointer to extra statistics counter array for output + * @param num Number of elements in the array + * + * @return Number of extra statistics counters + * @retval <0 on failure + */ +int odp_ml_model_extra_stats(odp_ml_model_t model, uint64_t stats[], int num); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif diff --git a/include/odp/api/spec/ml_quantize.h b/include/odp/api/spec/ml_quantize.h new file mode 100644 index 000000000..25565ef27 --- /dev/null +++ b/include/odp/api/spec/ml_quantize.h @@ -0,0 +1,124 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2023 Nokia + */ + +/** + * @file + * + * ODP Machine Learning (ML) quantization functions + */ + +#ifndef ODP_API_SPEC_ML_QUANTIZE_H_ +#define ODP_API_SPEC_ML_QUANTIZE_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/std_types.h> + +/** @addtogroup odp_ml + * @{ + */ + +/** + * Quantize 32-bit float to uint8_t + * + * Quantizes 'num' 32-bit floating point values to uint8_t values using the provided scale and + * zero point. + * + * dst_u8 = (src_fp32 / scale) + zerop + * + * @param[out] dst_u8 Destination address for quantized values + * @param src_fp32 Source address of values to be quantized + * @param num Number of values + * @param scale Scale for quantization + * @param zerop Zero point for quantization + */ +void odp_ml_fp32_to_uint8(uint8_t *dst_u8, const float *src_fp32, uint32_t num, + float scale, uint8_t zerop); + +/** + * De-quantize 32-bit float from uint8_t + * + * De-quantizes 'num' 32-bit floating point values from uint8_t values using the provided scale and + * zero point. + * + * dst_fp32 = (src_u8 - zerop) * scale + * + * @param[out] dst_fp32 Destination address for de-quantized values + * @param src_u8 Source address of values to be de-quantized + * @param num Number of values + * @param scale Scale for de-quantization + * @param zerop Zero point for de-quantization + */ +void odp_ml_fp32_from_uint8(float *dst_fp32, const uint8_t *src_u8, uint32_t num, + float scale, uint8_t zerop); + +/** + * Quantize 32-bit float to int8_t + * + * Quantizes 'num' 32-bit floating point values to int8_t values using the provided scale and + * zero point. + * + * dst_i8 = (src_fp32 / scale) + zerop + * + * @param[out] dst_i8 Destination address for quantized values + * @param src_fp32 Source address of values to be quantized + * @param num Number of values + * @param scale Scale for quantization + * @param zerop Zero point for quantization + */ +void odp_ml_fp32_to_int8(int8_t *dst_i8, const float *src_fp32, uint32_t num, float scale, + int8_t zerop); + +/** + * De-quantize 32-bit float from int8_t + * + * De-quantizes 'num' 32-bit floating point values from int8_t values using the provided scale and + * zero point. + * + * dst_fp32 = (src_i8 - zerop) * scale + * + * @param[out] dst_fp32 Destination address for de-quantized values + * @param src_i8 Source address of values to be de-quantized + * @param num Number of values + * @param scale Scale for de-quantization + * @param zerop Zero point for de-quantization + */ +void odp_ml_fp32_from_int8(float *dst_fp32, const int8_t *src_i8, uint32_t num, float scale, + int8_t zerop); + +/** + * Quantize 32-bit float to 16-bit float + * + * Quantizes 'num' 32-bit floating point values to 16-bit floating point values. + * + * @param[out] dst_fp16 Destination address for quantized values + * @param src_fp32 Source address of values to be quantized + * @param num Number of values + */ +void odp_ml_fp32_to_fp16(uint16_t *dst_fp16, const float *src_fp32, uint32_t num); + +/** + * De-quantize 32-bit float from 16-bit float + * + * De-quantizes 'num' 32-bit floating point values from 16-bit floating point values. + * + * @param[out] dst_fp32 Destination address for de-quantized values + * @param src_fp16 Source address of values to be de-quantized + * @param num Number of values + */ +void odp_ml_fp32_from_fp16(float *dst_fp32, const uint16_t *src_fp16, uint32_t num); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif diff --git a/include/odp/api/spec/ml_types.h b/include/odp/api/spec/ml_types.h new file mode 100644 index 000000000..2b8f9d6c8 --- /dev/null +++ b/include/odp/api/spec/ml_types.h @@ -0,0 +1,873 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2021-2023 Nokia + * Copyright (c) 2021 Marvell + */ + +/** + * @file + * + * ODP Machine Learning (ML) types + */ + +#ifndef ODP_API_SPEC_ML_TYPES_H_ +#define ODP_API_SPEC_ML_TYPES_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/event_types.h> +#include <odp/api/queue_types.h> +#include <odp/api/std_types.h> + +/** @defgroup odp_ml ODP ML + * @{ + */ + +/** + * @typedef odp_ml_model_t + * ODP ML model handle + */ + +/** + * @def ODP_ML_MODEL_INVALID + * Invalid ML model + */ + +/** + * @typedef odp_ml_compl_t + * ML completion event + */ + +/** + * @def ODP_ML_COMPL_INVALID + * Invalid ML completion event + */ + +/** + * @def ODP_ML_MODEL_NAME_LEN + * Maximum length of model name in chars (including null char) + */ + +/** + * @def ODP_ML_MODEL_IO_NAME_LEN + * Maximum length of model input/output name in chars (including null char) + */ + +/** + * @def ODP_ML_SHAPE_NAME_LEN + * Maximum length of data dimension name in chars (including null char) + */ + +/** + * @def ODP_ML_EXTRA_STAT_NAME_LEN + * Maximum length of extra statistics counter name in chars (including null char) + */ + +/** + * @typedef odp_ml_model_extra_param_t + * ODP implementation specific extra parameters for model creation + */ + +/** Maximum number of dimensions in input / output data shape */ +#define ODP_ML_MAX_DIMS 8 + +/** Dimension size is dynamic */ +#define ODP_ML_DIM_DYNAMIC 0 + +/** Synchronous operation */ +#define ODP_ML_COMPL_MODE_SYNC 0x1u + +/** + * Asynchronous poll mode operation + * + * A function call starts an operation and a status function call indicates when + * the operation has finished. + */ +#define ODP_ML_COMPL_MODE_POLL 0x2u + +/** + * Asynchronous event mode operation + * + * A function call starts an operation and a completion event indicates when + * the operation has finished. + */ +#define ODP_ML_COMPL_MODE_EVENT 0x4u + +/** ML completion mode */ +typedef uint32_t odp_ml_compl_mode_t; + +/** + * ML completion event pool capabilities + * + * Pool statistics are not supported with ML completion event pools. + */ +typedef struct odp_ml_compl_pool_capability_t { + /** + * Maximum number of ML completion event pools + * + * See odp_pool_capability_t.max_pools for maximum number of pools of any type. It + * includes also ML completion event pools. + */ + uint32_t max_pools; + + /** Maximum number of ML completion events in a pool */ + uint32_t max_num; + + /** Maximum user area size in bytes */ + uint32_t max_uarea_size; + + /** User area persistence + * + * See buf.uarea_persistence of odp_pool_capability_t for details + * (odp_pool_capability_t.uarea_persistence). + */ + odp_bool_t uarea_persistence; + + /** Maximum size of local thread cache */ + uint32_t max_cache_size; + + /** Minimum size of local thread cache */ + uint32_t min_cache_size; + +} odp_ml_compl_pool_capability_t; + +/** + * ML completion event pool parameters + * + * Use odp_ml_compl_pool_param_init() to initialize the structure to its default values. + */ +typedef struct odp_ml_compl_pool_param_t { + /** + * Number of ML completion events in the pool + * + * The maximum supported value is defined by ML pool capability 'max_num' + * (odp_ml_compl_pool_capability_t.max_num). + */ + uint32_t num; + + /** + * User area size in bytes + * + * The maximum supported value is defined by ML pool capability 'max_uarea_size'. + * Specify as zero if no user area is needed. The default value is 0. + */ + uint32_t uarea_size; + + /** Parameters for user area initialization */ + struct { + /** See uarea_init.init_fn of odp_pool_param_t for details + * (odp_pool_param_t.init_fn). Function is called during + * odp_ml_compl_pool_create(). The default value is NULL. */ + void (*init_fn)(void *uarea, uint32_t size, void *args, uint32_t index); + + /** See uarea_init.args of odp_pool_param_t for details + * (odp_pool_param_t.args). The default value is NULL. */ + void *args; + + } uarea_init; + + /** + * 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' ML pool capability. The default value is + * implementation specific and set by odp_ml_compl_pool_param_init(). + */ + uint32_t cache_size; + +} odp_ml_compl_pool_param_t; + +/** Machine learning capabilities */ +typedef struct odp_ml_capability_t { + /** Maximum number of models + * + * Maximum number of models that can be created simultaneously. The value is zero when + * ML offload is not available. */ + uint32_t max_models; + + /** Maximum number of models that can be loaded simultaneously */ + uint32_t max_models_loaded; + + /** Maximum model size in bytes */ + uint64_t max_model_size; + + /** Maximum completion identifier value */ + uint32_t max_compl_id; + + /** Maximum number of model inputs */ + uint32_t max_inputs; + + /** Maximum number of model outputs */ + uint32_t max_outputs; + + /** + * Maximum number of data segments per model input + * + * Segmented input data is not supported when 1. + */ + uint32_t max_segs_per_input; + + /** + * Maximum number of data segments per model output + * + * Segmented output data is not supported when 1. + */ + uint32_t max_segs_per_output; + + /** + * Minimum input data alignment in bytes + * + * For each model input, the first data segment must start at this or a higher power of two + * memory alignment in bytes. The value is 1 when there is no alignment requirement. + */ + uint32_t min_input_align; + + /** + * Minimum output data alignment in bytes + * + * For each model output, the first data segment must start at this or a higher power of two + * memory alignment in bytes. The value is 1 when there is no alignment requirement. + */ + uint32_t min_output_align; + + /** + * Input data packing + * + * 0: Data packing is not required. + * 1: Data for all model inputs must be continuous in memory. The memory block starts with + * data for the first input and continues through all inputs in-order and without gaps + * between inputs. The minimum alignment requirement (min_input_align) applies only for + * the first input. + */ + odp_bool_t packed_input_data; + + /** + * Output data packing + * + * 0: Data packing is not required. + * 1: Data buffer space for all model outputs must be continuous in memory. The memory + * block starts with buffer space for the first output and continues through all outputs + * in-order and without gaps between outputs. The minimum alignment requirement + * (min_output_align) applies only for the first output. + */ + odp_bool_t packed_output_data; + + /** Model load / unload capabilities */ + struct { + /** + * Supported completion modes for model load / unload operations + * + * Mask of supported completion modes. Each supported mode has the corresponding + * flag (e.g. #ODP_ML_COMPL_MODE_SYNC) set in the mask. + */ + odp_ml_compl_mode_t compl_mode_mask; + + /** + * Support of model load / unload completion into plain queues + * + * Specifies if plain queues are supported as destination queues for + * load / unload completion events (#ODP_ML_COMPL_MODE_EVENT). + * + * 0: Plain queues are not supported as completion queues + * 1: Plain queues are supported as completion queues + */ + odp_bool_t compl_queue_plain; + + /** + * Support of model load / unload completion into scheduled queues + * + * Specifies if scheduled queues are supported as destination queues for + * load / unload completion events (#ODP_ML_COMPL_MODE_EVENT). + * + * 0: Scheduled queues are not supported as completion queues + * 1: Scheduled queues are supported as completion queues + */ + odp_bool_t compl_queue_sched; + + } load; + + /** Model run capabilities */ + struct { + /** + * Supported completion modes for model run operations + * + * Mask of supported completion modes. Each supported mode has the corresponding + * flag (e.g. #ODP_ML_COMPL_MODE_SYNC) set in the mask. + */ + odp_ml_compl_mode_t compl_mode_mask; + + /** + * Support of model run completion into plain queues + * + * Specifies if plain queues are supported as destination queues for + * run completion events (#ODP_ML_COMPL_MODE_EVENT). + * + * 0: Plain queues are not supported as completion queues + * 1: Plain queues are supported as completion queues + */ + odp_bool_t compl_queue_plain; + + /** + * Support of model run completion into scheduled queues + * + * Specifies if scheduled queues are supported as destination queues for + * run completion events (#ODP_ML_COMPL_MODE_EVENT). + * + * 0: Scheduled queues are not supported as completion queues + * 1: Scheduled queues are supported as completion queues + */ + odp_bool_t compl_queue_sched; + + } run; + + /** ML completion event pool capabilities */ + odp_ml_compl_pool_capability_t pool; + +} odp_ml_capability_t; + +/** Machine learning configuration parameters */ +typedef struct odp_ml_config_t { + /** + * Maximum number of models + * + * Application may create and use this many models simultaneously. The default value is 1. + */ + uint32_t max_models_created; + + /** + * Maximum number of models loaded + * + * Maximum number of models that the application will keep loaded simultaneously. + * The default value is 1. + */ + uint32_t max_models_loaded; + + /** + * Maximum model binary size in bytes + * + * All model binaries application will pass to odp_ml_model_create() are this size or + * smaller. + */ + uint64_t max_model_size; + + /** + * Load / unload completion modes + * + * Mask of completion modes that application will use with model load/unload operations. + * Multiple modes may be selected, but it is implementation specific if some combinations + * are not supported. In case of an unsupported combination odp_ml_config() returns + * failure. Check odp_ml_capability_t.load for supported modes. The default value is 0. + */ + odp_ml_compl_mode_t load_mode_mask; + + /** + * Run completion modes + * + * Mask of completion modes that application will use with model run operations. + * Multiple modes may be selected, but it is implementation specific if some combinations + * are not supported. In case of an unsupported combination odp_ml_config() returns + * failure. Check odp_ml_capability_t.run for supported modes. The default value is 0. + */ + odp_ml_compl_mode_t run_mode_mask; + +} odp_ml_config_t; + +/** Model input / output data type enumeration */ +typedef enum { + /** Data type is not defined */ + ODP_ML_DATA_TYPE_NONE = 0, + + /** 8-bit integer */ + ODP_ML_DATA_TYPE_INT8, + + /** 8-bit unsigned integer */ + ODP_ML_DATA_TYPE_UINT8, + + /** 16-bit integer */ + ODP_ML_DATA_TYPE_INT16, + + /** 16-bit unsigned integer */ + ODP_ML_DATA_TYPE_UINT16, + + /** 24-bit integer */ + ODP_ML_DATA_TYPE_INT24, + + /** 24-bit unsigned integer */ + ODP_ML_DATA_TYPE_UINT24, + + /** 32-bit integer */ + ODP_ML_DATA_TYPE_INT32, + + /** 32-bit unsigned integer */ + ODP_ML_DATA_TYPE_UINT32, + + /** 64-bit integer */ + ODP_ML_DATA_TYPE_INT64, + + /** 64-bit unsigned integer */ + ODP_ML_DATA_TYPE_UINT64, + + /** 16-bit floating point number */ + ODP_ML_DATA_TYPE_FP16, + + /** 16-bit brain floating point (bfloat16) number */ + ODP_ML_DATA_TYPE_BFP16, + + /** 32-bit floating point number */ + ODP_ML_DATA_TYPE_FP32, + + /** 64-bit floating point number */ + ODP_ML_DATA_TYPE_FP64, + +} odp_ml_data_type_t; + +/** Model input / output data shape type */ +typedef enum { + /** Type of shape is not defined */ + ODP_ML_SHAPE_NONE = 0, + + /** Static shape of data + * + * Shape is static when all dimensions have fixed sizes. + */ + ODP_ML_SHAPE_STATIC, + + /** Dynamic batch size + * + * Shape that has only one dynamic dimension, and the dimension is used as batch size of + * input / output data. The same batch size is applied for all inputs and outputs of + * the model. + */ + ODP_ML_SHAPE_BATCH, + +} odp_ml_shape_type_t; + +/** Model input / output data shape information */ +typedef struct odp_ml_shape_info_t { + /** Shape type */ + odp_ml_shape_type_t type; + + /** Number of dimensions + * + * Number of input / output data dimensions. When zero, the model does not have + * dimension information available. ODP API supports in maximum #ODP_ML_MAX_DIMS + * dimensions. + */ + uint32_t num_dim; + + /** Dimension sizes + * + * Number of data values in each ('num_dim') dimension. Type of the data is defined by + * odp_ml_data_type_t enumeration. Depending on the shape type, some dimensions may have + * dynamic size which is denoted with #ODP_ML_DIM_DYNAMIC value. When shape type is + * #ODP_ML_SHAPE_BATCH, the shape has one dynamic dimension which is used as the batch + * size. + * + * For example, a static (#ODP_ML_SHAPE_STATIC) NCHW tensor could be presented as: + * + * num_dim = 4; + * dim[0] = 1; // no batching, N = 1 + * dim[1] = 3; // 3 color channels + * dim[2] = 720; // height 720 pixels + * dim[3] = 1280; // width 1280 pixels + * + * ... and with dynamic batch size (#ODP_ML_SHAPE_BATCH): + * + * num_dim = 4; + * dim[0] = ODP_ML_DIM_DYNAMIC; // dynamic in range: dim_min[0] ... dim_max[0] + * dim[1] = 3; + * dim[2] = 720; + * dim[3] = 1280; + */ + uint32_t dim[ODP_ML_MAX_DIMS]; + + /** Minimum dimension sizes + * + * Defines the minimum value for each dynamic size (#ODP_ML_DIM_DYNAMIC) in dim[] array. + * Zero is used when the minimum value is unknown. When dimension size is static, the + * value is equal to dim[] array value. + */ + uint32_t dim_min[ODP_ML_MAX_DIMS]; + + /** Maximum dimension sizes + * + * Defines the maximum value for each dynamic size (#ODP_ML_DIM_DYNAMIC) in dim[] array. + * Zero is used when the maximum value is unknown. When dimension size is static, the + * value is equal to dim[] array value. + */ + uint32_t dim_max[ODP_ML_MAX_DIMS]; + + /** Dimension name + * + * Name of each ('num_dim') dimension as a null terminated string. Null string is used if + * a dimension does not have a name. Maximum string length is #ODP_ML_SHAPE_NAME_LEN + * including the null character. + * + * For example, an NCHW tensor could have dimensions named as: + * dim_name = {"N", "C", "H", "W"} + */ + char dim_name[ODP_ML_MAX_DIMS][ODP_ML_SHAPE_NAME_LEN]; + +} odp_ml_shape_info_t; + +/** Model input information */ +typedef struct odp_ml_input_info_t { + /** Model input name */ + char name[ODP_ML_MODEL_IO_NAME_LEN]; + + /** Model input data type */ + odp_ml_data_type_t data_type; + + /** Size of model input data type in bytes */ + uint32_t data_type_size; + + /** Model input data shape */ + odp_ml_shape_info_t shape; + +} odp_ml_input_info_t; + +/** Model output information */ +typedef struct odp_ml_output_info_t { + /** Model output name */ + char name[ODP_ML_MODEL_IO_NAME_LEN]; + + /** Model output data type */ + odp_ml_data_type_t data_type; + + /** Size of model output data type in bytes */ + uint32_t data_type_size; + + /** Model output data shape */ + odp_ml_shape_info_t shape; + +} odp_ml_output_info_t; + +/** Model information */ +typedef struct odp_ml_model_info_t { + /** Model name */ + char name[ODP_ML_MODEL_NAME_LEN]; + + /** + * Model version number + * + * Version number of the model binary. The number changes when the model is modified + * in any way. + */ + uint64_t model_version; + + /** + * Model interface version number + * + * The model interface version number changes only when model input or output data + * format is modified. Data formats are the same for two model versions that have + * the same interface version number. + */ + uint64_t interface_version; + + /** Model index assigned by the implementation */ + uint32_t index; + + /** Number of model inputs */ + uint32_t num_inputs; + + /** Number of model outputs */ + uint32_t num_outputs; + +} odp_ml_model_info_t; + +/** + * Model input / output data format + */ +typedef struct odp_ml_data_format_t { + /** Model input / output data type */ + odp_ml_data_type_t data_type; + + /** Size of data type in bytes */ + uint32_t data_type_size; + + /** Model input / output data shape */ + odp_ml_shape_info_t shape; + +} odp_ml_data_format_t; + +/** + * Machine learning model parameters + * + * Use odp_ml_model_param_init() to initialize the structure to its default values. + */ +typedef struct odp_ml_model_param_t { + /** + * Model binary + * + * Points to model binary stored into a memory buffer. Model format is + * implementation specific. */ + void *model; + + /** Size of the model binary in bytes */ + uint64_t size; + + /** + * Maximum completion identifier value + * + * When application uses asynchronous poll mode (#ODP_ML_COMPL_MODE_POLL) operations with + * the model, it will choose completion identifier values between 0 and this value. Valid + * values range from 0 to max_compl_id capability. The default value is zero. + */ + uint32_t max_compl_id; + + /** + * Enable / disable extra statistics counters + * + * Extra statistics may be read with odp_ml_model_extra_stats() when enabled. Statistics + * are disabled by default. + */ + odp_bool_t extra_stat_enable; + + /** + * Extra model information + * + * When model metadata misses some details of model input / output data format, user can + * pass those with this structure. When 'num_inputs' / 'num_outputs' is non-zero, data + * format of all model inputs / outputs are overridden by the provided values. Values are + * ignored when 'num_inputs' / 'num_outputs' is zero. + */ + struct { + /** + * Number of model inputs + * + * Number of model inputs and elements in 'input_format' array. When non-zero, + * the value must match the number of inputs defined in model metadata. The default + * value is 0. + */ + uint32_t num_inputs; + + /** + * Number of model outputs + * + * Number of model outputs and elements in 'output_format' array. When non-zero, + * the value must match the number of outputs defined in model metadata. The default + * value is 0. + */ + uint32_t num_outputs; + + /** + * Model input data format array + * + * Points to an array of data formats. The array has 'num_inputs' elements. Inputs + * are defined in the same order they are listed in model metadata. + * An odp_ml_model_create() call copies these values. The default value is NULL. + */ + const odp_ml_data_format_t *input_format; + + /** + * Model output data format array + * + * Points to an array of data formats. The array has 'num_outputs' elements. Outputs + * are defined in the same order they are listed in model metadata. + * An odp_ml_model_create() call copies these values. The default value is NULL. + */ + const odp_ml_data_format_t *output_format; + + } extra_info; + + /** + * ODP implementation specific extra parameters + * + * See ODP implementation documentation for details about extra parameter usage. For + * example, extra parameters may give hints about HW resource usage with the model to be + * created. An odp_ml_model_create() call copies these parameter values. When NULL, all + * extra parameters are set to their default values. The default value is NULL. + */ + const odp_ml_model_extra_param_t *extra_param; + +} odp_ml_model_param_t; + +/** Results of model run operation */ +typedef struct odp_ml_run_result_t { + /** Model run error code + * + * Zero when model run completed successfully. Otherwise, error code contains + * an implementation specific value. + */ + uint64_t error_code; + + /** User context pointer value from odp_ml_compl_param_t */ + void *user_ptr; + +} odp_ml_run_result_t; + +/** Result of model load / unload operation */ +typedef struct odp_ml_load_result_t { + /** Model load / unload error code + * + * Zero when model load / unload completed successfully. Otherwise, error code contains + * an implementation specific value. + */ + uint64_t error_code; + + /** User context pointer value from odp_ml_compl_param_t */ + void *user_ptr; + +} odp_ml_load_result_t; + +/** + * ML completion parameters + * + * Use odp_ml_compl_param_init() to initialize the structure to its default values. + */ +typedef struct odp_ml_compl_param_t { + /** + * Completion mode + * + * The selected completion mode defines which other parameters are used. When + * #ODP_ML_COMPL_MODE_EVENT mode is selected, 'event' and 'queue' must have valid values + * but value of 'compl_id' is ignored, or vice versa when #ODP_ML_COMPL_MODE_POLL mode is + * selected. + */ + odp_ml_compl_mode_t mode; + + /** + * Completion event + * + * Event to be enqueued by ML offload to the completion queue when ML operation + * is complete. Event type must be ODP_EVENT_ML_COMPL. ML offload sets the subtype of + * the event to ODP_EVENT_ML_COMPL_LOAD or ODP_EVENT_ML_COMPL_RUN based on the completed + * operation. + */ + odp_event_t event; + + /** + * Completion queue + * + * Destination queue for the completion event. + */ + odp_queue_t queue; + + /** + * Completion identifier + * + * When completion mode is #ODP_ML_COMPL_MODE_POLL, ML operation completion status is + * reported through this completion identifier. The value passed here is used in + * a following status call to check model load, unload, or inference completion + * (see e.g. odp_ml_model_load_status()). + * + * Application selects a value between 0 and max_compl_id defined in model creation + * parameters (see odp_ml_model_param_t). Only single ML operation (per model) may be + * started with the same identifier value at a time. A value may be reused for the next + * ML operation only after the previous operation is complete. + */ + uint32_t compl_id; + + /** + * User defined context pointer + * + * ODP implementation does not refer to the pointer, but just copies it to the result. + * For example, application may use this pointer to link a received completion event + * to the originating model run request and its input / output data. The default value + * is NULL. + */ + void *user_ptr; + +} odp_ml_compl_param_t; + +/** Model input / output data segment */ +typedef struct odp_ml_data_seg_t { + /** Segment start address */ + void *addr; + + /** Segment size in bytes */ + uint64_t size; + +} odp_ml_data_seg_t; + +/** Model input / output data for a model inference run */ +typedef struct odp_ml_data_t { + /** + * Number of input data segments + * + * Number of elements in 'input_seg' array (at least one per input). + */ + uint32_t num_input_seg; + + /** + * Number of output data segments + * + * Number of elements in 'output_seg' array (at least one per output). + */ + uint32_t num_output_seg; + + /** + * Model input data segments + * + * Points to an array of data segment descriptors for model input data. Each segment + * (odp_ml_data_seg_t) specifies data for one input only. Multiple consecutive segments may + * be used to specify data for the same input. Sum of those segment sizes must match data + * size of the input. Inputs are defined in the same order which odp_ml_model_input_info() + * reports those. + * + * Input data segments may overlap in memory. + */ + odp_ml_data_seg_t *input_seg; + + /** + * Model output data segments + * + * Points to an array of data segment descriptors for model output data. Each segment + * (odp_ml_data_seg_t) specifies data buffer space for one output only. Multiple + * consecutive segments may be used to specify buffer space for the same output. + * Sum of those segment sizes must match data size of the output. Outputs are defined + * in the same order which odp_ml_model_output_info() reports those. + * + * An output data segment must not overlap with any other (input or output) segment + * in memory. + */ + odp_ml_data_seg_t *output_seg; + +} odp_ml_data_t; + +/** + * Parameters for model run + * + * Use odp_ml_run_param_init() to initialize the structure to its default values. + */ +typedef struct odp_ml_run_param_t { + /** + * Batch size + * + * Batch size for all model inputs and outputs that have #ODP_ML_SHAPE_BATCH shape type. + * The default value is 0. + */ + uint32_t batch_size; + + /** + * Model run results + * + * Points to a result structure for model run result output. Results are output only + * in synchronous mode (#ODP_ML_COMPL_MODE_SYNC). The pointer value is ignored in + * asynchronous modes. Use NULL when results are not required. The default value is NULL. + */ + odp_ml_run_result_t *result; + +} odp_ml_run_param_t; + +/** + * ML extra statistics counter information + */ +typedef struct odp_ml_extra_stat_info_t { + /** Name of the statistics counter */ + char name[ODP_ML_EXTRA_STAT_NAME_LEN]; + +} odp_ml_extra_stat_info_t; + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h index ca22280ec..7f6c732ee 100644 --- a/include/odp/api/spec/packet.h +++ b/include/odp/api/spec/packet.h @@ -25,7 +25,7 @@ extern "C" { #include <odp/api/std_types.h> #include <odp/api/time_types.h> -/** @defgroup odp_packet ODP PACKET +/** @addtogroup odp_packet * Packet event metadata and operations. * @{ */ diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h index cfb463c39..a83617f7c 100644 --- a/include/odp/api/spec/packet_io.h +++ b/include/odp/api/spec/packet_io.h @@ -25,7 +25,7 @@ extern "C" { #include <odp/api/reassembly.h> #include <odp/api/time_types.h> -/** @defgroup odp_packet_io ODP PACKET IO +/** @addtogroup odp_packet_io * Packet IO interfaces. * * Packet IO is the Ingress and Egress interface to ODP processing. It diff --git a/include/odp/api/spec/packet_io_types.h b/include/odp/api/spec/packet_io_types.h index 6b80611ec..9e56e087a 100644 --- a/include/odp/api/spec/packet_io_types.h +++ b/include/odp/api/spec/packet_io_types.h @@ -24,7 +24,7 @@ extern "C" { #include <odp/api/reassembly.h> #include <odp/api/std_types.h> -/** @addtogroup odp_packet_io +/** @defgroup odp_packet_io ODP PACKET IO * @{ */ diff --git a/include/odp/api/spec/packet_types.h b/include/odp/api/spec/packet_types.h index ee62de4ff..b9d55abde 100644 --- a/include/odp/api/spec/packet_types.h +++ b/include/odp/api/spec/packet_types.h @@ -20,7 +20,7 @@ extern "C" { #include <odp/api/proto_stats_types.h> #include <odp/api/queue_types.h> -/** @addtogroup odp_packet +/** @defgroup odp_packet ODP PACKET * @{ */ diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h index b02c0d294..1b71a5a09 100644 --- a/include/odp/api/spec/pool.h +++ b/include/odp/api/spec/pool.h @@ -20,7 +20,7 @@ extern "C" { #include <odp/api/std_types.h> #include <odp/api/pool_types.h> -/** @defgroup odp_pool ODP POOL +/** @addtogroup odp_pool * Packet and buffer (event) pools. * @{ */ diff --git a/include/odp/api/spec/pool_types.h b/include/odp/api/spec/pool_types.h index 7820349ef..cb3db4737 100644 --- a/include/odp/api/spec/pool_types.h +++ b/include/odp/api/spec/pool_types.h @@ -18,8 +18,9 @@ extern "C" { #include <odp/api/std_types.h> #include <odp/api/dma_types.h> +#include <odp/api/ml_types.h> -/** @addtogroup odp_pool +/** @defgroup odp_pool ODP POOL * @{ */ @@ -417,7 +418,10 @@ typedef enum odp_pool_type_t { ODP_POOL_VECTOR, /** DMA completion event pool */ - ODP_POOL_DMA_COMPL + ODP_POOL_DMA_COMPL, + + /** ML completion event pool */ + ODP_POOL_ML_COMPL } odp_pool_type_t; @@ -891,6 +895,9 @@ typedef struct odp_pool_info_t { /** Copy of pool parameters when pool type is ODP_POOL_DMA_COMPL. */ odp_dma_pool_param_t dma_pool_param; + + /** Copy of pool parameters when pool type is ODP_POOL_ML_COMPL. */ + odp_ml_compl_pool_param_t ml_pool_param; }; /** Additional info for packet pools */ diff --git a/include/odp/api/spec/proto_stats.h b/include/odp/api/spec/proto_stats.h index 1a1f67886..7dd57ac0f 100644 --- a/include/odp/api/spec/proto_stats.h +++ b/include/odp/api/spec/proto_stats.h @@ -18,7 +18,7 @@ extern "C" { #include <odp/api/proto_stats_types.h> -/** @defgroup odp_proto_stats ODP PROTO STATS +/** @addtogroup odp_proto_stats * Flow specific packet statistics. * @{ */ diff --git a/include/odp/api/spec/proto_stats_types.h b/include/odp/api/spec/proto_stats_types.h index f3ca80426..4c08e60ab 100644 --- a/include/odp/api/spec/proto_stats_types.h +++ b/include/odp/api/spec/proto_stats_types.h @@ -19,11 +19,16 @@ extern "C" { #include <odp/api/std_types.h> -/** @addtogroup odp_proto_stats +/** @defgroup odp_proto_stats ODP PROTO STATS * @{ */ /** + * @typedef odp_proto_stats_t + * ODP proto stats handle + */ + +/** * @def ODP_PROTO_STATS_INVALID * Invalid proto stats handle */ diff --git a/include/odp/api/spec/queue.h b/include/odp/api/spec/queue.h index 87f6e0d19..9ce2ac73f 100644 --- a/include/odp/api/spec/queue.h +++ b/include/odp/api/spec/queue.h @@ -21,7 +21,7 @@ extern "C" { #include <odp/api/queue_types.h> #include <odp/api/std_types.h> -/** @defgroup odp_queue ODP QUEUE +/** @addtogroup odp_queue * Queues for event passing and scheduling. * @{ */ diff --git a/include/odp/api/spec/queue_types.h b/include/odp/api/spec/queue_types.h index 5f84a5f49..9edf7271d 100644 --- a/include/odp/api/spec/queue_types.h +++ b/include/odp/api/spec/queue_types.h @@ -18,7 +18,7 @@ extern "C" { #include <odp/api/schedule_types.h> -/** @addtogroup odp_queue +/** @defgroup odp_queue ODP QUEUE * @{ */ diff --git a/include/odp/api/spec/random.h b/include/odp/api/spec/random.h index dd30f9d48..10f1026b3 100644 --- a/include/odp/api/spec/random.h +++ b/include/odp/api/spec/random.h @@ -19,7 +19,7 @@ extern "C" { #include <odp/api/random_types.h> #include <odp/api/std_types.h> -/** @defgroup odp_random ODP RANDOM +/** @addtogroup odp_random * Random number generation. * @{ */ diff --git a/include/odp/api/spec/random_types.h b/include/odp/api/spec/random_types.h index cb7dccc7c..5d5ee9450 100644 --- a/include/odp/api/spec/random_types.h +++ b/include/odp/api/spec/random_types.h @@ -19,7 +19,7 @@ extern "C" { #include <odp/api/std_types.h> -/** @addtogroup odp_random +/** @defgroup odp_random ODP RANDOM * @{ */ diff --git a/include/odp/api/spec/schedule.h b/include/odp/api/spec/schedule.h index 31da38e4d..7226c198b 100644 --- a/include/odp/api/spec/schedule.h +++ b/include/odp/api/spec/schedule.h @@ -22,7 +22,7 @@ extern "C" { #include <odp/api/schedule_types.h> #include <odp/api/thrmask.h> -/** @defgroup odp_scheduler ODP SCHEDULER +/** @addtogroup odp_scheduler * Event scheduler for work load balancing and prioritization. * @{ */ diff --git a/include/odp/api/spec/schedule_types.h b/include/odp/api/spec/schedule_types.h index b15397b96..30cb939dc 100644 --- a/include/odp/api/spec/schedule_types.h +++ b/include/odp/api/spec/schedule_types.h @@ -20,7 +20,7 @@ extern "C" { #endif -/** @addtogroup odp_scheduler +/** @defgroup odp_scheduler ODP SCHEDULER * @{ */ diff --git a/include/odp/api/spec/stash.h b/include/odp/api/spec/stash.h index 756214abe..61ae58eba 100644 --- a/include/odp/api/spec/stash.h +++ b/include/odp/api/spec/stash.h @@ -18,7 +18,7 @@ extern "C" { #include <odp/api/stash_types.h> -/** @defgroup odp_stash ODP STASH +/** @addtogroup odp_stash * Stash for storing object handles * @{ */ diff --git a/include/odp/api/spec/stash_types.h b/include/odp/api/spec/stash_types.h index 96e136d78..48c4b9be8 100644 --- a/include/odp/api/spec/stash_types.h +++ b/include/odp/api/spec/stash_types.h @@ -18,7 +18,7 @@ extern "C" { #include <odp/api/std_types.h> -/** @addtogroup odp_stash +/** @defgroup odp_stash ODP STASH * @{ */ diff --git a/include/odp/api/spec/std.h b/include/odp/api/spec/std.h index fba1ee31d..7be543338 100644 --- a/include/odp/api/spec/std.h +++ b/include/odp/api/spec/std.h @@ -19,12 +19,10 @@ extern "C" { #include <odp/api/std_types.h> -/** - * @defgroup odp_std ODP STD - * Standard types and performance optimized versions of selected C library - * functions. - * - * @{ +/** @addtogroup odp_std + * Standard types and performance optimized versions of selected C library + * functions. + * @{ */ /** diff --git a/include/odp/api/spec/std_types.h b/include/odp/api/spec/std_types.h index e2630e044..5428631b6 100644 --- a/include/odp/api/spec/std_types.h +++ b/include/odp/api/spec/std_types.h @@ -22,7 +22,7 @@ extern "C" { #endif -/** @addtogroup odp_std ODP STD +/** @defgroup odp_std ODP STD * @{ */ @@ -138,6 +138,9 @@ typedef union odp_feature_t { /** IPsec APIs, e.g., odp_ipsec_xxx() */ uint32_t ipsec:1; + /** Machine Learning APIs, e.g., odp_ml_xxx() */ + uint32_t ml:1; + /** Scheduler APIs, e.g., odp_schedule_xxx() */ uint32_t schedule:1; diff --git a/include/odp/api/spec/thread.h b/include/odp/api/spec/thread.h index dbb033da1..34d3c2b82 100644 --- a/include/odp/api/spec/thread.h +++ b/include/odp/api/spec/thread.h @@ -19,7 +19,7 @@ extern "C" { #include <odp/api/thread_types.h> -/** @defgroup odp_thread ODP THREAD +/** @addtogroup odp_thread * Thread types, masks and IDs. * @{ */ diff --git a/include/odp/api/spec/thread_types.h b/include/odp/api/spec/thread_types.h index 204d28cad..13846cd8f 100644 --- a/include/odp/api/spec/thread_types.h +++ b/include/odp/api/spec/thread_types.h @@ -15,7 +15,7 @@ extern "C" { #endif -/** @ingroup odp_thread ODP THREAD +/** @defgroup odp_thread ODP THREAD * @{ */ diff --git a/include/odp/api/spec/time.h b/include/odp/api/spec/time.h index c3571f7fa..f7e20a6f4 100644 --- a/include/odp/api/spec/time.h +++ b/include/odp/api/spec/time.h @@ -20,7 +20,7 @@ extern "C" { #include <odp/api/std_types.h> #include <odp/api/time_types.h> -/** @defgroup odp_time ODP TIME +/** @addtogroup odp_time * SoC global and CPU local wall clock time * * @{ diff --git a/include/odp/api/spec/time_types.h b/include/odp/api/spec/time_types.h index cf0393ef0..bd8f324a3 100644 --- a/include/odp/api/spec/time_types.h +++ b/include/odp/api/spec/time_types.h @@ -17,7 +17,7 @@ extern "C" { #endif -/** @addtogroup odp_time +/** @defgroup odp_time ODP TIME * @{ */ |