diff options
Diffstat (limited to 'include/odp/api')
26 files changed, 727 insertions, 263 deletions
diff --git a/include/odp/api/abi-default/packet_types.h b/include/odp/api/abi-default/packet_types.h index 84f210b0e..73cfdcafa 100644 --- a/include/odp/api/abi-default/packet_types.h +++ b/include/odp/api/abi-default/packet_types.h @@ -70,55 +70,55 @@ typedef struct odp_packet_parse_result_flag_t { /** Flags as a bitfield struct */ struct { - /** @see odp_packet_has_error() */ + /** See odp_packet_has_error() */ uint64_t has_error : 1; - /** @see odp_packet_has_l2_error() */ + /** See odp_packet_has_l2_error() */ uint64_t has_l2_error : 1; - /** @see odp_packet_has_l3_error() */ + /** See odp_packet_has_l3_error() */ uint64_t has_l3_error : 1; - /** @see odp_packet_has_l4_error() */ + /** See odp_packet_has_l4_error() */ uint64_t has_l4_error : 1; - /** @see odp_packet_has_l2() */ + /** See odp_packet_has_l2() */ uint64_t has_l2 : 1; - /** @see odp_packet_has_l3() */ + /** See odp_packet_has_l3() */ uint64_t has_l3 : 1; - /** @see odp_packet_has_l4() */ + /** See odp_packet_has_l4() */ uint64_t has_l4 : 1; - /** @see odp_packet_has_eth() */ + /** See odp_packet_has_eth() */ uint64_t has_eth : 1; - /** @see odp_packet_has_eth_bcast() */ + /** See odp_packet_has_eth_bcast() */ uint64_t has_eth_bcast : 1; - /** @see odp_packet_has_eth_mcast() */ + /** See odp_packet_has_eth_mcast() */ uint64_t has_eth_mcast : 1; - /** @see odp_packet_has_jumbo() */ + /** See odp_packet_has_jumbo() */ uint64_t has_jumbo : 1; - /** @see odp_packet_has_vlan() */ + /** See odp_packet_has_vlan() */ uint64_t has_vlan : 1; - /** @see odp_packet_has_vlan_qinq() */ + /** See odp_packet_has_vlan_qinq() */ uint64_t has_vlan_qinq : 1; - /** @see odp_packet_has_arp() */ + /** See odp_packet_has_arp() */ uint64_t has_arp : 1; - /** @see odp_packet_has_ipv4() */ + /** See odp_packet_has_ipv4() */ uint64_t has_ipv4 : 1; - /** @see odp_packet_has_ipv6() */ + /** See odp_packet_has_ipv6() */ uint64_t has_ipv6 : 1; - /** @see odp_packet_has_ip_bcast() */ + /** See odp_packet_has_ip_bcast() */ uint64_t has_ip_bcast : 1; - /** @see odp_packet_has_ip_mcast() */ + /** See odp_packet_has_ip_mcast() */ uint64_t has_ip_mcast : 1; - /** @see odp_packet_has_ipfrag() */ + /** See odp_packet_has_ipfrag() */ uint64_t has_ipfrag : 1; - /** @see odp_packet_has_ipopt() */ + /** See odp_packet_has_ipopt() */ uint64_t has_ipopt : 1; - /** @see odp_packet_has_ipsec() */ + /** See odp_packet_has_ipsec() */ uint64_t has_ipsec : 1; - /** @see odp_packet_has_udp() */ + /** See odp_packet_has_udp() */ uint64_t has_udp : 1; - /** @see odp_packet_has_tcp() */ + /** See odp_packet_has_tcp() */ uint64_t has_tcp : 1; - /** @see odp_packet_has_sctp() */ + /** See odp_packet_has_sctp() */ uint64_t has_sctp : 1; - /** @see odp_packet_has_icmp() */ + /** See odp_packet_has_icmp() */ uint64_t has_icmp : 1; }; }; diff --git a/include/odp/api/abi-default/time.h b/include/odp/api/abi-default/time.h index 94587371d..e601e6fd2 100644 --- a/include/odp/api/abi-default/time.h +++ b/include/odp/api/abi-default/time.h @@ -1,15 +1,9 @@ -/* Copyright (c) 2015-2018, Linaro Limited +/* Copyright (c) 2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause */ -/** - * @file - * - * ODP time service - */ - #ifndef ODP_ABI_TIME_H_ #define ODP_ABI_TIME_H_ @@ -17,34 +11,7 @@ extern "C" { #endif -/** @addtogroup odp_time - * @{ - **/ - -/** - * @internal Time structure used for both POSIX timespec and HW counter - * implementations. - */ -typedef struct odp_time_t { - /** @internal Variant mappings for time type */ - union { - /** @internal Used with generic 64 bit operations */ - uint64_t u64; - - /** @internal Nanoseconds */ - uint64_t nsec; - - /** @internal HW timer counter value */ - uint64_t count; - - }; -} odp_time_t; - -#define ODP_TIME_NULL ((odp_time_t){.u64 = 0}) - -/** - * @} - */ +/* Empty header required due to the inline functions */ #ifdef __cplusplus } diff --git a/include/odp/api/abi-default/time_types.h b/include/odp/api/abi-default/time_types.h new file mode 100644 index 000000000..4b7ec47eb --- /dev/null +++ b/include/odp/api/abi-default/time_types.h @@ -0,0 +1,49 @@ +/* Copyright (c) 2015-2018, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#ifndef ODP_ABI_TIME_TYPES_H_ +#define ODP_ABI_TIME_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <stdint.h> + +/** @ingroup odp_time + * @{ + **/ + +/** + * @internal Time structure used for both POSIX timespec and HW counter + * implementations. + */ +typedef struct odp_time_t { + /** @internal Variant mappings for time type */ + union { + /** @internal Used with generic 64 bit operations */ + uint64_t u64; + + /** @internal Nanoseconds */ + uint64_t nsec; + + /** @internal HW timer counter value */ + uint64_t count; + + }; +} odp_time_t; + +#define ODP_TIME_NULL ((odp_time_t){.u64 = 0}) + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/odp/api/spec/classification.h b/include/odp/api/spec/classification.h index 592ad1050..aefe2845a 100644 --- a/include/odp/api/spec/classification.h +++ b/include/odp/api/spec/classification.h @@ -274,7 +274,7 @@ typedef union odp_cls_pmr_terms_t { * Packet Matching Rule parameter structure * * Match value/mask size and endianness are defined in PMR term documentation - * (@see odp_cls_pmr_term_t). Most values and masks are passed in big + * (see odp_cls_pmr_term_t). Most values and masks are passed in big * endian format without data alignment requirement. ODP_PMR_LEN is * an exception to this (uint32_t in CPU endian). */ @@ -474,16 +474,16 @@ typedef struct odp_cls_stats_capability_t { union { /** Statistics counters in a bit field structure */ struct { - /** @see odp_cls_cos_stats_t::octets */ + /** See odp_cls_cos_stats_t::octets */ uint64_t octets : 1; - /** @see odp_cls_cos_stats_t::packets */ + /** See odp_cls_cos_stats_t::packets */ uint64_t packets : 1; - /** @see odp_cls_cos_stats_t::discards */ + /** See odp_cls_cos_stats_t::discards */ uint64_t discards : 1; - /** @see odp_cls_cos_stats_t::errors */ + /** See odp_cls_cos_stats_t::errors */ uint64_t errors : 1; } counter; @@ -502,16 +502,16 @@ typedef struct odp_cls_stats_capability_t { union { /** Statistics counters in a bit field structure */ struct { - /** @see odp_cls_queue_stats_t::octets */ + /** See odp_cls_queue_stats_t::octets */ uint64_t octets : 1; - /** @see odp_cls_queue_stats_t::packets */ + /** See odp_cls_queue_stats_t::packets */ uint64_t packets : 1; - /** @see odp_cls_queue_stats_t::discards */ + /** See odp_cls_queue_stats_t::discards */ uint64_t discards : 1; - /** @see odp_cls_queue_stats_t::errors */ + /** See odp_cls_queue_stats_t::errors */ uint64_t errors : 1; } counter; @@ -635,8 +635,9 @@ typedef struct odp_cls_cos_param { odp_cos_action_t action; /** Enable statistics. If true, counters are incremented when packets - * are classified to the CoS. Default is false. @see - * odp_cls_cos_stats(). + * are classified to the CoS. Default is false. + * + * @see odp_cls_cos_stats() */ odp_bool_t stats_enable; @@ -675,7 +676,7 @@ typedef struct odp_cls_cos_param { /** Pool associated with CoS * * May be set to ODP_POOL_INVALID, in which case the default pool of - * the originating packet input is used (@see odp_pktio_open()). If + * the originating packet input is used (see odp_pktio_open()). If * there is no originating packet input (e.g. with lookaside IPsec), * then this parameter must be set to a valid pool. * @@ -761,7 +762,7 @@ odp_queue_t odp_cls_hash_result(odp_cos_t cos, odp_packet_t packet); * * Before destroying a CoS, all the PMRs referring to the CoS (as a source or * destination CoS) must be destroyed first. Also, the CoS must not be in use - * as the default CoS in any pktio (@see odp_pktio_default_cos_set()) or as the + * as the default CoS in any pktio (see odp_pktio_default_cos_set()) or as the * destination CoS of any IPsec SA. * * @param cos CoS handle diff --git a/include/odp/api/spec/comp.h b/include/odp/api/spec/comp.h index 39ecbfde4..a1f6f48fb 100644 --- a/include/odp/api/spec/comp.h +++ b/include/odp/api/spec/comp.h @@ -219,7 +219,7 @@ typedef struct odp_comp_alg_capability_t { * that the percentage of output data produced might be greater * than this value. * - * @see odp__percent_t + * @see odp_percent_t */ odp_percent_t compression_ratio; } odp_comp_alg_capability_t; @@ -257,7 +257,7 @@ typedef struct odp_comp_deflate_param { * * max_level - High quality compression * - * @see 'max_level' in odp_comp_alg_capability_t + * @see odp_comp_alg_capability_t::max_level */ uint32_t comp_level; diff --git a/include/odp/api/spec/dma.h b/include/odp/api/spec/dma.h index 6e911b227..658b31058 100644 --- a/include/odp/api/spec/dma.h +++ b/include/odp/api/spec/dma.h @@ -1,4 +1,4 @@ -/* Copyright (c) 2021-2022, Nokia +/* Copyright (c) 2021-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -49,6 +49,10 @@ void odp_dma_param_init(odp_dma_param_t *param); /** * Create DMA session * + * Create a DMA session according to the parameters. The use of session name is optional. Unique + * names are not required. However, odp_dma_lookup() returns only a single matching named session. + * Use odp_dma_param_init() to initialize parameters into their default values. + * * @param name DMA session name or NULL. Maximum string length is ODP_DMA_NAME_LEN. * @param param DMA session parameters * @@ -285,6 +289,19 @@ odp_event_t odp_dma_compl_to_event(odp_dma_compl_t dma_compl); uint64_t odp_dma_compl_to_u64(odp_dma_compl_t dma_compl); /** + * DMA completion event user area + * + * Returns pointer to the user area associated with the completion event. Size of the area is fixed + * and defined in completion event pool parameters. + * + * @param dma_compl DMA completion event handle + * + * @return Pointer to the user area of the completion event + * @retval NULL The completion event does not have user area + */ +void *odp_dma_compl_user_area(odp_dma_compl_t dma_compl); + +/** * Allocate DMA completion event * * Allocates a DMA completion event from a pool. The pool must have been created with @@ -332,7 +349,7 @@ void odp_dma_pool_param_init(odp_dma_pool_param_t *pool_param); * The use of pool name is optional. Unique names are not required. However, odp_pool_lookup() * returns only a single matching pool. Use odp_dma_pool_param_init() to initialize pool parameters * into their default values. Parameters values must not exceed pool capabilities - * (@see odp_dma_pool_capability_t) + * (odp_dma_pool_capability_t). * * @param name Name of the pool or NULL. Maximum string length is ODP_POOL_NAME_LEN. * @param pool_param Pool parameters diff --git a/include/odp/api/spec/dma_types.h b/include/odp/api/spec/dma_types.h index caa51700b..26350e998 100644 --- a/include/odp/api/spec/dma_types.h +++ b/include/odp/api/spec/dma_types.h @@ -77,6 +77,9 @@ typedef struct odp_dma_pool_capability_t { /** Maximum number of DMA completion events in a pool */ uint32_t max_num; + /** Maximum user area size in bytes */ + uint32_t max_uarea_size; + /** Minimum size of thread local cache */ uint32_t min_cache_size; @@ -94,6 +97,13 @@ typedef struct odp_dma_pool_param_t { * Maximum value is defined by 'max_num' pool capability */ uint32_t num; + /** User area size in bytes + * + * Maximum value is defined by 'max_uarea_size' pool capability. Specify as 0 if no user + * area is needed. The default value is 0. + */ + uint32_t uarea_size; + /** Maximum number of events cached locally per thread * * See odp_pool_param_t::cache_size documentation for details. Valid values range from @@ -511,9 +521,8 @@ typedef struct odp_dma_compl_param_t { /** User context pointer * - * User defined context pointer which is copied to transfer results - * (@see odp_dma_result_t). The value does not need to represent a valid address - * (any intptr_t value is allowed). + * User defined context pointer which is copied to transfer results (odp_dma_result_t). The + * value does not need to represent a valid address (any intptr_t value is allowed). * * The default value is NULL. */ @@ -533,7 +542,7 @@ typedef struct odp_dma_result_t { /** User context pointer * * User defined context pointer value from transfer completion parameters - * (@see odp_dma_compl_param_t). The default value is NULL. + * (odp_dma_compl_param_t). The default value is NULL. */ void *user_ptr; diff --git a/include/odp/api/spec/event.h b/include/odp/api/spec/event.h index c36d9cef1..9dc614329 100644 --- a/include/odp/api/spec/event.h +++ b/include/odp/api/spec/event.h @@ -1,5 +1,5 @@ /* Copyright (c) 2015-2018, Linaro Limited - * Copyright (c) 2022, Nokia + * Copyright (c) 2022-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -80,6 +80,20 @@ int odp_event_type_multi(const odp_event_t event[], int num, odp_event_type_t *type); /** + * Event user area + * + * Returns pointer to the user area associated with the event. This maps to the + * user area of underlying event type (e.g. odp_packet_user_area() for packets). + * If the event does not have user area, NULL is returned. + * + * @param event Event handle + * + * @return Pointer to the user area of the event + * @retval NULL The event does not have user area + */ +void *odp_event_user_area(odp_event_t event); + +/** * Filter and convert packet events * * Checks event type of all input events, converts all packet events and outputs diff --git a/include/odp/api/spec/init.h b/include/odp/api/spec/init.h index 69ca55767..c4f64d4fd 100644 --- a/include/odp/api/spec/init.h +++ b/include/odp/api/spec/init.h @@ -1,5 +1,5 @@ /* Copyright (c) 2013-2018, Linaro Limited - * Copyright (c) 2019-2021, Nokia + * Copyright (c) 2019-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -33,6 +33,18 @@ extern "C" { */ /** + * Called from signal handler + */ +#define ODP_TERM_FROM_SIGH ((uint64_t)0x1) + +/** + * Last standard flag for abnormal terminate + * + * An implementation may use this for adding its own flags after the standard flags. + */ +#define ODP_TERM_LAST_FLAG ODP_TERM_FROM_SIGH + +/** * ODP log level. */ typedef enum { @@ -91,11 +103,12 @@ int odp_override_log(odp_log_level_t level, const char *fmt, ...); * - By overriding the ODP implementation default abort function * odp_override_abort(). * - * @warning The latter option is less portable and GNU linker dependent - * (utilizes function attribute "weak"). If both are defined, the odp_init_t - * function pointer has priority over the override function. + * The latter option is less portable and GNU linker dependent (utilizes function + * attribute "weak"). If both are defined, the odp_init_t function pointer has + * priority over the override function. * - * @warning this function shall not return + * Note that no ODP calls should be called in the abort function and the function + * should not return. */ void odp_override_abort(void) ODP_NORETURN; @@ -342,6 +355,39 @@ int odp_term_local(void); int odp_term_global(odp_instance_t instance); /** + * Abnormal ODP termination after a non-recoverable error + * + * Application may call this function to terminate an ODP instance after facing + * a non-recoverable error. Depending on the implementation, this function may + * attempt to dump stack and other memory areas, clean up and stop HW + * operations and/or perform other actions helpful in postmortem analysis. + * Depending on the nature of the error resulting in the abnormal termination, + * these actions may partially or completely fail. Flags (ODP_TERM_*) parameter + * can be used to control and data parameter can be used to pass additional + * flag-specific information to the termination process. Implementation + * specific flags with implementation specific data may also exist, see from + * implementation documentation how those should be utilized. + * + * Some coordination across threads is required when abnormally terminating, if + * other threads continue calling ODP functions during or after termination, + * their operation is most likely affected. + * + * When the function returns, the ODP instance has been destroyed either + * completely or partially. Application must not attempt to call any ODP + * functions during its remaining lifetime, but terminate as soon as feasible. + * + * @param instance Instance handle + * @param flags A bit mask of control flags (ODP_TERM_*), set to 0 + * when no flags + * @param data Additional data, set to NULL when no additional data + * + * @retval 0 on all actions successfully performed + * @retval <0 on failure to perform all actions, implementation specific status + * code for debugging + */ +int odp_term_abnormal(odp_instance_t instance, uint64_t flags, void *data); + +/** * Set thread specific log function * * By default, all ODP log writes use the global log function, which may be set diff --git a/include/odp/api/spec/packet.h b/include/odp/api/spec/packet.h index 51c7a8e46..9f41edf1a 100644 --- a/include/odp/api/spec/packet.h +++ b/include/odp/api/spec/packet.h @@ -1,5 +1,5 @@ /* Copyright (c) 2013-2018, Linaro Limited - * Copyright (c) 2021-2022, Nokia + * Copyright (c) 2021-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -25,7 +25,7 @@ extern "C" { #include <odp/api/pool_types.h> #include <odp/api/proto_stats_types.h> #include <odp/api/std_types.h> -#include <odp/api/time.h> +#include <odp/api/time_types.h> /** @defgroup odp_packet ODP PACKET * Packet event metadata and operations. @@ -937,7 +937,7 @@ void *odp_packet_buf_head(odp_packet_buf_t pkt_buf); /** * Packet buffer size in bytes * - * Packet buffer size is calculated from the buffer head pointer (@see odp_packet_buf_head()). + * Packet buffer size is calculated from the buffer head pointer (see odp_packet_buf_head()). * It contains all buffer level headroom, data, and tailroom. For a single segmented packet this is * equivalent to odp_packet_buf_len(). * @@ -994,7 +994,7 @@ void odp_packet_buf_data_set(odp_packet_buf_t pkt_buf, uint32_t data_offset, uin * may be done only for packet buffers that are not part of any packet (i.e. buffers between * odp_packet_disassemble() and odp_packet_reassemble() calls). * - * This call can be used only for packets of an external memory pool (@see odp_pool_ext_create()). + * This call can be used only for packets of an external memory pool (see odp_pool_ext_create()). * * @param pool Pool from which the packet buffer (disassembled packet) originate from * @param head Head pointer @@ -1008,12 +1008,12 @@ odp_packet_buf_t odp_packet_buf_from_head(odp_pool_t pool, void *head); * Disassemble packet into packet buffers * * Breaks up a packet into a list of packet buffers. Outputs a packet buffer handle for each - * segment of the packet (@see odp_packet_num_segs()). After a successful operation the packet + * segment of the packet (see odp_packet_num_segs()). After a successful operation the packet * handle must not be referenced anymore. Packet buffers are reassembled into a new packet (or * several new packets) with a later odp_packet_reassemble() call(s). All packet buffers must be * reassembled into a packet and freed into the originating pool before the pool is destroyed. * - * This call can be used only for packets of an external memory pool (@see odp_pool_ext_create()). + * This call can be used only for packets of an external memory pool (see odp_pool_ext_create()). * * @param pkt Packet to be disassembled * @param[out] pkt_buf Packet buffer handle array for output @@ -1040,7 +1040,7 @@ uint32_t odp_packet_disassemble(odp_packet_t pkt, odp_packet_buf_t pkt_buf[], ui * in the buffers. All other packet metadata are set to their default values. After a successful * operation packet buffer handles must not be referenced anymore. * - * This call can be used only for packets of an external memory pool (@see odp_pool_ext_create()). + * This call can be used only for packets of an external memory pool (see odp_pool_ext_create()). * * @param pool Pool from which all packet buffers (disassembled packets) originate from * @param pkt_buf Packet buffers to form a new packet @@ -2054,19 +2054,21 @@ void odp_packet_aging_tmo_set(odp_packet_t pkt, uint64_t tmo_ns); uint64_t odp_packet_aging_tmo(odp_packet_t pkt); /** - * Request Tx completion event. + * Request packet transmit completion * - * Enables or disables TX completion event request for the packet. When - * enabled, an event of type ODP_EVENT_PACKET_TX_COMPL will be sent to the - * destination queue based on the TX completion mode. The event is sent only - * after pktio interface has finished processing the packet. A previously - * enabled request can be disabled by setting the mode to - * ODP_PACKET_TX_COMPL_DISABLED. + * Enables or disables packet transmit completion request for the packet. Completion may be + * requested either in event (#ODP_PACKET_TX_COMPL_EVENT) or poll (#ODP_PACKET_TX_COMPL_POLL) mode. + * When event mode is enabled, an event of type ODP_EVENT_PACKET_TX_COMPL will be sent to the + * destination queue to signal transmit completion. When poll mode is enabled, + * odp_packet_tx_compl_done() is used with the provided completion identifier to check the + * completion. In both cases, transmit completion is reported only after pktio interface has + * finished processing the packet. * - * TX completion event request is disabled by default. + * A previously enabled request can be disabled by setting the mode to ODP_PACKET_TX_COMPL_DISABLED. + * Transmit completion request is disabled by default. * * @param pkt Packet handle - * @param opt Points to TX completion event generation options + * @param opt Packet transmit completion request options * * @retval 0 On success * @retval <0 On failure @@ -2074,16 +2076,49 @@ uint64_t odp_packet_aging_tmo(odp_packet_t pkt); int odp_packet_tx_compl_request(odp_packet_t pkt, const odp_packet_tx_compl_opt_t *opt); /** - * Check if TX completion event is requested for the packet + * Check if packet transmit completion is requested * * @param pkt Packet handle * - * @retval non-zero TX completion event is requested - * @retval 0 TX completion event is not requested + * @retval non-zero Transmit completion is requested + * @retval 0 Transmit completion is not requested */ int odp_packet_has_tx_compl_request(odp_packet_t pkt); /** + * Set packet free control option + * + * This option enables application to control which packets are freed/not freed back into pool + * after ODP implementation has finished processing those. The option affects only packets that + * are transmitted directly through a packet output interface (also with LSO), i.e. packets + * transmitted through inline IPsec or TM are not affected. + * + * When the option is set to #ODP_PACKET_FREE_CTRL_DONT_FREE, packet output interface will not free + * the packet after transmit and application may reuse the packet as soon as its transmit is + * complete (see e.g. odp_packet_tx_compl_done()). + * + * The option must not be enabled on packets that have multiple references. + * + * Check packet IO interface capability free_ctrl.dont_free (odp_pktio_capability_t::dont_free) for + * the option support. When an interface does not support the option, it ignores the value. + * + * The default value is #ODP_PACKET_FREE_CTRL_DISABLED. + * + * @param pkt Packet handle + * @param ctrl Packet free control option value + */ +void odp_packet_free_ctrl_set(odp_packet_t pkt, odp_packet_free_ctrl_t ctrl); + +/** + * Returns packet free control option value + * + * @param pkt Packet handle + * + * @return The current value of the packet free control option + */ +odp_packet_free_ctrl_t odp_packet_free_ctrl(odp_packet_t pkt); + +/** * Request packet proto stats. * * The statistics enabled in the proto stats object are updated for the packet in @@ -2195,8 +2230,8 @@ void odp_packet_vector_free(odp_packet_vector_t pktv); * the vector table. * * @note The maximum number of packets this vector can hold is defined by - * odp_pool_param_t:vector:max_size. The return value of this function will not - * be greater than odp_pool_param_t:vector:max_size + * odp_pool_param_t::vector::max_size. The return value of this function will not + * be greater than odp_pool_param_t::vector::max_size * * @note The pkt_tbl points to the packet vector table. Application can edit the * packet handles in the table directly (up to odp_pool_param_t::vector::max_size). @@ -2398,6 +2433,29 @@ void odp_packet_tx_compl_free(odp_packet_tx_compl_t tx_compl); */ void *odp_packet_tx_compl_user_ptr(odp_packet_tx_compl_t tx_compl); +/** + * Check packet transmit completion + * + * Checks if a previously sent packet with a ODP_PACKET_TX_COMPL_POLL type transmit completion + * request (see odp_packet_tx_compl_opt_t) has been transmitted. The packet send function call + * clears completion identifier status, and 0 is returned while the transmit is in progress. + * When >0 is returned, transmit of the packet is complete and the completion identifier may be + * reused for another transmit. + * + * When transmit of a packet is complete, it indicates that transmit of other packets sent + * before the packet through the same queue have also completed. + * + * Returns initially 0 for all configured completion identifiers. + * + * @param pktio Packet IO interface that was used to send the packet + * @param compl_id Completion identifier that was used in the transmit completion request + * + * @retval >0 Packet transmit is complete + * @retval 0 Packet transmit is not complete + * @retval <0 Failed to read packet transmit status + */ +int odp_packet_tx_compl_done(odp_pktio_t pktio, uint32_t compl_id); + /* * * Debugging diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h index 602093764..54aa2214b 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/packet_io_types.h> #include <odp/api/queue_types.h> #include <odp/api/reassembly.h> -#include <odp/api/time.h> +#include <odp/api/time_types.h> /** @defgroup odp_packet_io ODP PACKET IO * Packet IO interfaces. @@ -452,9 +452,13 @@ uint64_t odp_pktin_wait_time(uint64_t nsec); * the operation is optimized for single thread operation per queue and the same * queue must not be accessed simultaneously from multiple threads. * - * A successful call returns the actual number of packets sent. If return value - * is less than 'num', the remaining packets at the end of packets[] array - * are not consumed, and the caller has to take care of them. + * A successful call returns the actual number of packets accepted for transmit. If return value + * is less than 'num', the remaining packets at the end of packets[] array are not consumed, + * and the caller has to take care of them. Transmitted packets are freed back into their + * originating pools by default. If interface supports #ODP_PACKET_FREE_CTRL_DONT_FREE + * option and it is set (odp_packet_free_ctrl_set()) in a packet, the packet is not freed + * but application owns it again after its transmit is complete. Application may use + * odp_packet_tx_compl_request() to request an indication when transmit of a packet is complete. * * Entire packet data is sent out (odp_packet_len() bytes of data, starting from * odp_packet_data()). All other packet metadata is ignored unless otherwise @@ -465,7 +469,7 @@ uint64_t odp_pktin_wait_time(uint64_t nsec); * @param packets[] Array of packets to send * @param num Number of packets to send * - * @return Number of packets sent + * @return Number of packets accepted for transmit * @retval <0 on failure */ int odp_pktout_send(odp_pktout_queue_t queue, const odp_packet_t packets[], diff --git a/include/odp/api/spec/packet_io_stats.h b/include/odp/api/spec/packet_io_stats.h index 156a3a95e..bd3908867 100644 --- a/include/odp/api/spec/packet_io_stats.h +++ b/include/odp/api/spec/packet_io_stats.h @@ -101,16 +101,16 @@ typedef struct odp_pktio_stats_t { * level statistics odp_pktio_stats_t for counter definitions. */ typedef struct odp_pktin_queue_stats_t { - /** @see odp_pktio_stats_t::in_octets */ + /** See odp_pktio_stats_t::in_octets */ uint64_t octets; - /** @see odp_pktio_stats_t::in_packets */ + /** See odp_pktio_stats_t::in_packets */ uint64_t packets; - /** @see odp_pktio_stats_t::in_discards */ + /** See odp_pktio_stats_t::in_discards */ uint64_t discards; - /** @see odp_pktio_stats_t::in_errors */ + /** See odp_pktio_stats_t::in_errors */ uint64_t errors; } odp_pktin_queue_stats_t; @@ -122,16 +122,16 @@ typedef struct odp_pktin_queue_stats_t { * level statistics odp_pktio_stats_t for counter definitions. */ typedef struct odp_pktout_queue_stats_t { - /** @see odp_pktio_stats_t::out_octets */ + /** See odp_pktio_stats_t::out_octets */ uint64_t octets; - /** @see odp_pktio_stats_t::out_packets */ + /** See odp_pktio_stats_t::out_packets */ uint64_t packets; - /** @see odp_pktio_stats_t::out_discards */ + /** See odp_pktio_stats_t::out_discards */ uint64_t discards; - /** @see odp_pktio_stats_t::out_errors */ + /** See odp_pktio_stats_t::out_errors */ uint64_t errors; } odp_pktout_queue_stats_t; @@ -146,46 +146,46 @@ typedef struct odp_pktio_stats_capability_t { union { /** Statistics counters in a bit field structure */ struct { - /** @see odp_pktio_stats_t::in_octets */ + /** See odp_pktio_stats_t::in_octets */ uint64_t in_octets : 1; - /** @see odp_pktio_stats_t::in_packets */ + /** See odp_pktio_stats_t::in_packets */ uint64_t in_packets : 1; - /** @see odp_pktio_stats_t::in_ucast_pkts */ + /** See odp_pktio_stats_t::in_ucast_pkts */ uint64_t in_ucast_pkts : 1; - /** @see odp_pktio_stats_t::in_mcast_pkts */ + /** See odp_pktio_stats_t::in_mcast_pkts */ uint64_t in_mcast_pkts : 1; - /** @see odp_pktio_stats_t::in_bcast_pkts */ + /** See odp_pktio_stats_t::in_bcast_pkts */ uint64_t in_bcast_pkts : 1; - /** @see odp_pktio_stats_t::in_discards */ + /** See odp_pktio_stats_t::in_discards */ uint64_t in_discards : 1; - /** @see odp_pktio_stats_t::in_errors */ + /** See odp_pktio_stats_t::in_errors */ uint64_t in_errors : 1; - /** @see odp_pktio_stats_t::out_octets */ + /** See odp_pktio_stats_t::out_octets */ uint64_t out_octets : 1; - /** @see odp_pktio_stats_t::out_packets */ + /** See odp_pktio_stats_t::out_packets */ uint64_t out_packets : 1; - /** @see odp_pktio_stats_t::out_ucast_pkts */ + /** See odp_pktio_stats_t::out_ucast_pkts */ uint64_t out_ucast_pkts : 1; - /** @see odp_pktio_stats_t::out_mcast_pkts */ + /** See odp_pktio_stats_t::out_mcast_pkts */ uint64_t out_mcast_pkts : 1; - /** @see odp_pktio_stats_t::out_bcast_pkts */ + /** See odp_pktio_stats_t::out_bcast_pkts */ uint64_t out_bcast_pkts : 1; - /** @see odp_pktio_stats_t::out_discards */ + /** See odp_pktio_stats_t::out_discards */ uint64_t out_discards : 1; - /** @see odp_pktio_stats_t::out_errors */ + /** See odp_pktio_stats_t::out_errors */ uint64_t out_errors : 1; } counter; @@ -203,16 +203,16 @@ typedef struct odp_pktio_stats_capability_t { union { /** Statistics counters in a bit field structure */ struct { - /** @see odp_pktin_queue_stats_t::octets */ + /** See odp_pktin_queue_stats_t::octets */ uint64_t octets : 1; - /** @see odp_pktin_queue_stats_t::packets */ + /** See odp_pktin_queue_stats_t::packets */ uint64_t packets : 1; - /** @see odp_pktin_queue_stats_t::discards */ + /** See odp_pktin_queue_stats_t::discards */ uint64_t discards : 1; - /** @see odp_pktin_queue_stats_t::errors */ + /** See odp_pktin_queue_stats_t::errors */ uint64_t errors : 1; } counter; @@ -230,16 +230,16 @@ typedef struct odp_pktio_stats_capability_t { union { /** Statistics counters in a bit field structure */ struct { - /** @see odp_pktout_queue_stats_t::octets */ + /** See odp_pktout_queue_stats_t::octets */ uint64_t octets : 1; - /** @see odp_pktout_queue_stats_t::packets */ + /** See odp_pktout_queue_stats_t::packets */ uint64_t packets : 1; - /** @see odp_pktout_queue_stats_t::discards */ + /** See odp_pktout_queue_stats_t::discards */ uint64_t discards : 1; - /** @see odp_pktout_queue_stats_t::errors */ + /** See odp_pktout_queue_stats_t::errors */ uint64_t errors : 1; } counter; diff --git a/include/odp/api/spec/packet_io_types.h b/include/odp/api/spec/packet_io_types.h index a46668c30..fcdf49eb4 100644 --- a/include/odp/api/spec/packet_io_types.h +++ b/include/odp/api/spec/packet_io_types.h @@ -1,5 +1,5 @@ /* Copyright (c) 2013-2018, Linaro Limited - * Copyright (c) 2020-2022, Nokia + * Copyright (c) 2020-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -523,12 +523,11 @@ typedef union odp_pktout_config_opt_t { */ uint64_t aging_ena : 1; - /** Enable packet transmit completion event requests - * - * Use pktio capability tx_compl to check if TX completion events are supported. + /** + * For backwards compatibility, setting this flag is the same as setting + * tx_compl.mode_event in odp_pktio_config_t. The default value is zero. * - * 0: Application will not request packet TX completion events (default) - * 1: Application may request packet TX completion events + * @deprecated Use odp_pktio_config_t::mode_event instead. */ uint64_t tx_compl_ena : 1; @@ -635,8 +634,7 @@ typedef struct odp_pktio_config_t { * * 0: Disable outbound IPSEC inline operation (default) * * 1: Enable outbound IPSEC inline operation * - * @see odp_ipsec_config(), odp_ipsec_sa_create() - * odp_ipsec_out_inline() + * @see odp_ipsec_config(), odp_ipsec_sa_create(), odp_ipsec_out_inline() */ odp_bool_t outbound_ipsec; @@ -699,6 +697,45 @@ typedef struct odp_pktio_config_t { } flow_control; + /** + * Packet transmit completion configuration + */ + struct { + /** + * Enable packet transmit completion events + * + * Use pktio capability tx_compl to check if packet transmit completion mode + * #ODP_PACKET_TX_COMPL_EVENT is supported. + * + * 0: Application will not request ODP_PACKET_TX_COMPL_EVENT mode + * completion (default) + * 1: Application may request ODP_PACKET_TX_COMPL_EVENT mode completion + */ + uint32_t mode_event : 1; + + /** + * Enable packet transmit completion check through polling + * + * Use pktio capability tx_compl to check if packet transmit completion mode + * #ODP_PACKET_TX_COMPL_POLL is supported. + * + * 0: Application will not request ODP_PACKET_TX_COMPL_POLL mode + * completion (default) + * 1: Application may request ODP_PACKET_TX_COMPL_POLL mode completion + */ + uint32_t mode_poll : 1; + + /** + * Maximum completion index + * + * When ODP_PACKET_TX_COMPL_POLL mode is enabled, the maximum completion index + * value that application will use. The value must be between 0 and + * tx_compl.max_compl_id capability. The default value is zero. + */ + uint32_t max_compl_id; + + } tx_compl; + } odp_pktio_config_t; /** @@ -987,11 +1024,34 @@ typedef struct odp_pktio_capability_t { */ odp_bool_t queue_type_plain; - /** ODP_PACKET_TX_COMPL_ALL supported */ - uint32_t mode_all:1; + /** + * For backwards compatibility, mode_all is synonym of mode_event. + * + * @deprecated Use mode_event instead. + */ + uint32_t mode_all : 1; + + /** Packet transmit completion mode ODP_PACKET_TX_COMPL_EVENT support */ + uint32_t mode_event : 1; + + /** Packet transmit completion mode ODP_PACKET_TX_COMPL_POLL support */ + uint32_t mode_poll : 1; + + /** Maximum supported completion ID value */ + uint32_t max_compl_id; } tx_compl; + /** Supported packet free control options */ + struct { + /** + * Packet free control option #ODP_PACKET_FREE_CTRL_DONT_FREE support + * with odp_packet_free_ctrl_set(). + */ + uint32_t dont_free : 1; + + } free_ctrl; + /** Packet input reassembly capability */ odp_reass_capability_t reassembly; diff --git a/include/odp/api/spec/packet_types.h b/include/odp/api/spec/packet_types.h index 1eba3506f..5114582ab 100644 --- a/include/odp/api/spec/packet_types.h +++ b/include/odp/api/spec/packet_types.h @@ -1,5 +1,5 @@ /* Copyright (c) 2013-2018, Linaro Limited - * Copyright (c) 2021, Nokia + * Copyright (c) 2021-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -357,26 +357,26 @@ typedef struct odp_packet_parse_result_t { /** Parse result flags */ odp_packet_parse_result_flag_t flag; - /** @see odp_packet_len() */ + /** See odp_packet_len() */ uint32_t packet_len; - /** @see odp_packet_l2_offset() */ + /** See odp_packet_l2_offset() */ uint32_t l2_offset; - /** @see odp_packet_l3_offset() */ + /** See odp_packet_l3_offset() */ uint32_t l3_offset; - /** @see odp_packet_l4_offset() */ + /** See odp_packet_l4_offset() */ uint32_t l4_offset; - /** @see odp_packet_l3_chksum_status() */ + /** See odp_packet_l3_chksum_status() */ odp_packet_chksum_status_t l3_chksum_status; - /** @see odp_packet_l4_chksum_status() */ + /** See odp_packet_l4_chksum_status() */ odp_packet_chksum_status_t l4_chksum_status; - /** @see odp_packet_l2_type() */ + /** See odp_packet_l2_type() */ odp_proto_l2_type_t l2_type; - /** @see odp_packet_l3_type() */ + /** See odp_packet_l3_type() */ odp_proto_l3_type_t l3_type; - /** @see odp_packet_l4_type() */ + /** See odp_packet_l4_type() */ odp_proto_l4_type_t l4_type; } odp_packet_parse_result_t; @@ -418,34 +418,87 @@ typedef struct odp_packet_lso_opt_t { } odp_packet_lso_opt_t; /** - * Packet Tx completion mode + * Packet transmit completion mode */ typedef enum odp_packet_tx_compl_mode_t { - /** Packet Tx completion event is disabled + /** Disable packet transmit completion */ + ODP_PACKET_TX_COMPL_DISABLED = 0, + + /** + * Enable packet transmit completion event + * + * A packet transmit completion event is sent for both transmitted and dropped packets. + */ + ODP_PACKET_TX_COMPL_EVENT, + + /** + * Enable packet transmit completion check through polling * - * When mode is disabled, all other fields of odp_packet_tx_compl_opt_t are ignored. + * Packet transmit completion status is updated for both transmitted and dropped packets. */ - ODP_PACKET_TX_COMPL_DISABLED, - /** Packet Tx completion event is sent for all packets (both transmitted and dropped) */ - ODP_PACKET_TX_COMPL_ALL, + ODP_PACKET_TX_COMPL_POLL, + } odp_packet_tx_compl_mode_t; /** - * Tx completion request options + * For backwards compatibility, ODP_PACKET_TX_COMPL_ALL is synonym of ODP_PACKET_TX_COMPL_EVENT. + * + * @deprecated Use #ODP_PACKET_TX_COMPL_EVENT instead. + */ +#define ODP_PACKET_TX_COMPL_ALL ODP_PACKET_TX_COMPL_EVENT + +/** + * Packet transmit completion request options */ typedef struct odp_packet_tx_compl_opt_t { - /** Queue handle + /** + * Packet transmit completion mode * - * Tx completion event will be posted to ODP queue identified by this handle. + * When completion mode is #ODP_PACKET_TX_COMPL_DISABLED, all other fields of this struct + * are ignored. */ - odp_queue_t queue; - - /** Packet Tx completion event mode */ odp_packet_tx_compl_mode_t mode; + /** Union of packet transmit completion destinations */ + union { + /** + * Destination queue + * + * When completion mode is #ODP_PACKET_TX_COMPL_EVENT, a packet transmit completion + * event will be sent to this queue. + */ + odp_queue_t queue; + + /** + * Completion identifier + * + * When completion mode is #ODP_PACKET_TX_COMPL_POLL, a packet transmit completion + * status will be reported through this completion identifier. Application selects + * a value between 0 and tx_compl.max_compl_id in packet IO configuration options + * (see odp_pktio_config_t). Only single packet may be transmitted with the same + * identifier value at a time (through the same packet IO interface). A value may + * be reused for the next transmit only after transmit of the previous packet is + * complete. Multiple packets may have the same identifier value set as long as + * those packets are not transmitted simultaneously. + */ + uint32_t compl_id; + }; + } odp_packet_tx_compl_opt_t; /** + * Packet free control option + */ +typedef enum odp_packet_free_ctrl_t { + /** Packet free control disabled */ + ODP_PACKET_FREE_CTRL_DISABLED = 0, + + /** Don't free packet after processing it */ + ODP_PACKET_FREE_CTRL_DONT_FREE, + +} odp_packet_free_ctrl_t; + +/** * Packet proto stats options */ typedef struct odp_packet_proto_stats_opt_t { diff --git a/include/odp/api/spec/pool.h b/include/odp/api/spec/pool.h index a72dcd3af..e51ce0b0d 100644 --- a/include/odp/api/spec/pool.h +++ b/include/odp/api/spec/pool.h @@ -1,5 +1,5 @@ /* Copyright (c) 2015-2018, Linaro Limited - * Copyright (c) 2020-2022, Nokia + * Copyright (c) 2020-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -156,10 +156,11 @@ unsigned int odp_pool_max_index(void); int odp_pool_index(odp_pool_t pool); /** - * Get statistics for pool handle + * Get statistics for pool * - * Read the statistics counters enabled using odp_pool_stats_opt_t during pool - * creation. The inactive counters are set to zero by the implementation. + * Read the statistics counters enabled using odp_pool_stats_opt_t during pool creation. The + * inactive counters are set to zero by the implementation. Depending on the implementation, there + * may be some delay until performed pool operations are visible in the statistics. * * A single call may read statistics from one to ODP_POOL_MAX_THREAD_STATS * threads. Set 'stats.thread.first' and 'stats.thread.last' to select the @@ -176,7 +177,29 @@ int odp_pool_index(odp_pool_t pool); int odp_pool_stats(odp_pool_t pool, odp_pool_stats_t *stats); /** - * Reset statistics for pool handle + * Get selected pool statistics + * + * Read the selected counters given in odp_pool_stats_opt_t bit field structure. Only counters + * included in odp_pool_stats_selected_t can be read and the selected counters must have been + * enabled during pool creation. Values of the unselected counters are undefined. Depending on the + * implementation, there may be some delay until performed pool operations are visible in the + * statistics. + * + * Depending on the implementation, this function may have higher performance compared to + * odp_pool_stats(), as only the selected set of counters is read. + * + * @param pool Pool handle + * @param[out] stats Output buffer for counters + * @param opt Bit field for selecting the counters to be read + * + * @retval 0 on success + * @retval <0 on failure + */ +int odp_pool_stats_selected(odp_pool_t pool, odp_pool_stats_selected_t *stats, + const odp_pool_stats_opt_t *opt); + +/** + * Reset statistics for pool * * Reset all statistics counters to zero except: odp_pool_stats_t::available, * odp_pool_stats_t::cache_available, odp_pool_stats_t::thread::cache_available diff --git a/include/odp/api/spec/pool_types.h b/include/odp/api/spec/pool_types.h index e9b1f9d52..cf1051a07 100644 --- a/include/odp/api/spec/pool_types.h +++ b/include/odp/api/spec/pool_types.h @@ -1,4 +1,4 @@ -/* Copyright (c) 2021-2022, Nokia +/* Copyright (c) 2021-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -56,31 +56,31 @@ extern "C" { typedef union odp_pool_stats_opt_t { /** Option flags */ struct { - /** @see odp_pool_stats_t::available */ + /** See odp_pool_stats_t::available */ uint64_t available : 1; - /** @see odp_pool_stats_t::alloc_ops */ + /** See odp_pool_stats_t::alloc_ops */ uint64_t alloc_ops : 1; - /** @see odp_pool_stats_t::alloc_fails */ + /** See odp_pool_stats_t::alloc_fails */ uint64_t alloc_fails : 1; - /** @see odp_pool_stats_t::free_ops */ + /** See odp_pool_stats_t::free_ops */ uint64_t free_ops : 1; - /** @see odp_pool_stats_t::total_ops */ + /** See odp_pool_stats_t::total_ops */ uint64_t total_ops : 1; - /** @see odp_pool_stats_t::cache_available */ + /** See odp_pool_stats_t::cache_available */ uint64_t cache_available : 1; - /** @see odp_pool_stats_t::cache_alloc_ops */ + /** See odp_pool_stats_t::cache_alloc_ops */ uint64_t cache_alloc_ops : 1; - /** @see odp_pool_stats_t::cache_free_ops */ + /** See odp_pool_stats_t::cache_free_ops */ uint64_t cache_free_ops : 1; - /** @see odp_pool_stats_t::thread::cache_available */ + /** See odp_pool_stats_t::thread::cache_available */ uint64_t thread_cache_available : 1; } bit; @@ -148,6 +148,38 @@ typedef struct odp_pool_stats_t { } odp_pool_stats_t; /** + * Pool statistics counters + * + * Same as odp_pool_stats_t excluding per thread counters. + */ +typedef struct odp_pool_stats_selected_t { + /** See odp_pool_stats_t::available */ + uint64_t available; + + /** See odp_pool_stats_t::alloc_ops */ + uint64_t alloc_ops; + + /** See odp_pool_stats_t::alloc_fails */ + uint64_t alloc_fails; + + /** See odp_pool_stats_t::free_ops */ + uint64_t free_ops; + + /** See odp_pool_stats_t::total_ops */ + uint64_t total_ops; + + /** See odp_pool_stats_t::cache_available */ + uint64_t cache_available; + + /** See odp_pool_stats_t::cache_alloc_ops */ + uint64_t cache_alloc_ops; + + /** See odp_pool_stats_t::cache_free_ops */ + uint64_t cache_free_ops; + +} odp_pool_stats_selected_t; + +/** * Pool capabilities */ typedef struct odp_pool_capability_t { @@ -449,7 +481,7 @@ typedef struct odp_pool_param_t { /** Minimum packet data alignment in bytes. * * Valid values are powers of two. User allocated packets have - * start of data (@see odp_packet_data()) aligned to this or + * start of data (see odp_packet_data()) aligned to this or * a higher alignment (power of two value). This parameter * does not apply to packets that ODP allocates internally * (e.g. packets from packet input). diff --git a/include/odp/api/spec/schedule.h b/include/odp/api/spec/schedule.h index 417e5cb22..9aa898ccc 100644 --- a/include/odp/api/spec/schedule.h +++ b/include/odp/api/spec/schedule.h @@ -225,7 +225,7 @@ void odp_schedule_prefetch(int num); * Maximum scheduling priority level * * This is the maximum value that can be set to 'prio' field in - * odp_schedule_param_t (e.g. @see odp_queue_create()). Queues with a higher + * odp_schedule_param_t (e.g. odp_queue_create()). Queues with a higher * priority value are served with higher priority than queues with a lower * priority value. * @@ -237,7 +237,7 @@ int odp_schedule_max_prio(void); * Minimum scheduling priority level * * This is the minimum value that can be set to 'prio' field in - * odp_schedule_param_t (e.g. @see odp_queue_create()). Queues with a higher + * odp_schedule_param_t (e.g. odp_queue_create()). Queues with a higher * priority value are served with higher priority than queues with a lower * priority value. * @@ -249,7 +249,7 @@ int odp_schedule_min_prio(void); * Default scheduling priority level * * This is the default value of 'prio' field in odp_schedule_param_t - * (e.g. @see odp_queue_param_init()). The default value should be suitable for + * (e.g. odp_queue_param_init()). The default value should be suitable for * an application that uses single priority level for all its queues (uses * scheduler only for load balancing and synchronization). Typically, * the default value is between minimum and maximum values, but with a few @@ -534,6 +534,7 @@ void odp_schedule_order_lock_wait(uint32_t lock_index); * an ordered scheduling context or if an ordered lock is being held. * * This functions does nothing if ordered wait is not supported. + * * @see odp_schedule_capability() */ void odp_schedule_order_wait(void); diff --git a/include/odp/api/spec/shared_memory.h b/include/odp/api/spec/shared_memory.h index eebf288c9..52fbd7ae9 100644 --- a/include/odp/api/spec/shared_memory.h +++ b/include/odp/api/spec/shared_memory.h @@ -295,7 +295,7 @@ int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); * SHM block segmentation information * * Retrieve information about each memory segment of an SHM block. SHM info call outputs the number - * of memory segments (@see odp_shm_info_t.num_seg). A single segment info call may be used + * of memory segments (odp_shm_info_t::num_seg). A single segment info call may be used * to request information for all the segments, or for a subset of those. Use 'index' and 'num' * parameters to specify the segments. Segment indexing starts from zero and continues to * odp_shm_info_t.num_seg - 1. Segment infos are written in virtual memory address order and diff --git a/include/odp/api/spec/stash_types.h b/include/odp/api/spec/stash_types.h index 30fff26c4..3e6e966be 100644 --- a/include/odp/api/spec/stash_types.h +++ b/include/odp/api/spec/stash_types.h @@ -106,10 +106,10 @@ typedef enum odp_stash_op_mode_t { typedef union odp_stash_stats_opt_t { /** Option flags */ struct { - /** @see odp_stash_stats_t::count */ + /** See odp_stash_stats_t::count */ uint64_t count : 1; - /** @see odp_stash_stats_t::cache_count */ + /** See odp_stash_stats_t::cache_count */ uint64_t cache_count : 1; } bit; diff --git a/include/odp/api/spec/time.h b/include/odp/api/spec/time.h index c25338a51..f4496c4c7 100644 --- a/include/odp/api/spec/time.h +++ b/include/odp/api/spec/time.h @@ -1,5 +1,5 @@ /* Copyright (c) 2013-2018, Linaro Limited - * Copyright (c) 2020-2021, Nokia + * Copyright (c) 2020-2023, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause @@ -19,39 +19,14 @@ extern "C" { #endif +#include <odp/api/std_types.h> +#include <odp/api/time_types.h> + /** @defgroup odp_time ODP TIME * Chip and CPU level wall clock time. * @{ */ -/** A microsecond in nanoseconds */ -#define ODP_TIME_USEC_IN_NS 1000ULL - -/** A millisecond in nanoseconds */ -#define ODP_TIME_MSEC_IN_NS 1000000ULL - -/** A second in nanoseconds */ -#define ODP_TIME_SEC_IN_NS 1000000000ULL - -/** A minute in nanoseconds */ -#define ODP_TIME_MIN_IN_NS 60000000000ULL - -/** An hour in nanoseconds */ -#define ODP_TIME_HOUR_IN_NS 3600000000000ULL - -/** - * @typedef odp_time_t - * ODP time stamp. Time stamp can represent a time stamp from local or global - * time source. A local time stamp must not be shared between threads. API calls - * work correctly only when all time stamps for input are from the same time - * source. - */ - -/** - * @def ODP_TIME_NULL - * Zero time stamp - */ - /** * Current local time * diff --git a/include/odp/api/spec/time_types.h b/include/odp/api/spec/time_types.h new file mode 100644 index 000000000..9065b8004 --- /dev/null +++ b/include/odp/api/spec/time_types.h @@ -0,0 +1,63 @@ +/* Copyright (c) 2013-2018, Linaro Limited + * Copyright (c) 2020-2023, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP time + */ + +#ifndef ODP_API_SPEC_TIME_TYPES_H_ +#define ODP_API_SPEC_TIME_TYPES_H_ +#include <odp/visibility_begin.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** @addtogroup odp_time + * @{ + */ + +/** A microsecond in nanoseconds */ +#define ODP_TIME_USEC_IN_NS 1000ULL + +/** A millisecond in nanoseconds */ +#define ODP_TIME_MSEC_IN_NS 1000000ULL + +/** A second in nanoseconds */ +#define ODP_TIME_SEC_IN_NS 1000000000ULL + +/** A minute in nanoseconds */ +#define ODP_TIME_MIN_IN_NS 60000000000ULL + +/** An hour in nanoseconds */ +#define ODP_TIME_HOUR_IN_NS 3600000000000ULL + +/** + * @typedef odp_time_t + * ODP time stamp. Time stamp can represent a time stamp from local or global + * time source. A local time stamp must not be shared between threads. API calls + * work correctly only when all time stamps for input are from the same time + * source. + */ + +/** + * @def ODP_TIME_NULL + * Zero time stamp + */ + +/** + * @} + */ + +#ifdef __cplusplus +} +#endif + +#include <odp/visibility_end.h> +#endif diff --git a/include/odp/api/spec/timer.h b/include/odp/api/spec/timer.h index 7982e391b..bbb439692 100644 --- a/include/odp/api/spec/timer.h +++ b/include/odp/api/spec/timer.h @@ -75,11 +75,14 @@ int odp_timer_res_capability(odp_timer_clk_src_t clk_src, * frequency multiplier and the minimum timeout resolution. If there is no requirement for timeout * resolution, it is set to zero. * - * A successful call overwrites all 'capa' fields with the resulting values. Return value - * is 1 when timer capability meets or exceeds all requested values. The call returns 0, when - * the requested base frequency is not supported exactly, but capability meets or exceeds all other - * requested values. In this case, the call overwrites 'base_freq_hz' with the closest supported - * frequency. + * When the call returns success, 'capa' fields are overwritten in following ways. On return value + * of 1, timer supports the requested base frequency exactly, and meets or exceeds other requested + * values. The base frequency value is not modified, but other 'capa' fields are updated with + * resulting maximum capabilities. + * + * When the call returns 0, the requested base frequency is not supported exactly, but timer + * capabilities meet or exceed all other requested values. In this case, the call overwrites + * 'base_freq_hz' with the closest supported frequency and updates other 'capa' fields accordingly. * * Failure is returned when the requirements are not supported or the call fails otherwise. * @@ -115,8 +118,11 @@ void odp_timer_pool_param_init(odp_timer_pool_param_t *param); * to initialize timer pool parameters into their default values. * * Periodic timer expiration frequency is a multiple of the timer pool base frequency - * (odp_timer_pool_param_t::base_freq_hz). Use odp_timer_periodic_capability() to check - * which base frequencies and multipliers are supported. + * (odp_timer_pool_param_t::base_freq_hz). Depending on implementation, the base frequency may need + * to be selected carefully with respect to the timer pool source clock frequency. Use + * odp_timer_periodic_capability() to check which base frequencies and multipliers are supported. + * + * The call returns failure when requested parameter values are not supported. * * @param name Name of the timer pool or NULL. Maximum string length is * ODP_TIMER_POOL_NAME_LEN. @@ -125,8 +131,7 @@ void odp_timer_pool_param_init(odp_timer_pool_param_t *param); * @return Timer pool handle on success * @retval ODP_TIMER_POOL_INVALID on failure */ -odp_timer_pool_t odp_timer_pool_create(const char *name, - const odp_timer_pool_param_t *params); +odp_timer_pool_t odp_timer_pool_create(const char *name, const odp_timer_pool_param_t *params); /** * Start a timer pool @@ -186,6 +191,28 @@ uint64_t odp_timer_ns_to_tick(odp_timer_pool_t timer_pool, uint64_t ns); uint64_t odp_timer_current_tick(odp_timer_pool_t timer_pool); /** + * Sample tick values of timer pools + * + * Reads timer pool tick values simultaneously (or closely back-to-back) from all requested timer + * pools, and outputs those on success. Optionally, outputs corresponding source clock (HW) counter + * values, which are implementation specific and may be used for debugging. When a timer pool does + * not support reading of the source clock value, zero is written instead. Values are written into + * the output arrays in the same order which timer pools were defined. Nothing is written on + * failure. + * + * @param timer_pool Timer pools to sample + * @param[out] tick Tick value array for output (one element per timer pool) + * @param[out] clk_count Source clock counter value array for output (one element per + * timer pool), or NULL when counter values are not requested. + * @param num Number of timer pools to sample + * + * @retval 0 All requested timer pools sampled successfully + * @retval -1 Failure + */ +int odp_timer_sample_ticks(odp_timer_pool_t timer_pool[], uint64_t tick[], uint64_t clk_count[], + int num); + +/** * Query timer pool configuration and current state * * @param timer_pool Timer pool @@ -422,19 +449,22 @@ int ODP_DEPRECATE(odp_timer_set_rel)(odp_timer_t timer, uint64_t rel_tick, odp_e /** * Cancel a timer * - * Cancels a previously started single shot timer. A successful operation prevents timer - * expiration and returns the timeout event back to application. Application may use or free - * the event normally. + * Cancels a previously started single shot timer. A successful operation (#ODP_TIMER_SUCCESS) + * prevents timer expiration and returns the timeout event back to application. Application may + * use or free the event normally. * * When the timer is close to expire or has expired already, the call may not be able cancel it - * anymore. In this case, the call returns failure and the timeout is delivered to the destination - * queue. + * anymore. In this case, the call returns #ODP_TIMER_TOO_NEAR and the timeout is delivered to + * the destination queue. * * @param timer Timer - * @param[out] tmo_ev Pointer to an event handle for output + * @param[out] tmo_ev Pointer to an event handle for output. Event handle is written only + * on success. * - * @retval 0 Success. Active timer cancelled, timeout returned in 'tmo_ev' - * @retval <0 Failure. Timer inactive or already expired. + * @retval ODP_TIMER_SUCCESS Timer was cancelled successfully. Timeout event returned in 'tmo_ev'. + * @retval ODP_TIMER_TOO_NEAR Timer cannot be cancelled. Timer has expired already, or cannot be + * cancelled due to close expiration time. + * @retval ODP_TIMER_FAIL Other failure. */ int odp_timer_cancel(odp_timer_t timer, odp_event_t *tmo_ev); diff --git a/include/odp/api/spec/timer_types.h b/include/odp/api/spec/timer_types.h index fd23bdeca..f1e199352 100644 --- a/include/odp/api/spec/timer_types.h +++ b/include/odp/api/spec/timer_types.h @@ -1,5 +1,5 @@ /* Copyright (c) 2013-2018, Linaro Limited - * Copyright (c) 2019-2022, Nokia + * Copyright (c) 2019-2023, Nokia * * All rights reserved. * @@ -102,7 +102,15 @@ typedef struct { * Periodic timer capability */ typedef struct { - /** Periodic timer pool base frequency in hertz */ + /** + * Periodic timer pool base frequency in hertz + * + * Base frequency is represented as a fractional number where the fraction part is always + * less than one. In other words, the integer part specifies whole hertz whereas + * the fraction part specifies parts of a hertz (if any). The fraction part does not + * need to be reduced to its lowest terms - e.g. 100.5 Hz may be represented as 100 1/2 Hz, + * 100 5/10 Hz, or 100 Hz with some other equivalent fraction part. + */ odp_fract_u64_t base_freq_hz; /** Maximum base frequency multiplier */ @@ -358,7 +366,9 @@ typedef struct { * Use odp_timer_periodic_capability() to check base frequency support, * and resulting max_multiplier and resolution values. * - * The default value is zero. + * Fraction part of the value is always less than one, see + * odp_timer_periodic_capability_t::base_freq_hz for details. The default value + * is zero. * * An example with two timer frequencies: * base_freq_hz.integer = 33333, .numer = 1, .denom = 3 @@ -477,9 +487,9 @@ typedef struct odp_timer_periodic_start_t { /** First expiration time * * The first expiration time in absolute timer ticks. When zero, the first expiration time - * is one period after the current time. After the first expiration, timer expiration - * continues with the defined frequency. The tick value must be within one timer period - * from the current time. + * is one period after the current time, or as close to that as the implementation can + * achieve. After the first expiration, timer expiration continues with the defined + * frequency. The tick value must be less than one timer period after the current time. */ uint64_t first_tick; @@ -505,24 +515,49 @@ typedef struct odp_timer_periodic_start_t { } odp_timer_periodic_start_t; /** - * Return values of timer set calls. + * Return values for timer start, restart and cancel calls */ typedef enum { - /** Timer set operation succeeded */ + /** + * Timer operation succeeded + * + * Timer start, restart and cancel operations may return this value. + */ ODP_TIMER_SUCCESS = 0, - /** Timer set operation failed because expiration time is too near to - * the current time. */ + /** + * Timer operation failed, too near to the current time + * + * The operation failed because the requested time/timer has expired already, or is too + * near to the current time. Timer start, restart and cancel operations may return this + * value. + */ ODP_TIMER_TOO_NEAR = -1, - /** Timer set operation failed because expiration time is too far from - * the current time. */ + /** + * Timer operation failed, too far from the current time + * + * The operation failed because the requested time is too far from the current time. + * Only timer start and restart operations may return this value. + */ ODP_TIMER_TOO_FAR = -2, - /** Timer set operation failed */ + /** + * Timer operation failed + * + * The operation failed due to some other reason than timing of the request. Timer start, + * restart and cancel operations may return this value. + */ ODP_TIMER_FAIL = -3 -} odp_timer_set_t; +} odp_timer_retval_t; + +/** + * For backwards compatibility, odp_timer_set_t is synonym of odp_timer_retval_t + * + * @deprecated Use odp_timer_retval_t instead. + */ +typedef odp_timer_retval_t odp_timer_set_t; #if ODP_DEPRECATED_API /** diff --git a/include/odp/api/spec/traffic_mngr.h b/include/odp/api/spec/traffic_mngr.h index 9bd735a7a..2331cc133 100644 --- a/include/odp/api/spec/traffic_mngr.h +++ b/include/odp/api/spec/traffic_mngr.h @@ -206,19 +206,19 @@ typedef struct odp_tm_queue_stats_capability_t { union { /** Statistics counters in a bit field structure */ struct { - /** @see odp_tm_queue_stats_t::octets */ + /** See odp_tm_queue_stats_t::octets */ uint64_t octets : 1; - /** @see odp_tm_queue_stats_t::packets */ + /** See odp_tm_queue_stats_t::packets */ uint64_t packets : 1; - /** @see odp_tm_queue_stats_t::discards */ + /** See odp_tm_queue_stats_t::discards */ uint64_t discards : 1; - /** @see odp_tm_queue_stats_t::discard_octets */ + /** See odp_tm_queue_stats_t::discard_octets */ uint64_t discard_octets : 1; - /** @see odp_tm_queue_stats_t::errors */ + /** See odp_tm_queue_stats_t::errors */ uint64_t errors : 1; } counter; diff --git a/include/odp/api/time.h b/include/odp/api/time.h index 125e9118b..fb550724d 100644 --- a/include/odp/api/time.h +++ b/include/odp/api/time.h @@ -17,7 +17,6 @@ extern "C" { #endif -#include <odp/api/std_types.h> #include <odp/api/abi/time.h> #include <odp/api/spec/time.h> diff --git a/include/odp/api/time_types.h b/include/odp/api/time_types.h new file mode 100644 index 000000000..f7281d456 --- /dev/null +++ b/include/odp/api/time_types.h @@ -0,0 +1,28 @@ +/* Copyright (c) 2023, Nokia + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @file + * + * ODP time + */ + +#ifndef ODP_API_TIME_TYPES_H_ +#define ODP_API_TIME_TYPES_H_ + +#ifdef __cplusplus +extern "C" { +#endif + +#include <odp/api/abi/time_types.h> + +#include <odp/api/spec/time_types.h> + +#ifdef __cplusplus +} +#endif + +#endif |