/* Copyright (c) 2013-2018, Linaro Limited * Copyright (c) 2020-2021, Nokia * All rights reserved. * * SPDX-License-Identifier: BSD-3-Clause */ /** * @file * * ODP Packet IO */ #ifndef ODP_API_SPEC_PACKET_IO_H_ #define ODP_API_SPEC_PACKET_IO_H_ #include #ifdef __cplusplus extern "C" { #endif #include #include #include #include #include #include /** @defgroup odp_packet_io ODP PACKET IO * Packet IO interfaces. * * Packet IO is the Ingress and Egress interface to ODP processing. It * allows manipulation of the interface for setting such attributes as * number of queues, MAC address etc. * Pktio is usually followed by the classifier and a default class COS * can be set so that the scheduler may distribute flows. The interface * may be used directly in polled mode with odp_pktin_recv() and * odp_pktout_send(). * Diagnostic messages can be enhanced by using odp_pktio_to_u64 which * will generate a printable reference for a pktio handle for use with * the logging. * @{ */ /** * @typedef odp_pktio_t * Packet IO handle */ /** * @typedef odp_pktin_queue_t * Direct packet input queue handle */ /** * @typedef odp_pktout_queue_t * Direct packet output queue handle */ /** * @typedef odp_lso_profile_t * LSO profile handle */ /** * @def ODP_PKTIO_INVALID * Invalid packet IO handle */ /** * @def ODP_LSO_PROFILE_INVALID * Invalid LSO profile handle */ /** * @def ODP_PKTIO_MACADDR_MAXSIZE * Minimum size of output buffer for odp_pktio_mac_addr() * Actual MAC address sizes may be different. */ /** * @def ODP_PKTIN_NO_WAIT * Do not wait on packet input */ /** * Packet input mode */ typedef enum odp_pktin_mode_t { /** Direct packet input from the interface */ ODP_PKTIN_MODE_DIRECT = 0, /** Packet input through scheduler and scheduled event queues */ ODP_PKTIN_MODE_SCHED, /** Packet input through plain event queues */ ODP_PKTIN_MODE_QUEUE, /** Application will never receive from this interface */ ODP_PKTIN_MODE_DISABLED } odp_pktin_mode_t; /** * Packet output mode */ typedef enum odp_pktout_mode_t { /** Direct packet output on the interface */ ODP_PKTOUT_MODE_DIRECT = 0, /** Packet output through event queues */ ODP_PKTOUT_MODE_QUEUE, /** Packet output through traffic manager API */ ODP_PKTOUT_MODE_TM, /** Application will never send to this interface */ ODP_PKTOUT_MODE_DISABLED } odp_pktout_mode_t; /** * Packet input hash protocols * * The list of protocol header field combinations, which are included into * packet input hash calculation. */ typedef union odp_pktin_hash_proto_t { /** Protocol header fields for hashing */ struct { /** IPv4 addresses and UDP port numbers */ uint32_t ipv4_udp : 1; /** IPv4 addresses and TCP port numbers */ uint32_t ipv4_tcp : 1; /** IPv4 addresses */ uint32_t ipv4 : 1; /** IPv6 addresses and UDP port numbers */ uint32_t ipv6_udp : 1; /** IPv6 addresses and TCP port numbers */ uint32_t ipv6_tcp : 1; /** IPv6 addresses */ uint32_t ipv6 : 1; } proto; /** All bits of the bit field structure */ uint32_t all_bits; } odp_pktin_hash_proto_t; /** * Packet IO operation mode */ typedef enum odp_pktio_op_mode_t { /** Multithread safe operation * * Direct packet IO operation (recv or send) is multithread safe. Any * number of application threads may perform the operation * concurrently. */ ODP_PKTIO_OP_MT = 0, /** Not multithread safe operation * * Direct packet IO operation (recv or send) may not be multithread * safe. Application ensures synchronization between threads so that * simultaneously only single thread attempts the operation on * the same (pktin or pktout) queue. */ ODP_PKTIO_OP_MT_UNSAFE } odp_pktio_op_mode_t; /** * Packet input queue parameters override */ typedef struct odp_pktin_queue_param_ovr_t { /** Override for schedule group in odp_schedule_param_t * * This parameter is considered only when queue type is * ODP_QUEUE_TYPE_SCHED. */ odp_schedule_group_t group; } odp_pktin_queue_param_ovr_t; /** * Packet input vector configuration */ typedef struct odp_pktin_vector_config_t { /** Enable packet input vector * * When true, packet input vector is enabled and configured with vector * config parameters. Otherwise, packet input vector configuration * parameters are ignored. */ odp_bool_t enable; /** Vector pool * * Vector pool to allocate the vectors to hold packets. * The pool must have been created with the ODP_POOL_VECTOR type. */ odp_pool_t pool; /** Maximum time to wait for packets * * Maximum timeout in nanoseconds to wait for the producer to form the * vector of packet events (odp_packet_vector_t). This value should be * in the range of odp_pktin_vector_capability_t::min_tmo_ns to * odp_pktin_vector_capability_t::max_tmo_ns. */ uint64_t max_tmo_ns; /** Maximum number of packets in a vector * * The packet input subsystem forms packet vector events when either * it reaches odp_pktin_vector_config_t::max_tmo_ns or producer reaches * max_size packets. This value should be in the range of * odp_pktin_vector_capability_t::min_size to * odp_pktin_vector_capability_t::max_size. * * @note The maximum number of packets this vector can hold is defined * by odp_pool_param_t::vector::max_size with odp_pktin_vector_config_t::pool. * The max_size should not be greater than odp_pool_param_t::vector::max_size. */ uint32_t max_size; } odp_pktin_vector_config_t; /** * Packet input queue parameters */ typedef struct odp_pktin_queue_param_t { /** Operation mode * * The default value is ODP_PKTIO_OP_MT. Application may enable * performance optimization by defining ODP_PKTIO_OP_MT_UNSAFE when * applicable. */ odp_pktio_op_mode_t op_mode; /** Enable classifier * * * 0: Classifier is disabled (default) * * 1: Classifier is enabled. Use classifier to direct incoming * packets into pktin event queues. Classifier can be enabled * only in ODP_PKTIN_MODE_SCHED and ODP_PKTIN_MODE_QUEUE modes. * Both classifier and hashing cannot be enabled simultaneously * ('hash_enable' must be 0). */ odp_bool_t classifier_enable; /** Enable flow hashing * * * 0: Do not hash flows (default) * * 1: Enable flow hashing. Use flow hashing to spread incoming * packets into input queues. Hashing can be enabled in all * modes. Both classifier and hashing cannot be enabled * simultaneously ('classifier_enable' must be 0). */ odp_bool_t hash_enable; /** Protocol field selection for hashing * * Multiple protocols can be selected. Ignored when 'hash_enable' is * zero. The default value is all bits zero. */ odp_pktin_hash_proto_t hash_proto; /** Number of input queues to be created * * When classifier is enabled in odp_pktin_queue_config() this * value is ignored, otherwise at least one queue is required. * More than one input queues require flow hashing configured. * The maximum value is defined by pktio capability 'max_input_queues'. * Queue type is defined by the input mode. The default value is 1. */ unsigned int num_queues; /** Queue parameters * * These are used for input queue creation in ODP_PKTIN_MODE_QUEUE * or ODP_PKTIN_MODE_SCHED modes. Scheduler parameters are considered * only in ODP_PKTIN_MODE_SCHED mode. Default values are defined in * odp_queue_param_t documentation. * When classifier is enabled in odp_pktin_queue_config() this * value is ignored. */ odp_queue_param_t queue_param; /** Queue parameters override * * When the override array is defined, the same parameter value * in 'queue_param' is ignored and these per queue parameter * values are used instead. Array elements are used in order * (i.e. the first queue gets parameters from the first array * element, etc). * Must point to an array of num_queues elements or NULL to * disable queue parameters override. The default value is * NULL. */ odp_pktin_queue_param_ovr_t *queue_param_ovr; /** Packet input vector configuration */ odp_pktin_vector_config_t vector; } odp_pktin_queue_param_t; /** * Packet output queue parameters * * These parameters are used in ODP_PKTOUT_MODE_DIRECT and * ODP_PKTOUT_MODE_QUEUE modes. */ typedef struct odp_pktout_queue_param_t { /** Operation mode * * The default value is ODP_PKTIO_OP_MT. Application may enable * performance optimization by defining ODP_PKTIO_OP_MT_UNSAFE when * applicable. */ odp_pktio_op_mode_t op_mode; /** Number of output queues to be created. The value must be between * 1 and interface capability. The default value is 1. */ unsigned int num_queues; } odp_pktout_queue_param_t; /** * Packet IO parameters * * Packet IO interface level parameters. Use odp_pktio_param_init() to * initialize the structure with default values. */ typedef struct odp_pktio_param_t { /** Packet input mode * * The default value is ODP_PKTIN_MODE_DIRECT. */ odp_pktin_mode_t in_mode; /** Packet output mode * * The default value is ODP_PKTOUT_MODE_DIRECT. */ odp_pktout_mode_t out_mode; } odp_pktio_param_t; /** * Packet input configuration options bit field * * Packet input configuration options listed in a bit field structure. Packet * input timestamping may be enabled for all packets or at least for those that * belong to time synchronization protocol (PTP). * * Packet input checksum checking may be enabled or disabled. When it is * enabled, implementation will attempt to verify checksum correctness on * incoming packets and depending on drop configuration either deliver erroneous * packets with appropriate flags set (e.g. odp_packet_has_l3_error(), * odp_packet_l3_chksum_status()) or drop those. When packet dropping is * enabled, application will never receive a packet with the specified error * and may avoid to check the error flag. * * If checksum checking is enabled, IPv4 header checksum checking is always * done for packets that do not have IP options and L4 checksum checking * is done for unfragmented packets that do not have IPv4 options or IPv6 * extension headers. In other cases checksum checking may or may not * be done. For example, L4 checksum of fragmented packets is typically * not checked. * * IPv4 checksum checking may be enabled only when parsing level is * ODP_PROTO_LAYER_L3 or higher. Similarly, L4 level checksum checking * may be enabled only with parsing level ODP_PROTO_LAYER_L4 or higher. * * Whether checksum checking was done and whether a checksum was correct * can be queried for each received packet with odp_packet_l3_chksum_status() * and odp_packet_l4_chksum_status(). */ typedef union odp_pktin_config_opt_t { /** Option flags */ struct { /** Timestamp all packets on packet input */ uint64_t ts_all : 1; /** Timestamp (at least) IEEE1588 / PTP packets * on packet input */ uint64_t ts_ptp : 1; /** Check IPv4 header checksum on packet input */ uint64_t ipv4_chksum : 1; /** Check UDP checksum on packet input */ uint64_t udp_chksum : 1; /** Check TCP checksum on packet input */ uint64_t tcp_chksum : 1; /** Check SCTP checksum on packet input */ uint64_t sctp_chksum : 1; /** Drop packets with an IPv4 error on packet input */ uint64_t drop_ipv4_err : 1; /** Drop packets with an IPv6 error on packet input */ uint64_t drop_ipv6_err : 1; /** Drop packets with a UDP error on packet input */ uint64_t drop_udp_err : 1; /** Drop packets with a TCP error on packet input */ uint64_t drop_tcp_err : 1; /** Drop packets with a SCTP error on packet input */ uint64_t drop_sctp_err : 1; } bit; /** All bits of the bit field structure * * This field can be used to set/clear all flags, or bitwise * operations over the entire structure. */ uint64_t all_bits; } odp_pktin_config_opt_t; /** * Packet output configuration options bit field * * Packet output configuration options listed in a bit field structure. Packet * output checksum insertion may be enabled or disabled (e.g. ipv4_chksum_ena): * * 0: Disable checksum insertion. Application will not request checksum * insertion for any packet. This is the default value for xxx_chksum_ena * bits. * 1: Enable checksum insertion. Application will request checksum insertion * for some packets. * * When checksum insertion is enabled, application may use configuration options * to set the default behaviour on packet output (e.g. ipv4_chksum): * * 0: Do not insert checksum by default. This is the default value for * xxx_chksum bits. * 1: Calculate and insert checksum by default. * * These defaults may be overridden on per packet basis using e.g. * odp_packet_l4_chksum_insert(). * * For correct operation, packet metadata must provide valid offsets and type * flags for the appropriate layer 3 and layer 4 protocols. L3 and L4 offsets * can be updated with odp_packet_l3_offset_set() and odp_packet_l4_offset_set() * calls. L3 and L4 type flags can be updated using odp_packet_has_*_set() calls * For example, UDP checksum calculation needs both L3 and L4 types (IP and UDP) and * L3 and L4 offsets (to access IP and UDP headers), while IP checksum * calculation only needs L3 type (IP) and L3 offset (to access IP header). * When application (e.g. a switch) does not modify L3/L4 data and thus checksum * does not need to be updated, checksum insertion should be disabled for optimal * performance. * * UDP, TCP and SCTP checksum insertion must not be requested for IP fragments. * Use checksum override function (odp_packet_l4_chksum_insert()) to disable * checksumming when sending a fragment through a packet IO interface that has * the relevant L4 checksum insertion enabled. * * Result of checksum insertion at packet output is undefined if the protocol * headers required for checksum calculation are not well formed. Packet must * contain at least as many data bytes after L3/L4 offsets as the headers * indicate. Other data bytes of the packet are ignored for the checksum * insertion. */ typedef union odp_pktout_config_opt_t { /** Option flags for packet output */ struct { /** Enable Tx timestamp capture */ uint64_t ts_ena : 1; /** Enable IPv4 header checksum insertion */ uint64_t ipv4_chksum_ena : 1; /** Enable UDP checksum insertion */ uint64_t udp_chksum_ena : 1; /** Enable TCP checksum insertion */ uint64_t tcp_chksum_ena : 1; /** Enable SCTP checksum insertion */ uint64_t sctp_chksum_ena : 1; /** Insert IPv4 header checksum by default */ uint64_t ipv4_chksum : 1; /** Insert UDP checksum on packet by default */ uint64_t udp_chksum : 1; /** Insert TCP checksum on packet by default */ uint64_t tcp_chksum : 1; /** Insert SCTP checksum on packet by default */ uint64_t sctp_chksum : 1; /** Packet references not used on packet output * * When set, application indicates that it will not transmit * packet references on this packet IO interface. * Since every ODP implementation supports it, it is always * ok to set this flag. * * 0: Packet references may be transmitted on the * interface (the default value). * 1: Packet references will not be transmitted on the * interface. */ uint64_t no_packet_refs : 1; /** Enable packet aging and drop * * 0: application will not request packet aging (default) * 1: application may request packet aging */ uint64_t aging_ena : 1; /** Enable packet transmit completion event requests * * Use pktio capability tx_compl to check if TX completion events are supported. * * 0: Application will not request packet TX completion events (default) * 1: Application may request packet TX completion events */ uint64_t tx_compl_ena : 1; /** Enable packet protocol stats update */ uint64_t proto_stats_ena : 1; } bit; /** All bits of the bit field structure * * This field can be used to set/clear all flags, or bitwise * operations over the entire structure. */ uint64_t all_bits; } odp_pktout_config_opt_t; /** * Parser layers * * @deprecated Use odp_proto_layer_t instead */ typedef odp_proto_layer_t odp_pktio_parser_layer_t; /** No layers * @deprecated Use ODP_PROTO_LAYER_NONE, instead */ #define ODP_PKTIO_PARSER_LAYER_NONE ODP_PROTO_LAYER_NONE /** Layer L2 protocols (Ethernet, VLAN, ARP, etc) * @deprecated Use ODP_PROTO_LAYER_L2, instead */ #define ODP_PKTIO_PARSER_LAYER_L2 ODP_PROTO_LAYER_L2 /** Layer L3 protocols (IPv4, IPv6, ICMP, IPsec, etc) * @deprecated Use ODP_PROTO_LAYER_L3, instead */ #define ODP_PKTIO_PARSER_LAYER_L3 ODP_PROTO_LAYER_L3 /** Layer L4 protocols (UDP, TCP, SCTP) * @deprecated Use ODP_PROTO_LAYER_L4, instead */ #define ODP_PKTIO_PARSER_LAYER_L4 ODP_PROTO_LAYER_L4 /** All layers * @deprecated Use ODP_PROTO_LAYER_ALL instead */ #define ODP_PKTIO_PARSER_LAYER_ALL ODP_PROTO_LAYER_ALL /** * Parser configuration */ typedef struct odp_pktio_parser_config_t { /** Protocol parsing level in packet input * * Application requires that protocol headers in a packet are checked * up to this layer during packet input. Use ODP_PROTO_LAYER_ALL for * all layers. Packet metadata for this and all preceding layers are * set. In addition, offset (and pointer) to the next layer is set. * Other layer/protocol specific metadata have undefined values. * * The default value is ODP_PROTO_LAYER_ALL. */ odp_proto_layer_t layer; } odp_pktio_parser_config_t; /** * Packet IO configuration options * * Packet IO interface level configuration options. Use odp_pktio_capability() * to see which options are supported by the implementation. * Use odp_pktio_config_init() to initialize the structure with default values. */ typedef struct odp_pktio_config_t { /** Packet input configuration options bit field * * Default value for all bits is zero. */ odp_pktin_config_opt_t pktin; /** Packet output configuration options bit field * * Default value for all bits is zero. */ odp_pktout_config_opt_t pktout; /** Packet input parser configuration */ odp_pktio_parser_config_t parser; /** Interface loopback mode * * In this mode the packets sent out through the interface is * looped back to input of the same interface. Supporting loopback mode * is an optional feature per interface and should be queried in the * interface capability before enabling the same. * * Default value is false. */ odp_bool_t enable_loop; /** Inbound IPSEC inlined with packet input * * Enable/disable inline inbound IPSEC operation. When enabled packet * input directs all IPSEC packets automatically to IPSEC inbound * processing. IPSEC configuration (through IPSEC API) must be done * before enabling this feature in pktio. * Packets that are not (recognized as) IPSEC are processed * according to the packet input configuration. * * 0: Disable inbound IPSEC inline operation (default) * 1: Enable inbound IPSEC inline operation * * @see odp_ipsec_config(), odp_ipsec_sa_create() */ odp_bool_t inbound_ipsec; /** Outbound IPSEC inlined with packet output * * Enable/disable inline outbound IPSEC operation. When enabled IPSEC * outbound processing can send outgoing IPSEC packets directly * to the pktio interface for output. IPSEC configuration is done * through the IPSEC API. * * Support of outbound IPSEC inline operation with traffic manager * (ODP_PKTOUT_MODE_TM) can be queried with odp_ipsec_capability(). * * * 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() */ odp_bool_t outbound_ipsec; /** Enable Large Send Offload (LSO) * * LSO operation cannot be combined with IPSEC or Traffic Manager (ODP_PKTOUT_MODE_TM) on * packet output. * * 0: Application will not use LSO (default) * 1: Application will use LSO * * @see odp_pktout_send_lso() */ odp_bool_t enable_lso; /** Packet input reassembly configuration */ odp_reass_config_t reassembly; } odp_pktio_config_t; /** * Packet IO set operations * * Supported packet IO interface set operations listed in a bit field structure. */ typedef union odp_pktio_set_op_t { /** Operation flags */ struct { /** Promiscuous mode */ uint32_t promisc_mode : 1; /** MAC address */ uint32_t mac_addr : 1; /** Per port header offset(skip)set */ uint32_t skip_offset : 1; /** Maximum frame length */ uint32_t maxlen : 1; } op; /** All bits of the bit field structure. * This field can be used to set/clear all flags, or bitwise * operations over the entire structure. */ uint32_t all_bits; } odp_pktio_set_op_t; /** Maximum number of custom LSO fields supported by ODP API */ #define ODP_LSO_MAX_CUSTOM 8 /** LSO custom modification options */ typedef enum odp_lso_modify_t { /** Add current segment number. Numbering starts from zero. */ ODP_LSO_ADD_SEGMENT_NUM = 0x1, /** Add number of payload bytes in the segment */ ODP_LSO_ADD_PAYLOAD_LEN = 0x2, /** Add number of payload bytes in all previous segments */ ODP_LSO_ADD_PAYLOAD_OFFSET = 0x4 } odp_lso_modify_t; /** LSO protocol options * * An LSO operation may perform segmentation on these protocols. */ typedef enum odp_lso_protocol_t { /** Protocol not selected. */ ODP_LSO_PROTO_NONE = 0, /** Custom protocol. LSO performs only custom field updates to the packet headers. */ ODP_LSO_PROTO_CUSTOM, /** LSO performs IPv4 fragmentation. * * IP header length and checksum fields are updated. IP fragmentation related fields are * filled and IPv4 Identification field value is copied from the original packet. */ ODP_LSO_PROTO_IPV4, /** LSO performs IPv6 fragmentation. */ ODP_LSO_PROTO_IPV6, /** LSO performs TCP segmentation on top of IPv4. * * IP header length and checksum fields are updated. IP fragmentation is not performed * and IPv4 Don't Fragment bit is not set. Unique IPv4 Identification field values * are generated. Those are usually increments of the IPv4 ID field value in the packet. */ ODP_LSO_PROTO_TCP_IPV4, /** LSO performs TCP segmentation on top of IPv6. */ ODP_LSO_PROTO_TCP_IPV6, /** LSO performs SCTP segmentation on top of IPv4. */ ODP_LSO_PROTO_SCTP_IPV4, /** LSO performs SCTP segmentation on top of IPv6. */ ODP_LSO_PROTO_SCTP_IPV6 } odp_lso_protocol_t; /** Large Send Offload (LSO) capabilities */ typedef struct odp_lso_capability_t { /** Maximum number of LSO profiles. When zero, LSO is not supported. */ uint32_t max_profiles; /** Maximum number of LSO profiles per packet IO interface. When zero, LSO is not * supported by the interface. */ uint32_t max_profiles_per_pktio; /** Maximum number of segments in an input packet. When one, LSO operation accepts only * non-segmented packets as input. */ uint32_t max_packet_segments; /** Maximum number of segments an LSO operation may create. This implies that * the maximum supported input packet payload size for an LSO operation is * max_segments * max_payload_len bytes. */ uint32_t max_segments; /** Maximum payload length per an LSO generated packet (in bytes). This is the maximum value * for max_payload_len in odp_packet_lso_opt_t. */ uint32_t max_payload_len; /** Maximum supported offset to the packet payload (in bytes). This is the maximum value * for payload_offset in odp_packet_lso_opt_t. */ uint32_t max_payload_offset; /** Supported LSO custom modification options */ struct { /** ODP_LSO_ADD_SEGMENT_NUM support */ uint16_t add_segment_num:1; /** ODP_LSO_ADD_PAYLOAD_LEN support */ uint16_t add_payload_len:1; /** ODP_LSO_ADD_PAYLOAD_OFFSET support */ uint16_t add_payload_offset:1; } mod_op; /** Maximum number of custom fields supported per LSO profile. When zero, custom * fields are not supported. */ uint8_t max_num_custom; /** Supported LSO protocol options */ struct { /** ODP_LSO_PROTO_CUSTOM support */ uint32_t custom:1; /** ODP_LSO_PROTO_IPV4 support */ uint32_t ipv4:1; /** ODP_LSO_PROTO_IPV6 support */ uint32_t ipv6:1; /** ODP_LSO_PROTO_TCP_IPV4 support */ uint32_t tcp_ipv4:1; /** ODP_LSO_PROTO_TCP_IPV6 support */ uint32_t tcp_ipv6:1; /** ODP_LSO_PROTO_SCTP_IPV4 support */ uint32_t sctp_ipv4:1; /** ODP_LSO_PROTO_SCTP_IPV6 support */ uint32_t sctp_ipv6:1; } proto; } odp_lso_capability_t; /** * Packet input vector capabilities */ typedef struct odp_pktin_vector_capability_t { /** Packet input vector availability */ odp_support_t supported; /** Maximum number of packets that can be accumulated into a packet * vector by a producer * * odp_pktin_vector_config_t::max_size should not be greater than this * value. */ uint32_t max_size; /** Minimum value allowed to be configured to * odp_pktin_vector_config_t::max_size */ uint32_t min_size; /** Maximum timeout in nanoseconds for the producer to wait for the * vector of packets * * odp_pktin_vector_config_t::max_tmo_ns should not be greater than this * value. */ uint64_t max_tmo_ns; /** Minimum value allowed to be configured to * odp_pktin_vector_config_t::max_tmo_ns */ uint64_t min_tmo_ns; } odp_pktin_vector_capability_t; /** * Packet IO capabilities */ typedef struct odp_pktio_capability_t { /** Maximum number of input queues */ unsigned int max_input_queues; /** Maximum number of output queues */ unsigned int max_output_queues; /** Supported pktio configuration options */ odp_pktio_config_t config; /** Supported set operations * * A bit set to one indicates a supported operation. All other bits are * set to zero. */ odp_pktio_set_op_t set_op; /** @deprecated Use enable_loop inside odp_pktin_config_t */ odp_bool_t ODP_DEPRECATE(loop_supported); /** Packet input vector capability */ odp_pktin_vector_capability_t vector; /** LSO capabilities */ odp_lso_capability_t lso; /** Supported frame lengths for odp_pktio_maxlen_set() * * A frame length value of zero indicates an unsupported operation. */ struct { /** Equal maximum frame length for both packet input and output * * When set, the same maximum frame length value has to be used * for both input and output directions. */ odp_bool_t equal; /** Minimum valid value for 'maxlen_input' */ uint32_t min_input; /** Maximum valid value for 'maxlen_input' */ uint32_t max_input; /** Minimum valid value for 'maxlen_output' */ uint32_t min_output; /** Maximum valid value for 'maxlen_output' */ uint32_t max_output; } maxlen; /** * Max Tx aging timeout in nano seconds supported when packet aging * feature is supported. * * 0: aging is not supported * >0: maximum aging timeout supported in nanoseconds */ uint64_t max_tx_aging_tmo_ns; /** Supported packet Tx completion options */ struct { /** * Scheduled queue support * * This defines whether schedule queues are supported for receiving Tx * completion events. * * 0: Scheduled queues are not supported for receiving Tx completion events. * 1: Scheduled queues are supported for receiving Tx completion events. * @see odp_packet_tx_compl_request() */ odp_bool_t queue_type_sched; /** * Plain queue support * * This defines whether plain queues are supported for receiving Tx * completion events. * * 0: Plain queues are not supported for receiving Tx completion events. * 1: Plain queues are supported for receiving Tx completion events. * @see odp_packet_tx_compl_request() */ odp_bool_t queue_type_plain; /** ODP_PACKET_TX_COMPL_ALL supported */ uint32_t mode_all:1; } tx_compl; /** Packet input reassembly capability */ odp_reass_capability_t reassembly; /** Statistics counters capabilities */ odp_pktio_stats_capability_t stats; } odp_pktio_capability_t; /** * Open a packet IO interface * * An ODP program can open a single packet IO interface per device, attempts * to open an already open device will fail, returning ODP_PKTIO_INVALID with * errno set. Use odp_pktio_lookup() to obtain a handle to an already open * device. Packet IO parameters provide interface level configuration options. * * Use odp_pktio_param_init() to initialize packet IO parameters into their * default values. Default values are also used when 'param' pointer is NULL. * * Packet input queue configuration must be setup with * odp_pktin_queue_config() before odp_pktio_start() is called. When packet * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() call is * optional and will ignore all parameters. * * Packet output queue configuration must be setup with * odp_pktout_queue_config() before odp_pktio_start() is called. When packet * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, * odp_pktout_queue_config() call is optional and will ignore all parameters. * * Packet receive and transmit on the interface is enabled with a call to * odp_pktio_start(). If not specified otherwise, any interface level * configuration must not be changed when the interface is active (between start * and stop calls). * * In summary, a typical pktio interface setup sequence is ... * * odp_pktio_open() * * odp_pktin_queue_config() * * odp_pktout_queue_config() * * odp_pktio_start() * * ... and tear down sequence is: * * odp_pktio_stop() * * odp_pktio_close() * * @param name Packet IO device name * @param pool Default pool from which to allocate storage for packets * received over this interface, must be of type ODP_POOL_PACKET * @param param Packet IO parameters. Uses defaults when NULL. * * @return Packet IO handle * @retval ODP_PKTIO_INVALID on failure * * @note The device name "loop" is a reserved name for a loopback device used * for testing purposes. * * @note Packets arriving via this interface assigned to a CoS by the * classifier are received into the pool associated with that CoS. This * will occur either because this pktio is assigned a default CoS via * the odp_pktio_default_cos_set() routine, or because a matching PMR * assigned the packet to a specific CoS. The default pool specified * here is applicable only for those packets that are not assigned to a * more specific CoS. * * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() */ odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, const odp_pktio_param_t *param); /** * Query packet IO interface capabilities * * Outputs packet IO interface capabilities on success. * * @param pktio Packet IO handle * @param[out] capa Pointer to capability structure for output * * @retval 0 on success * @retval <0 on failure */ int odp_pktio_capability(odp_pktio_t pktio, odp_pktio_capability_t *capa); /** * Maximum packet IO interface index * * Return the maximum packet IO interface index. Interface indexes * (e.g. returned by odp_pktio_index()) range from zero to this maximum value. * * @return Maximum packet IO interface index */ unsigned int odp_pktio_max_index(void); /** * Configure packet IO interface options * * Select interface level configuration options before the interface is * activated (before odp_pktio_start() call). This step is optional in pktio * interface setup sequence. Use odp_pktio_capability() to query configuration * capabilities. Use odp_pktio_config_init() to initialize * configuration options into their default values. Default values are used * when 'config' pointer is NULL. * * @param pktio Packet IO handle * @param config Packet IO interface configuration. Uses defaults * when NULL. * * @retval 0 on success * @retval <0 on failure */ int odp_pktio_config(odp_pktio_t pktio, const odp_pktio_config_t *config); /** * Configure packet input queues * * Setup a number of packet input queues and configure those. The maximum number * of queues is platform dependent and can be queried with * odp_pktio_capability(). Use odp_pktin_queue_param_init() to initialize * parameters into their default values. Default values are also used when * 'param' pointer is NULL. * * Queue handles for input queues can be requested with odp_pktin_queue() or * odp_pktin_event_queue() after this call. All requested queues are setup on * success, no queues are setup on failure. Each call reconfigures input queues * and may invalidate all previous queue handles. * * @param pktio Packet IO handle * @param param Packet input queue configuration parameters. Uses defaults * when NULL. * * @retval 0 on success * @retval <0 on failure * * @see odp_pktio_capability(), odp_pktin_queue(), odp_pktin_event_queue() */ int odp_pktin_queue_config(odp_pktio_t pktio, const odp_pktin_queue_param_t *param); /** * Configure packet output queues * * Setup a number of packet output queues and configure those. The maximum * number of queues is platform dependent and can be queried with * odp_pktio_capability(). Use odp_pktout_queue_param_init() to initialize * parameters into their default values. Default values are also used when * 'param' pointer is NULL. * * Queue handles for output queues can be requested with odp_pktout_queue() or * odp_pktout_event_queue() after this call. All requested queues are setup on * success, no queues are setup on failure. Each call reconfigures output queues * and may invalidate all previous queue handles. * * @param pktio Packet IO handle * @param param Packet output queue configuration parameters. Uses defaults * when NULL. * * @retval 0 on success * @retval <0 on failure * * @see odp_pktio_capability(), odp_pktout_queue(), odp_pktout_event_queue() */ int odp_pktout_queue_config(odp_pktio_t pktio, const odp_pktout_queue_param_t *param); /** * Event queues for packet input * * Returns the number of input queues configured for the interface in * ODP_PKTIN_MODE_QUEUE and ODP_PKTIN_MODE_SCHED modes. Outputs up to 'num' * queue handles when the 'queues' array pointer is not NULL. If return value is * larger than 'num', there are more queues than the function was allowed to * output. If return value (N) is less than 'num', only queues[0 ... N-1] have * been written. * * In addition to packet input, application and other parts of ODP (e.g. timer) * may enqueue events into these queues. Depending on the queue mode, application * uses either odp_queue_deq() or odp_schedule() (or variants of those) to receive * packets and other events from these queues. * * @param pktio Packet IO handle * @param[out] queues Points to an array of queue handles for output * @param num Maximum number of queue handles to output * * @return Number of packet input queues * @retval <0 on failure */ int odp_pktin_event_queue(odp_pktio_t pktio, odp_queue_t queues[], int num); /** * Direct packet input queues * * Returns the number of input queues configured for the interface in * ODP_PKTIN_MODE_DIRECT mode. Outputs up to 'num' queue handles when the * 'queues' array pointer is not NULL. If return value is larger than 'num', * there are more queues than the function was allowed to output. If return * value (N) is less than 'num', only queues[0 ... N-1] have been written. * * Packets from these queues are received with odp_pktin_recv(). * * @param pktio Packet IO handle * @param[out] queues Points to an array of queue handles for output * @param num Maximum number of queue handles to output * * @return Number of packet input queues * @retval <0 on failure */ int odp_pktin_queue(odp_pktio_t pktio, odp_pktin_queue_t queues[], int num); /** * Event queues for packet output * * Returns the number of output queues configured for the interface in * ODP_PKTOUT_MODE_QUEUE. Outputs up to 'num' queue handles when the * 'queues' array pointer is not NULL. If return value is larger than 'num', * there are more queues than the function was allowed to output. If return * value (N) is less than 'num', only queues[0 ... N-1] have been written. * * Packets are enqueued to these queues with odp_queue_enq() or * odp_queue_enq_multi(). Behaviour is undefined if other events than packets * are enqueued. Application cannot dequeue from these queues. * * @param pktio Packet IO handle * @param[out] queues Points to an array of queue handles for output * @param num Maximum number of queue handles to output * * @return Number of packet output queues * @retval <0 on failure */ int odp_pktout_event_queue(odp_pktio_t pktio, odp_queue_t queues[], int num); /** * Direct packet output queues * * Returns the number of output queues configured for the interface in * ODP_PKTOUT_MODE_DIRECT mode. Outputs up to 'num' queue handles when the * 'queues' array pointer is not NULL. If return value is larger than 'num', * there are more queues than the function was allowed to output. If return * value (N) is less than 'num', only queues[0 ... N-1] have been written. * * Packets are sent to these queues with odp_pktout_send(). * * @param pktio Packet IO handle * @param[out] queues Points to an array of queue handles for output * @param num Maximum number of queue handles to output * * @return Number of packet output queues * @retval <0 on failure */ int odp_pktout_queue(odp_pktio_t pktio, odp_pktout_queue_t queues[], int num); /** * Start packet receive and transmit * * Activate packet receive and transmit on a previously opened or stopped * interface. The interface can be stopped with a call to odp_pktio_stop(). * * @param pktio Packet IO handle * * @retval 0 on success * @retval <0 on failure * * @see odp_pktio_open(), odp_pktio_stop() */ int odp_pktio_start(odp_pktio_t pktio); /** * Stop packet receive and transmit * * Stop packet receive and transmit on a previously started interface. New * packets are not received from or transmitted to the network. Packets already * received from the network may be still available from interface and * application can receive those normally. New packets may not be accepted for * transmit. Packets already stored for transmit are not freed. A following * odp_packet_start() call restarts packet receive and transmit. * * @param pktio Packet IO handle * * @retval 0 on success * @retval <0 on failure * * @see odp_pktio_start(), odp_pktio_close() */ int odp_pktio_stop(odp_pktio_t pktio); /** * Close a packet IO interface * * Close a stopped packet IO interface. This call frees all remaining packets * stored in pktio receive and transmit side buffers. The pktio is destroyed * and the handle must not be used for other calls. After a successful call, * the same pktio device can be opened again with a odp_pktio_open() call. * * @param pktio Packet IO handle * * @retval 0 on success * @retval <0 on failure * * @see odp_pktio_stop(), odp_pktio_open() */ int odp_pktio_close(odp_pktio_t pktio); /** * Return a packet IO handle for an already open device * * @param name Packet IO device name * * @return Packet IO handle * @retval ODP_PKTIO_INVALID on failure */ odp_pktio_t odp_pktio_lookup(const char *name); /** * Receive packets directly from an interface input queue * * Receives up to 'num' packets from the pktio interface input queue. Returns * the number of packets received. * * When input queue parameter 'op_mode' has been set to ODP_PKTIO_OP_MT_UNSAFE, * the operation is optimized for single thread operation per queue and the same * queue must not be accessed simultaneously from multiple threads. * * @param queue Packet input queue handle for receiving packets * @param[out] packets[] Packet handle array for output of received packets * @param num Maximum number of packets to receive * * @return Number of packets received * @retval <0 on failure * * @see odp_pktin_queue() */ int odp_pktin_recv(odp_pktin_queue_t queue, odp_packet_t packets[], int num); /** * Receive packets directly from an interface input queue with timeout * * Provides the same functionality as odp_pktin_recv(), except that waits if * there are no packets available. Wait time is specified by the 'wait' * parameter. * * @param queue Packet input queue handle for receiving packets * @param[out] packets[] Packet handle array for output of received packets * @param num Maximum number of packets to receive * @param wait Wait time specified as as follows: * * ODP_PKTIN_NO_WAIT: Do not wait * * Other values specify the minimum time to wait. * Use odp_pktin_wait_time() to convert nanoseconds * to a valid parameter value. Wait time may be * rounded up a small, platform specific amount. * * @return Number of packets received * @retval <0 on failure */ int odp_pktin_recv_tmo(odp_pktin_queue_t queue, odp_packet_t packets[], int num, uint64_t wait); /** * Receive packets directly from multiple interface input queues with timeout * * Receives up to 'num' packets from one of the specified pktio interface input * queues. The index of the source queue is stored into 'from' output * parameter. If there are no packets available on any of the queues, waits for * packets depending on 'wait' parameter value. Returns the number of packets * received. * * When an input queue has been configured with 'op_mode' value * ODP_PKTIO_OP_MT_UNSAFE, the operation is optimized for single thread * operation and the same queue must not be accessed simultaneously from * multiple threads. * * It is implementation specific in which order the queues are checked for * packets. Application may improve fairness of queue service levels by * circulating queue handles between consecutive calls (e.g. [q0, q1, q2, q3] -> * [q1, q2, q3, q0] -> [q2, q3, ...). * * @param queues[] Packet input queue handles for receiving packets * @param num_q Number of input queues * @param[out] from Pointer for output of the source queue index. Ignored * when NULL. * @param[out] packets[] Packet handle array for output of received packets * @param num Maximum number of packets to receive * @param wait Wait time specified as as follows: * * ODP_PKTIN_NO_WAIT: Do not wait * * Other values specify the minimum time to wait. * Use odp_pktin_wait_time() to convert nanoseconds * to a valid parameter value. Wait time may be * rounded up a small, platform specific amount. * * @return Number of packets received * @retval <0 on failure */ int odp_pktin_recv_mq_tmo(const odp_pktin_queue_t queues[], unsigned int num_q, unsigned int *from, odp_packet_t packets[], int num, uint64_t wait); /** * Packet input wait time * * Converts nanoseconds to wait time values for packet input functions. * * @param nsec Minimum number of nanoseconds to wait * * @return Wait parameter value for packet input functions */ uint64_t odp_pktin_wait_time(uint64_t nsec); /** * Send packets directly to an interface output queue * * Sends out a number of packets to the interface output queue. When * output queue parameter 'op_mode' has been set to ODP_PKTIO_OP_MT_UNSAFE, * 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. * * 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 * specified e.g. for protocol offload purposes. Link protocol specific frame * checksum and padding are added to frames before transmission. * * @param queue Packet output queue handle for sending packets * @param packets[] Array of packets to send * @param num Number of packets to send * * @return Number of packets sent * @retval <0 on failure */ int odp_pktout_send(odp_pktout_queue_t queue, const odp_packet_t packets[], int num); /** * LSO profile parameters */ typedef struct odp_lso_profile_param_t { /** * Segmentation protocol * * Selects on which protocol LSO operation performs segmentation (e.g. IP fragmentation vs. * TCP segmentation). When ODP_LSO_PROTO_CUSTOM is selected, only custom field * modifications are performed. The default value is ODP_LSO_PROTO_NONE. Check LSO * capability for supported protocols. */ odp_lso_protocol_t lso_proto; /** * Custom fields * * Set lso_proto to ODP_LSO_PROTO_CUSTOM when using custom fields. Fields are defined * in the same order they appear in the packet. */ struct { /** Custom field to be modified by LSO */ struct { /** Field modify operation. Selects how value of the field is modified * from its original value during segmentation. Field value is assumed * to be in network (big endian) byte order. */ odp_lso_modify_t mod_op; /** Field offset in bytes from packet start */ uint32_t offset; /** Field size in bytes. Valid values are 1, 2, 4, and 8 bytes. */ uint8_t size; } field[ODP_LSO_MAX_CUSTOM]; /** Number of custom fields specified. The default value is 0. */ uint8_t num_custom; } custom; } odp_lso_profile_param_t; /** * Initialize LSO profile parameters * * Initialize an odp_lso_profile_param_t to its default values for all fields. * * @param param Address of the odp_lso_profile_param_t to be initialized */ void odp_lso_profile_param_init(odp_lso_profile_param_t *param); /** * Create LSO profile * * LSO profile defines the set of segmentation operations to be performed to a packet. LSO profiles * are created before the packet IO interface is started (after odp_pktio_config() and before * odp_pktio_start()). * * See odp_lso_capability_t for maximum number of profiles supported and other LSO capabilities. * * @param pktio Packet IO interface which is used with this LSO profile * @param param LSO profile parameters * * @return LSO profile handle * @retval ODP_LSO_PROFILE_INVALID on failure */ odp_lso_profile_t odp_lso_profile_create(odp_pktio_t pktio, const odp_lso_profile_param_t *param); /** * Destroy LSO profile * * LSO profiles can be destoyed only when the packet IO interface is not active (i.e. after it * has been stopped). * * @param lso_profile LSO profile to be destroyed * * @retval 0 on success * @retval <0 on failure */ int odp_lso_profile_destroy(odp_lso_profile_t lso_profile); /** * Send packets with segmentation offload * * Like odp_pktout_send(), but splits a packet payload into 'max_payload_len' or smaller segments * during output. Packet headers (before 'payload_offset') are copied into each segment and * automatically modified before transmission. Header updates are based on segmentation protocol * selection (odp_lso_profile_param_t::lso_proto) in LSO profile. Header checksums are updated * after modifications. L3/L4 header modifications (see e.g. ODP_LSO_PROTO_TCP_IPV4) require that * L3/L4 layer offsets in the packet are valid (see e.g. odp_packet_l3_offset()). * * In addition, custom field updates may be used to cover unsupported or proprietary protocols. * Custom fields must not overlap with each other and can be used only when ODP_LSO_PROTO_CUSTOM * is selected. * * Packets are processed and transmitted in the array order. Segments of each packet are transmitted * in ascending order. * * When all packets share the same LSO options, usage of 'lso_opt' parameter may improve * performance as a number of packet metadata writes/reads are avoided. Results are undefined if * 'lso_opt' is NULL and a packet misses LSO options. * * Check LSO support level from packet IO capabilities (odp_pktio_capability_t). * * @param queue Packet output queue handle * @param packet[] Array of packets to be LSO processed and sent * @param num Number of packets * @param lso_opt When set, LSO options to be used for all packets. When NULL, LSO options are * read from each packet (see odp_packet_lso_request()). * * @return Number of packets successfully segmented (0 ... num) * @retval <0 on failure */ int odp_pktout_send_lso(odp_pktout_queue_t queue, const odp_packet_t packet[], int num, const odp_packet_lso_opt_t *lso_opt); /** * MTU value of a packet IO interface * * @deprecated Use odp_pktin_maxlen() and odp_pktout_maxlen() instead. MTU was * not well defined. There may be difference between MTU and maximum frame * length values. * * @param pktio Packet IO handle. * * @return MTU value on success * @retval 0 on failure */ uint32_t ODP_DEPRECATE(odp_pktio_mtu)(odp_pktio_t pktio); /** * Enable/Disable promiscuous mode on a packet IO interface. * * @param pktio Packet IO handle. * @param enable 1 to enable, 0 to disable. * * @retval 0 on success * @retval <0 on failure */ int odp_pktio_promisc_mode_set(odp_pktio_t pktio, odp_bool_t enable); /** * Determine if promiscuous mode is enabled for a packet IO interface. * * @param pktio Packet IO handle. * * @retval 1 if promiscuous mode is enabled. * @retval 0 if promiscuous mode is disabled. * @retval <0 on failure */ int odp_pktio_promisc_mode(odp_pktio_t pktio); /** * Maximum frame length at packet input * * Maximum frame length in bytes that the packet IO interface can receive. * For Ethernet, the frame length bytes start with MAC addresses and continue * to the end of the payload. So, Ethernet checksum, interpacket gap * and preamble bytes are excluded from the length. * * @param pktio Packet IO handle. * * @return Maximum frame length at packet input * @retval 0 on failure */ uint32_t odp_pktin_maxlen(odp_pktio_t pktio); /** * Maximum frame length at packet output * * Maximum frame length in bytes that the packet IO interface can transmit. * For Ethernet, the frame length bytes start with MAC addresses and continue * to the end of the payload. So, Ethernet checksum, interpacket gap * and preamble bytes are excluded from the length. * * @param pktio Packet IO handle. * * @return Maximum frame length at packet output * @retval 0 on failure */ uint32_t odp_pktout_maxlen(odp_pktio_t pktio); /** * Set maximum frame lengths * * Set the maximum frame lengths in bytes that the packet IO interface can * receive and transmit. For Ethernet, the frame length bytes start with MAC * addresses and continue to the end of the payload. So, Ethernet checksum, * interpacket gap, and preamble bytes are excluded from the lengths. * * Use odp_pktio_capability() to query interface capabilities. If setting * maximum frame length is only supported in input or output direction, the * parameter for the unsupported direction has to be set to zero. When * 'equal' flag in odp_pktio_capability_t::maxlen is set, the same maximum * frame length value has to be used for both input and output directions. * * @param pktio Packet IO handle * @param maxlen_input Maximum frame length at packet input * @param maxlen_output Maximum frame length at packet output * * @retval 0 on success * @retval <0 on failure * * @see odp_pktin_maxlen(), odp_pktout_maxlen() */ int odp_pktio_maxlen_set(odp_pktio_t pktio, uint32_t maxlen_input, uint32_t maxlen_output); /** * Get the default MAC address of a packet IO interface. * * @param pktio Packet IO handle * @param[out] mac_addr Output buffer (use ODP_PKTIO_MACADDR_MAXSIZE) * @param size Size of output buffer * * @return Number of bytes written (actual size of MAC address) * @retval <0 on failure */ int odp_pktio_mac_addr(odp_pktio_t pktio, void *mac_addr, int size); /** * Set the default MAC address of a packet IO interface. * * Support of this operation on a packet IO interface is reported * through ‘mac_addr’ set operation capability. * * @param pktio Packet IO handle * @param mac_addr MAC address to be set as default address * @param size Size of the MAC address * * @return 0 on success * @retval <0 on failure */ int odp_pktio_mac_addr_set(odp_pktio_t pktio, const void *mac_addr, int size); /** * Setup per-port default class-of-service. * * @param pktio Ingress port pktio handle. * @param default_cos Class-of-service set to all packets arriving at this * ingress port, unless overridden by subsequent * header-based filters. * * @retval 0 on success * @retval <0 on failure * * @note The default_cos has to be unique per odp_pktio_t instance. */ int odp_pktio_default_cos_set(odp_pktio_t pktio, odp_cos_t default_cos); /** * Setup per-port error class-of-service * * @param pktio Ingress port pktio handle. * @param error_cos class-of-service set to all packets arriving at this * ingress port that contain an error. * * @retval 0 on success * @retval <0 on failure * * @note Optional. */ int odp_pktio_error_cos_set(odp_pktio_t pktio, odp_cos_t error_cos); /** * Setup per-port header offset * * @param pktio Ingress port pktio handle. * @param offset Number of bytes the classifier must skip. * * This option is input to packet input parser/classifier indicating * how many bytes of data should be skipped from start of packet, * before parsing starts. So this option effects all packet input * protocol identification and other offloads. * * @retval 0 on success * @retval <0 on failure * * @note Optional. */ int odp_pktio_skip_set(odp_pktio_t pktio, uint32_t offset); /** * Specify per-port buffer headroom * * @param pktio Ingress port pktio handle. * @param headroom Number of bytes of space preceding packet data to reserve * for use as headroom. Must not exceed the implementation * defined ODP_PACKET_MAX_HEADROOM. * * @retval 0 on success * @retval <0 on failure * * @note Optional. */ int odp_pktio_headroom_set(odp_pktio_t pktio, uint32_t headroom); /** * Get pktio interface index * * @param pktio Packet I/O handle * * @return Packet interface index (0..odp_pktio_max_index()) * @retval <0 On failure (e.g., handle not valid) */ int odp_pktio_index(odp_pktio_t pktio); /** * Get printable value for an odp_pktio_t * * @param pktio odp_pktio_t handle to be printed * @return uint64_t value that can be used to print/display this * handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents * an odp_pktio_t handle. */ uint64_t odp_pktio_to_u64(odp_pktio_t pktio); /** * Initialize pktio params * * Initialize an odp_pktio_param_t to its default values for all fields * * @param param Address of the odp_pktio_param_t to be initialized */ void odp_pktio_param_init(odp_pktio_param_t *param); /** * Initialize packet input queue parameters * * Initialize an odp_pktin_queue_param_t to its default values. * * @param param Input queue parameter structure to be initialized */ void odp_pktin_queue_param_init(odp_pktin_queue_param_t *param); /** * Initialize packet output queue parameters * * Initialize an odp_pktout_queue_param_t to its default values. * * @param param Output queue parameter structure to be initialized */ void odp_pktout_queue_param_init(odp_pktout_queue_param_t *param); /** * Initialize packet IO configuration options * * Initialize an odp_pktio_config_t to its default values. * * @param config Packet IO interface configuration */ void odp_pktio_config_init(odp_pktio_config_t *config); /** * Print pktio info to the console * * Print implementation-defined pktio debug information to the console. * * @param pktio Packet IO handle */ void odp_pktio_print(odp_pktio_t pktio); /** Link status */ typedef enum odp_pktio_link_status_t { ODP_PKTIO_LINK_STATUS_UNKNOWN = -1, ODP_PKTIO_LINK_STATUS_DOWN = 0, ODP_PKTIO_LINK_STATUS_UP = 1 } odp_pktio_link_status_t; /** * Determine pktio link is up or down for a packet IO interface. * * @param pktio Packet IO handle. * * @retval ODP_PKTIO_LINK_STATUS_UP or ODP_PKTIO_LINK_STATUS_DOWN on success * @retval ODP_PKTIO_LINK_STATUS_UNKNOWN on failure */ odp_pktio_link_status_t odp_pktio_link_status(odp_pktio_t pktio); /** * Packet IO information */ typedef struct odp_pktio_info_t { /** Packet IO device name */ const char *name; /** Packet IO driver name (implementation specific) */ const char *drv_name; /** Packet pool */ odp_pool_t pool; /** Packet IO parameters */ odp_pktio_param_t param; } odp_pktio_info_t; /** * Retrieve information about a pktio * * Fills in packet IO information structure with current parameter values. * May be called any time with a valid pktio handle. The call is not * synchronized with configuration changing calls. The application should * ensure that it does not simultaneously change the configuration and retrieve * it with this call. The call is not intended for fast path use. The info * structure is written only on success. * * @param pktio Packet IO handle * @param[out] info Pointer to packet IO info struct for output * * @retval 0 on success * @retval <0 on failure */ int odp_pktio_info(odp_pktio_t pktio, odp_pktio_info_t *info); /** @name Link speed * Packet IO link speeds in Mbps * @anchor link_speed * @{ */ /** Link speed unknown */ #define ODP_PKTIO_LINK_SPEED_UNKNOWN 0 /** Link speed 10 Mbit/s */ #define ODP_PKTIO_LINK_SPEED_10M 10 /** Link speed 100 Mbit/s */ #define ODP_PKTIO_LINK_SPEED_100M 100 /** Link speed 1 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_1G 1000 /** Link speed 2.5 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_2_5G 2500 /** Link speed 5 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_5G 5000 /** Link speed 10 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_10G 10000 /** Link speed 20 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_20G 20000 /** Link speed 25 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_25G 25000 /** Link speed 40 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_40G 40000 /** Link speed 50 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_50G 50000 /** Link speed 56 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_56G 56000 /** Link speed 100 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_100G 100000 /** Link speed 200 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_200G 200000 /** Link speed 400 Gbit/s */ #define ODP_PKTIO_LINK_SPEED_400G 400000 /** @} */ /** Autonegotiation mode */ typedef enum odp_pktio_link_autoneg_t { /** Autonegotiation state unknown */ ODP_PKTIO_LINK_AUTONEG_UNKNOWN = -1, /** Autonegotiation disabled */ ODP_PKTIO_LINK_AUTONEG_OFF = 0, /** Autonegotiation enabled */ ODP_PKTIO_LINK_AUTONEG_ON = 1 } odp_pktio_link_autoneg_t; /** Duplex mode */ typedef enum odp_pktio_link_duplex_t { ODP_PKTIO_LINK_DUPLEX_UNKNOWN = -1, ODP_PKTIO_LINK_DUPLEX_HALF = 0, ODP_PKTIO_LINK_DUPLEX_FULL = 1 } odp_pktio_link_duplex_t; /** Ethernet pause frame (flow control) mode */ typedef enum odp_pktio_link_pause_t { ODP_PKTIO_LINK_PAUSE_UNKNOWN = -1, ODP_PKTIO_LINK_PAUSE_OFF = 0, ODP_PKTIO_LINK_PAUSE_ON = 1 } odp_pktio_link_pause_t; /** * Packet IO link information */ typedef struct odp_pktio_link_info_t { /** Link autonegotiation */ odp_pktio_link_autoneg_t autoneg; /** Duplex mode */ odp_pktio_link_duplex_t duplex; /** Link media type * * The implementation owned string describes link media type. Values are * implementation specific short names like copper, fiber, or virtual. * The value of "unknown" is used when media type cannot be determined. */ const char *media; /** Reception of pause frames */ odp_pktio_link_pause_t pause_rx; /** Transmission of pause frames */ odp_pktio_link_pause_t pause_tx; /** Link speed in Mbps * * The value of zero means that the link speed is unknown. * ODP_PKTIO_LINK_SPEED_* (@ref link_speed) defines can be used to * compare the value to standard link speeds. */ uint32_t speed; /** Link status */ odp_pktio_link_status_t status; } odp_pktio_link_info_t; /** * Retrieve information about packet IO link status * * Fills in link information structure with the current link status values. * May be called any time with a valid pktio handle. The call is not intended * for fast path use. The info structure is written only on success. * * @param pktio Packet IO handle * @param[out] info Pointer to packet IO link info struct for output * * @retval 0 on success * @retval <0 on failure */ int odp_pktio_link_info(odp_pktio_t pktio, odp_pktio_link_info_t *info); /** * Packet input timestamp resolution in hertz * * @deprecated Use odp_pktio_ts_res() instead, which returns resolution for * both packet input and output timestamps. * * This is the resolution of packet input timestamps. Returns zero on a failure * or when timestamping is disabled. * * @param pktio Packet IO handle * * @return Packet input timestamp resolution in hertz * @retval 0 on failure */ uint64_t ODP_DEPRECATE(odp_pktin_ts_res)(odp_pktio_t pktio); /** * Convert nanoseconds to packet input time * * @deprecated Use odp_pktio_ts_from_ns() instead, which can be used with both * packet input and output timestamps. * * Packet input time source is used for timestamping incoming packets. * This function is used convert nanosecond time to packet input timestamp time. * * @param pktio Packet IO handle * @param ns Time in nanoseconds * * @return Packet input timestamp */ odp_time_t ODP_DEPRECATE(odp_pktin_ts_from_ns)(odp_pktio_t pktio, uint64_t ns); /** * Packet IO timestamp resolution in hertz * * This is the resolution of packet input and output timestamps using a packet * IO time source. * * @param pktio Packet IO handle * * @return Packet IO timestamp resolution in hertz * @retval 0 on failure */ uint64_t odp_pktio_ts_res(odp_pktio_t pktio); /** * Convert nanoseconds to packet IO time * * Packet IO time source is used for timestamping incoming and outgoing packets. * This function is used to convert nanosecond time to packet input or output * timestamp time. * * @param pktio Packet IO handle * @param ns Time in nanoseconds * * @return Packet IO timestamp * @retval ODP_TIME_NULL on failure */ odp_time_t odp_pktio_ts_from_ns(odp_pktio_t pktio, uint64_t ns); /** * Current packet IO time and global time * * Returns current packet IO time and optionally global time. The returned * global time is that of global time source, where as the packet IO time is of * packet IO time source that is used to timestamp incoming and outgoing * packets. * * @param pktio Packet IO handle * @param[out] ts_global Pointer to odp_time_t for output or NULL. * On success, global timestamp will be taken at the * same point of time as packet IO time. * * @return Current packet IO time * @retval ODP_TIME_NULL on failure */ odp_time_t odp_pktio_time(odp_pktio_t pktio, odp_time_t *ts_global); /** * Read last captured Tx timestamp of a packet if available and clear it for * next timestamp. * * @param pktio Packet IO handle * @param[out] ts Pointer to odp_time_t for output * * @retval 0 on success * @retval >0 Timestamp not available either because none has been requested or * the requested timestamp is not yet available. In case it is the * latter, then retry again later for retrieving the timestamp. * @retval <0 on failure */ int odp_pktout_ts_read(odp_pktio_t pktio, odp_time_t *ts); /** * @} */ #ifdef __cplusplus } #endif #include #endif