diff options
Diffstat (limited to 'include/odp/api/spec/packet_io.h')
| -rw-r--r-- | include/odp/api/spec/packet_io.h | 784 |
1 files changed, 287 insertions, 497 deletions
diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h index cec1f22af..a83617f7c 100644 --- a/include/odp/api/spec/packet_io.h +++ b/include/odp/api/spec/packet_io.h @@ -1,34 +1,36 @@ -/* Copyright (c) 2013, Linaro Limited - * All rights reserved. - * - * SPDX-License-Identifier: BSD-3-Clause +/* SPDX-License-Identifier: BSD-3-Clause + * Copyright (c) 2013-2018 Linaro Limited + * Copyright (c) 2020-2023 Nokia */ - /** * @file * * ODP Packet IO */ -#ifndef ODP_API_PACKET_IO_H_ -#define ODP_API_PACKET_IO_H_ +#ifndef ODP_API_SPEC_PACKET_IO_H_ +#define ODP_API_SPEC_PACKET_IO_H_ #include <odp/visibility_begin.h> #ifdef __cplusplus extern "C" { #endif +#include <odp/api/classification.h> +#include <odp/api/packet_types.h> #include <odp/api/packet_io_stats.h> -#include <odp/api/queue.h> -#include <odp/api/time.h> +#include <odp/api/packet_io_types.h> +#include <odp/api/queue_types.h> +#include <odp/api/reassembly.h> +#include <odp/api/time_types.h> -/** @defgroup odp_packet_io ODP PACKET IO - * Operations on a packet Input/Output interface. +/** @addtogroup 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 - * the mtu, mac etc. + * 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 @@ -40,425 +42,12 @@ extern "C" { */ /** - * @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 - */ - -/** - * @def ODP_PKTIO_INVALID - * Invalid packet IO 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 - */ - -/** - * @def ODP_PKTIN_WAIT - * Wait infinitely 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 - */ -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 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; - -} 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 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 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()) 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. - */ -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. When it is enabled, - * implementation will calculate and insert checksum into every outgoing packet - * by default. Application may use a packet metadata flag to disable checksum - * insertion per packet bases. For correct operation, packet metadata must - * provide valid offsets for the appropriate protocols. For example, UDP - * checksum calculation needs both L3 and L4 offsets (to access IP and UDP - * headers). When application (e.g. a switch) does not modify L3/L4 data and - * thus checksum does not need to be updated, output checksum insertion should - * be disabled for optimal performance. - */ -typedef union odp_pktout_config_opt_t { - /** Option flags */ - struct { - /** Insert IPv4 header checksum on packet output */ - uint64_t ipv4_chksum : 1; - - /** Insert UDP checksum on packet output */ - uint64_t udp_chksum : 1; - - /** Insert TCP checksum on packet output */ - uint64_t tcp_chksum : 1; - - /** Insert SCTP checksum on packet output */ - uint64_t sctp_chksum : 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 - */ -typedef enum odp_pktio_parser_layer_t { - /** No layers */ - ODP_PKTIO_PARSER_LAYER_NONE = 0, - - /** Layer L2 protocols (Ethernet, VLAN, ARP, etc) */ - ODP_PKTIO_PARSER_LAYER_L2, - - /** Layer L3 protocols (IPv4, IPv6, ICMP, IPsec, etc) */ - ODP_PKTIO_PARSER_LAYER_L3, - - /** Layer L4 protocols (UDP, TCP, SCTP) */ - ODP_PKTIO_PARSER_LAYER_L4, - - /** All layers */ - ODP_PKTIO_PARSER_LAYER_ALL - -} odp_pktio_parser_layer_t; - -/** - * Parser configuration - */ -typedef struct odp_pktio_parser_config_t { - /** Protocol parsing level in packet input - * - * Parse protocol layers in minimum up to this level during packet - * input. The default value is ODP_PKTIO_PARSER_LAYER_ALL. */ - odp_pktio_parser_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. */ - odp_bool_t enable_loop; - -} 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; - } 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; - -/** - * Packet IO capabilities - */ -typedef struct odp_pktio_capability_t { - /** Maximum number of input queues */ - unsigned max_input_queues; - - /** Maximum number of output queues */ - unsigned 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; - - /** Support of Loopback mode - * - * A boolean to denote whether loop back mode is supported on this - * specific interface. */ - odp_bool_t loop_supported; -} 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. + * to open an already open device will fail, returning ODP_PKTIO_INVALID. 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. @@ -473,6 +62,12 @@ typedef struct odp_pktio_capability_t { * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, * odp_pktout_queue_config() call is optional and will ignore all parameters. * + * Advanced packet IO interface offload features and options can be setup with + * odp_pktio_config() before the interface is started. These features include e.g. + * checksum, segmentation (LSO), reassembly and inline IPSEC offloads. When + * odp_pktio_config() is not used, the interface is started with the default + * values of odp_pktio_config_t. + * * 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 @@ -482,6 +77,7 @@ typedef struct odp_pktio_capability_t { * * odp_pktio_open() * * odp_pktin_queue_config() * * odp_pktout_queue_config() + * * [optionally] odp_pktio_config() * * odp_pktio_start() * * ... and tear down sequence is: @@ -505,7 +101,7 @@ typedef struct odp_pktio_capability_t { * 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. + * more specific CoS that specifies another pool. * * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() */ @@ -530,10 +126,11 @@ int odp_pktio_capability(odp_pktio_t pktio, odp_pktio_capability_t *capa); * * Return the maximum packet IO interface index. Interface indexes * (e.g. returned by odp_pktio_index()) range from zero to this maximum value. + * The return value does not exceed #ODP_PKTIO_MAX_INDEX. * * @return Maximum packet IO interface index */ -unsigned odp_pktio_max_index(void); +unsigned int odp_pktio_max_index(void); /** * Configure packet IO interface options @@ -616,8 +213,10 @@ int odp_pktout_queue_config(odp_pktio_t pktio, * output. If return value (N) is less than 'num', only queues[0 ... N-1] have * been written. * - * Packets (and other events) from these queues are received with - * odp_queue_deq(), odp_schedule(), etc calls. + * 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 @@ -659,7 +258,7 @@ int odp_pktin_queue(odp_pktio_t pktio, odp_pktin_queue_t queues[], int num); * * 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. + * 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 @@ -784,7 +383,6 @@ int odp_pktin_recv(odp_pktin_queue_t queue, odp_packet_t packets[], int num); * @param num Maximum number of packets to receive * @param wait Wait time specified as as follows: * * ODP_PKTIN_NO_WAIT: Do not wait - * * ODP_PKTIN_WAIT: Wait infinitely * * 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 @@ -823,7 +421,6 @@ int odp_pktin_recv_tmo(odp_pktin_queue_t queue, odp_packet_t packets[], * @param num Maximum number of packets to receive * @param wait Wait time specified as as follows: * * ODP_PKTIN_NO_WAIT: Do not wait - * * ODP_PKTIN_WAIT: Wait infinitely * * 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 @@ -832,9 +429,8 @@ int odp_pktin_recv_tmo(odp_pktin_queue_t queue, odp_packet_t packets[], * @return Number of packets received * @retval <0 on failure */ -int odp_pktin_recv_mq_tmo(const odp_pktin_queue_t queues[], unsigned num_q, - unsigned *from, odp_packet_t packets[], int num, - uint64_t wait); +int odp_pktin_recv_mq_tmo(const odp_pktin_queue_t queues[], uint32_t num_q, uint32_t *from, + odp_packet_t packets[], int num, uint64_t wait); /** * Packet input wait time @@ -855,35 +451,115 @@ 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 + * 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 + * @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[], int num); /** - * Return the currently configured MTU value of a packet IO interface. + * Initialize LSO profile parameters * - * @param[in] pktio Packet IO handle. + * Initialize an odp_lso_profile_param_t to its default values for all fields. * - * @return MTU value on success - * @retval 0 on failure + * @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 */ -uint32_t odp_pktio_mtu(odp_pktio_t pktio); +odp_lso_profile_t odp_lso_profile_create(odp_pktio_t pktio, const odp_lso_profile_param_t *param); /** - * Enable/Disable promiscuous mode on a packet IO interface. + * Destroy LSO profile + * + * LSO profiles can be destroyed only when the packet IO interface is not active (i.e. after it + * has been stopped). * - * @param[in] pktio Packet IO handle. - * @param[in] enable 1 to enable, 0 to disable. + * @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. + * + * Packets with less than (or equal to) 'max_payload_len' payload bytes can be sent also, however + * odp_pktout_send() should be more optimal for those than this function. + * + * 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); + +/** + * Set promiscuous mode + * + * Enable or disable promiscuous mode on a packet IO interface. Use packet IO capability + * odp_pktio_set_op_t::promisc_mode to check if an interface supports this operation. + * When the operation is supported, promiscuous mode is disabled by default. + * + * @param pktio Packet IO handle. + * @param enable 1 to enable, 0 to disable. * * @retval 0 on success * @retval <0 on failure @@ -893,7 +569,7 @@ 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[in] pktio Packet IO handle. + * @param pktio Packet IO handle. * * @retval 1 if promiscuous mode is enabled. * @retval 0 if promiscuous mode is disabled. @@ -902,6 +578,62 @@ int odp_pktio_promisc_mode_set(odp_pktio_t pktio, odp_bool_t enable); 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 @@ -914,16 +646,31 @@ int odp_pktio_promisc_mode(odp_pktio_t pktio); 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[in] pktio Ingress port pktio handle. - * @param[in] default_cos Class-of-service set to all packets arriving - * at this ingress port, - * unless overridden by subsequent - * header-based filters. + * @param pktio Ingress port pktio handle. + * @param default_cos Class-of-service set to all packets arriving at this + * ingress port. Use ODP_COS_INVALID to remove the default + * CoS. * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure * * @note The default_cos has to be unique per odp_pktio_t instance. */ @@ -932,12 +679,12 @@ int odp_pktio_default_cos_set(odp_pktio_t pktio, odp_cos_t default_cos); /** * Setup per-port error class-of-service * - * @param[in] pktio Ingress port pktio handle. - * @param[in] error_cos class-of-service set to all packets arriving - * at this ingress port that contain an error. + * @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 + * @retval 0 on success + * @retval <0 on failure * * @note Optional. */ @@ -946,24 +693,28 @@ int odp_pktio_error_cos_set(odp_pktio_t pktio, odp_cos_t error_cos); /** * Setup per-port header offset * - * @param[in] pktio Ingress port pktio handle. - * @param[in] offset Number of bytes the classifier must skip. + * @param pktio Ingress port pktio handle. + * @param offset Number of bytes the classifier must skip. * - * @retval 0 on success - * @retval <0 on failure - * @note Optional. + * 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[in] pktio Ingress port pktio handle. - * @param[in] 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. + * @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 @@ -1045,21 +796,10 @@ void odp_pktio_print(odp_pktio_t pktio); * * @param pktio Packet IO handle. * - * @retval 1 link is up - * @retval 0 link is down - * @retval <0 on failure + * @retval ODP_PKTIO_LINK_STATUS_UP or ODP_PKTIO_LINK_STATUS_DOWN on success + * @retval ODP_PKTIO_LINK_STATUS_UNKNOWN on failure */ -int odp_pktio_link_status(odp_pktio_t pktio); - -/** - * Packet IO information - */ -typedef struct odp_pktio_info_t { - const char *name; /**< Packet IO device name */ - const char *drv_name; /**< Packet IO driver name (implementation specific) */ - odp_pool_t pool; /**< Packet pool */ - odp_pktio_param_t param; /**< Packet IO parameters */ -} odp_pktio_info_t; +odp_pktio_link_status_t odp_pktio_link_status(odp_pktio_t pktio); /** * Retrieve information about a pktio @@ -1080,30 +820,80 @@ typedef struct odp_pktio_info_t { int odp_pktio_info(odp_pktio_t pktio, odp_pktio_info_t *info); /** - * Packet input timestamp resolution in hertz + * 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 IO timestamp resolution in hertz * - * This is the resolution of packet input timestamps. Returns zero on a failure - * or when timestamping is disabled. + * This is the resolution of packet input and output timestamps using a packet + * IO time source. * * @param pktio Packet IO handle * - * @return Packet input timestamp resolution in hertz + * @return Packet IO timestamp resolution in hertz * @retval 0 on failure */ -uint64_t odp_pktin_ts_res(odp_pktio_t pktio); +uint64_t odp_pktio_ts_res(odp_pktio_t pktio); /** - * Convert nanoseconds to packet input time + * Convert nanoseconds to packet IO time * - * Packet input time source is used for timestamping incoming packets. - * This function is used convert nanosecond time to packet input timestamp 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 input timestamp + * @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 */ -odp_time_t odp_pktin_ts_from_ns(odp_pktio_t pktio, uint64_t ns); +int odp_pktout_ts_read(odp_pktio_t pktio, odp_time_t *ts); /** * @} |