diff options
Diffstat (limited to 'include/odp/api/spec/stash.h')
| -rw-r--r-- | include/odp/api/spec/stash.h | 439 |
1 files changed, 439 insertions, 0 deletions
diff --git a/include/odp/api/spec/stash.h b/include/odp/api/spec/stash.h new file mode 100644 index 000000000..d1b2f66c9 --- /dev/null +++ b/include/odp/api/spec/stash.h @@ -0,0 +1,439 @@ +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2020-2023 Nokia + */ + +/** + * @file + * + * ODP stash + */ + +#ifndef ODP_API_SPEC_STASH_H_ +#define ODP_API_SPEC_STASH_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/stash_types.h> + +/** @addtogroup odp_stash + * Stash for storing object handles + * @{ + */ + +/** + * Query stash capabilities + * + * Outputs capabilities of the given stash type on success. The stash type + * is not supported if 'max_stashes' capability is zero. The default stash + * type (ODP_STASH_TYPE_DEFAULT) is always supported. The function returns + * failure if the given stash type is unknown to the implementation. + * + * @param[out] capa Pointer to capability structure for output + * @param type Stash type + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_stash_capability(odp_stash_capability_t *capa, odp_stash_type_t type); + +/** + * Initialize stash params + * + * Initialize an odp_stash_param_t to its default values for all fields. + * + * @param param Parameter structure to be initialized + */ +void odp_stash_param_init(odp_stash_param_t *param); + +/** + * Create a stash + * + * This routine is used to create a stash for object handles. Object handle + * values are opaque data to ODP implementation. Application may use a stash + * to store e.g. pointers, offsets or indexes to arbitrary objects which are + * allocated and freed frequently (e.g. per packet) during application + * processing. Object handle size is specified in stash parameters. + * + * It is optional to give a name. Names do not have to be unique. However, + * odp_stash_lookup() returns only a single matching stash. + * + * @param name Name of the stash or NULL. Maximum string length is + * ODP_STASH_NAME_LEN, including the null character. + * @param param Stash creation parameters + * + * @return Handle of the created stash + * @retval ODP_STASH_INVALID Stash could not be created + */ +odp_stash_t odp_stash_create(const char *name, const odp_stash_param_t *param); + +/** + * Destroy a stash + * + * Destroy a previously created stash. Stash must be empty before it is + * destroyed. Results are undefined if an attempt is made to destroy a stash + * that contains object handles. + * + * @param stash The stash to be destroyed + * + * @retval 0 Success + * @retval <0 Failure + */ +int odp_stash_destroy(odp_stash_t stash); + +/** + * Find a stash by name + * + * @param name Name of the stash + * + * @return Handle of the first matching stash + * @retval ODP_STASH_INVALID Stash could not be found + */ +odp_stash_t odp_stash_lookup(const char *name); + +/** + * Get printable value for a stash handle + * + * @param stash Handle to be converted for debugging + * @return uint64_t value that can be used for debugging (e.g. printed) + */ +uint64_t odp_stash_to_u64(odp_stash_t stash); + +/** + * Put object handles into a stash + * + * Store object handles into the stash. Handle values are opaque data to + * ODP implementation and may be e.g. pointers or indexes to arbitrary objects. + * Application specifies object handle size and maximum number of handles to be + * stored in stash creation parameters. + * + * A successful operation returns the actual number of object handles stored. + * If the return value is less than 'num', the remaining handles at the end of + * 'obj' array are not stored. + * + * In case of ODP_STASH_TYPE_FIFO, object handles are stored into the stash in + * the order they are in the array. + * + * @param stash Stash handle + * @param obj Points to an array of object handles to be stored. + * Object handle size is specified by 'obj_size' in stash + * creation parameters. The array must be 'obj_size' aligned + * in memory. + * @param num Number of object handles to store + * + * @return Number of object handles actually stored (0 ... num) + * @retval <0 on failure + */ +int32_t odp_stash_put(odp_stash_t stash, const void *obj, int32_t num); + +/** + * Put batch of object handles into a stash + * + * Otherwise like odp_stash_put(), except that this function stores either all + * 'num' object handles or none. odp_stash_capability_t.max_put_batch defines + * the maximum supported batch size. + * + * @param stash Stash handle + * @param obj Points to an array of object handles to be stored. + * Object handle size is specified by 'obj_size' in stash + * creation parameters. The array must be 'obj_size' aligned + * in memory. + * @param num Number of object handles to store + * + * @return Number of object handles actually stored (0 or num) + * @retval <0 on failure + */ +int32_t odp_stash_put_batch(odp_stash_t stash, const void *obj, int32_t num); + +/** + * Put 32-bit integers into a stash + * + * Otherwise like odp_stash_put(), except that this function operates on 32-bit + * integers. The stash must have been created with 'obj_size' of 4. + * + * @param stash Stash handle + * @param val Points to an array of 32-bit integers to be stored. The array + * must be 32-bit aligned in memory. + * @param num Number of integers to store + * + * @return Number of integers actually stored (0 ... num) + * @retval <0 on failure + */ +int32_t odp_stash_put_u32(odp_stash_t stash, const uint32_t val[], int32_t num); + +/** + * Put batch of 32-bit integers into a stash + * + * Otherwise like odp_stash_put_u32(), except that this function stores either + * all 'num' object handles or none. odp_stash_capability_t.max_put_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param val Points to an array of 32-bit integers to be stored. The array + * must be 32-bit aligned in memory. + * @param num Number of integers to store + * + * @return Number of integers actually stored (0 or num) + * @retval <0 on failure + */ +int32_t odp_stash_put_u32_batch(odp_stash_t stash, const uint32_t val[], int32_t num); + +/** + * Put 64-bit integers into a stash + * + * Otherwise like odp_stash_put(), except that this function operates on 64-bit + * integers. The stash must have been created with 'obj_size' of 8. + * + * @param stash Stash handle + * @param val Points to an array of 64-bit integers to be stored. The array + * must be 64-bit aligned in memory. + * @param num Number of integers to store + * + * @return Number of integers actually stored (0 ... num) + * @retval <0 on failure + */ +int32_t odp_stash_put_u64(odp_stash_t stash, const uint64_t val[], int32_t num); + +/** + * Put batch of 64-bit integers into a stash + * + * Otherwise like odp_stash_put_u64(), except that this function stores either + * all 'num' object handles or none. odp_stash_capability_t.max_put_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param val Points to an array of 64-bit integers to be stored. The array + * must be 64-bit aligned in memory. + * @param num Number of integers to store + * + * @return Number of integers actually stored (0 or num) + * @retval <0 on failure + */ +int32_t odp_stash_put_u64_batch(odp_stash_t stash, const uint64_t val[], int32_t num); + +/** + * Put pointers into a stash + * + * Otherwise like odp_stash_put(), except that this function operates on + * pointers. The stash must have been created with 'obj_size' matching to the + * size of uintptr_t. + * + * @param stash Stash handle + * @param ptr Points to an array of pointers to be stored. The array must be + * pointer size aligned in memory. + * @param num Number of pointers to store + * + * @return Number of pointers actually stored (0 ... num) + * @retval <0 on failure + */ +int32_t odp_stash_put_ptr(odp_stash_t stash, const uintptr_t ptr[], int32_t num); + +/** + * Put batch of pointers into a stash + * + * Otherwise like odp_stash_put_ptr(), except that this function stores either + * all 'num' object handles or none. odp_stash_capability_t.max_put_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param ptr Points to an array of pointers to be stored. The array must be + * pointer size aligned in memory. + * @param num Number of pointers to store + * + * @return Number of pointers actually stored (0 or num) + * @retval <0 on failure + */ +int32_t odp_stash_put_ptr_batch(odp_stash_t stash, const uintptr_t ptr[], int32_t num); + +/** + * Get object handles from a stash + * + * Get previously stored object handles from the stash. Application specifies + * object handle size in stash creation parameters. + * + * @param stash Stash handle + * @param[out] obj Points to an array of object handles for output. + * Object handle size is specified by 'obj_size' in stash + * creation parameters. The array must be 'obj_size' aligned + * in memory. + * @param num Maximum number of object handles to get from the stash + * + * @return Number of object handles actually output (0 ... num) to 'obj' array + * @retval <0 on failure + */ +int32_t odp_stash_get(odp_stash_t stash, void *obj, int32_t num); + +/** + * Get batch of object handles from a stash + * + * Otherwise like odp_stash_get(), except that this function outputs either + * all 'num' object handles or none. odp_stash_capability_t.max_get_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param[out] obj Points to an array of object handles for output. + * Object handle size is specified by 'obj_size' in stash + * creation parameters. The array must be 'obj_size' aligned + * in memory. + * @param num Number of object handles to get from the stash + * + * @return Number of object handles actually output (0 or num) to 'obj' array + * @retval <0 on failure + */ +int32_t odp_stash_get_batch(odp_stash_t stash, void *obj, int32_t num); + +/** + * Get 32-bit integers from a stash + * + * Otherwise like odp_stash_get(), except that this function operates on 32-bit + * integers. The stash must have been created with 'obj_size' of 4. + * + * @param stash Stash handle + * @param[out] val Points to an array of 32-bit integers for output. The + * array must be 32-bit aligned in memory. + * @param num Maximum number of integers to get from the stash + * + * @return Number of integers actually output (0 ... num) to 'val' array + * @retval <0 on failure + */ +int32_t odp_stash_get_u32(odp_stash_t stash, uint32_t val[], int32_t num); + +/** + * Get batch of 32-bit integers from a stash + * + * Otherwise like odp_stash_get_u32(), except that this function outputs either + * all 'num' object handles or none. odp_stash_capability_t.max_get_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param[out] val Points to an array of 32-bit integers for output. The + * array must be 32-bit aligned in memory. + * @param num Number of integers to get from the stash + * + * @return Number of integers actually output (0 or num) to 'val' array + * @retval <0 on failure + */ +int32_t odp_stash_get_u32_batch(odp_stash_t stash, uint32_t val[], int32_t num); + +/** + * Get 64-bit integers from a stash + * + * Otherwise like odp_stash_get(), except that this function operates on 64-bit + * integers. The stash must have been created with 'obj_size' of 8. + * + * @param stash Stash handle + * @param[out] val Points to an array of 64-bit integers for output. The + * array must be 64-bit aligned in memory. + * @param num Maximum number of integers to get from the stash + * + * @return Number of integers actually output (0 ... num) to 'val' array + * @retval <0 on failure + */ +int32_t odp_stash_get_u64(odp_stash_t stash, uint64_t val[], int32_t num); + +/** + * Get batch of 64-bit integers from a stash + * + * Otherwise like odp_stash_get_u64(), except that this function outputs either + * all 'num' object handles or none. odp_stash_capability_t.max_get_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param[out] val Points to an array of 64-bit integers for output. The + * array must be 64-bit aligned in memory. + * @param num Number of integers to get from the stash + * + * @return Number of integers actually output (0 or num) to 'val' array + * @retval <0 on failure + */ +int32_t odp_stash_get_u64_batch(odp_stash_t stash, uint64_t val[], int32_t num); + +/** + * Get pointers from a stash + * + * Otherwise like odp_stash_get(), except that this function operates on + * pointers. The stash must have been created with 'obj_size' matching to the + * size of uintptr_t. + * + * @param stash Stash handle + * @param[out] ptr Points to an array of pointers for output. The array must + * be pointer size aligned in memory. + * @param num Maximum number of pointers to get from the stash + * + * @return Number of pointers actually output (0 ... num) to 'ptr' array + * @retval <0 on failure + */ +int32_t odp_stash_get_ptr(odp_stash_t stash, uintptr_t ptr[], int32_t num); + +/** + * Get batch of pointers from a stash + * + * Otherwise like odp_stash_get_ptr(), except that this function outputs either + * all 'num' object handles or none. odp_stash_capability_t.max_get_batch + * defines the maximum supported batch size. + * + * @param stash Stash handle + * @param[out] ptr Points to an array of pointers for output. The array must + * be pointer size aligned in memory. + * @param num Number of pointers to get from the stash + * + * @return Number of pointers actually output (0 or num) to 'ptr' array + * @retval <0 on failure + */ +int32_t odp_stash_get_ptr_batch(odp_stash_t stash, uintptr_t ptr[], int32_t num); + +/** + * Flush object handles from the thread local cache + * + * Flushes all object handles from the thread local cache into the stash, so + * that those are available to odp_stash_get() calls from other threads. This + * call may be used to ensure that thread local cache is empty e.g. before + * the calling thread stops using the stash. + * + * Flush and put operations share 'put_mode' setting in stash creation + * parameters. So, application must ensure that flush and put operations are not + * used concurrently, when ODP_STASH_OP_ST is selected. + * + * @param stash Stash handle + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_stash_flush_cache(odp_stash_t stash); + +/** + * Print debug information about the stash + * + * Print implementation defined information about the stash to the ODP log. The information + * is intended to be used for debugging. + * + * @param stash Stash handle + */ +void odp_stash_print(odp_stash_t stash); + +/** + * Read statistics counters of a stash + * + * Read the statistics counters enabled using odp_stash_stats_opt_t during stash creation. + * Inactive counters are set to zero by the implementation. + * + * @param stash Stash handle + * @param[out] stats Points to statistics counters structure for output + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_stash_stats(odp_stash_t stash, odp_stash_stats_t *stats); + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif |