On 2014-08-19 15:22, Bill Fischofer wrote: > During review Mike noted that Doxygen seems somewhat wonky from one version > to the next. The one I've been using is 1.8.4 and that seems to work fine. > Mike had some problems with 1.8.6 but managed to resolve them. What > version are you using? Perhaps Mike can shed some additional light here.
I've tried 1.8.4, 1.8.6 and 1.8.7 and with all of them the image are to big... =( Cheers, Anders > > Bill > > > On Tue, Aug 19, 2014 at 3:16 PM, Anders Roxell <[email protected]> > wrote: > > > On 2014-08-18 19:06, Bill Fischofer wrote: > > > Sorry for the delay. Catching up with e-mail. > > > > > > 1. Adding ODP_PMR_LEN was the reason for the v5 patch, so I don't > > > understand this comment. > > > > That comment should not go in to the commit message, you can add it > > below the "---" > > > > > > > > 2. You can delete the stray v1.0 or I can rev this to v6 as you prefer. > > > Please advise. > > > > > > 3. I'm not sure what the problem is. It's just a clarifying remark > > that's > > > part of the original. > > > > OK, fine. > > > > > > > > 4. Not sure why you're not seeing the images. They were working for Mike > > > and I. > > > > http://people.linaro.org/~anders.roxell/OpenDataPlane-Architecture.pdf > > > > Different versions? > > > > > > > > 5. As with Crypto, the design approval means we're ready to begin > > > implementation, not that every detail has been nailed down. The "TBD" is > > > from the original. > > > > OK. > > > > Cheers, > > Anders > > > > > > > > Bill > > > > > > > > > On Tue, Aug 12, 2014 at 9:26 AM, Anders Roxell <[email protected] > > > > > > wrote: > > > > > > > On 2014-08-06 08:41, Bill Fischofer wrote: > > > > > Add ODP_PMR_LEN term to odp_pmr_term_e enum > > > > > > > > Is this needed? > > > > > > > > > > > > > > Signed-off-by: Bill Fischofer <[email protected]> > > > > > --- > > > > > classification_design.dox | 900 ++ > > > > > images/classification_flow.eps | 33518 > > > > +++++++++++++++++++++++++++++++++++++++ > > > > > images/classification_flow.png | Bin 0 -> 35193 bytes > > > > > 3 files changed, 34418 insertions(+) > > > > > create mode 100644 classification_design.dox > > > > > create mode 100644 images/classification_flow.eps > > > > > create mode 100644 images/classification_flow.png > > > > > > > > > > diff --git a/classification_design.dox b/classification_design.dox > > > > > new file mode 100644 > > > > > index 0000000..bf0209e > > > > > --- /dev/null > > > > > +++ b/classification_design.dox > > > > > @@ -0,0 +1,900 @@ > > > > > +/* Copyright (c) 2014, Linaro Limited > > > > > + * All rights reserved > > > > > + * > > > > > + * SPDX-License-Identifier: BSD-3-Clause > > > > > + */ > > > > > + > > > > > +/*! > > > > > +@page classification_design ODP Design - Classification API > > > > > +For the implementation of the ODP classification API please see @ref > > > > odp_classify.h > > > > > + > > > > > +@tableofcontents > > > > > + > > > > > +@section introduction Introduction > > > > > +This document defines the Classification APIs supported by ODP v1.0. > > > > > > > > Remove v1.0 > > > > > > > > > +Classification is logically composed of two stages: Parsing and Rule > > > > Matching. > > > > > +Parsing takes a raw packet and validates its structure and > > identifies > > > > fields of interest in the various headers that comprise the layers of > > the > > > > packet. > > > > > +Rule Matching, in turn, takes the result of parsing and sorts > > packets > > > > into Classes of Service (CoS) based on application-defined rule sets. > > > > > +@subsection use_of_terms Use of Terms > > > > > +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", > > > > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this > > > > document are to be interpreted as described in [RFC 2119]( > > > > https://tools.ietf.org/html/rfc21199). > > > > > +@subsection purpose Purpose > > > > > +ODP is a framework for software-based packet forwarding/filtering > > > > applications, and the purpose of the Packet Classifier API is to enable > > > > applications to program the platform hardware or software > > implementation to > > > > assist in prioritization, classification and scheduling of each > > packet, so > > > > that the software application can run faster, scale better and adhere > > to > > > > QoS requirements. > > > > > +The following API abstraction are not modelled after any existing > > > > product implementation, but is instead defined in terms of what a > > typical > > > > data-plane application may require from such a platform, without > > > > sacrificing simplicity and avoiding ambiguity. > > > > > +Certain terms that are being used within the context of existing > > > > products in relation to packet parsing and classification, such as > > “access > > > > lists” are avoided such that not to suggest any relationship between > > the > > > > abstraction used within this API and any particular manner in which > > they > > > > may be implemented in hardware. > > > > > +These are the key ODP objects that the parser needs to employ, that > > are > > > > presently defined in ODP: > > > > > +@subsubsection odp_pktio odp_pktio > > > > > +odp_pktio specifies an individual packet I/O channel instance. > > > > > +In other words, it would translate to a physical interface or a > > logical > > > > port, or in the case of channelized protocols (e.g., [Interlaken]( > > > > > > https://www.google.com/url?q=https%3A%2F%2Fwww.cortina-systems.com%2Fimages%2Fdocuments%2F400023_Interlaken_Technology_White_Paper.pdf&sa=D&sntz=1&usg=AFQjCNEBdJTBmA1XaNGY3pmumQTfgSi1oA > > )) > > > > it would map to a logical channel on that interface. > > > > > +Since the classifier API deals exclusively with ingress, this object > > > > represents the source of packets into the classifier. > > > > > +In order to support any non-trivial use case, the classifier API > > needs > > > > to be able to assign multiple odp_queue instances for any single > > odp_pktio > > > > object, and may also assign any odp_queue instance to more than one > > > > odp_pktio object. > > > > > +@subsubsection odp_queue odp_queue > > > > > +odp_queue specifies a logical queue for packets, and in the case of > > > > ingress, this would represent a stream of packets which share several > > > > attributes, that are delivered to the ODP application for processing. > > > > > +The per-queue attributes currently defined are: queue type, sync > > > > (ordering); priority; and schedule group (set of processor cores). > > > > > +@subsubsection odp_buffer_pool odp_buffer_pool > > > > > +odp_buffer_pool specifies a collection of buffers of same size and > > > > alignment, as well as a set of policies such as flow control and > > processor > > > > affinity. > > > > > +The classifier API refers to such pools that are designated for > > storing > > > > ingress packets. > > > > > +@section functional_description Functional Description > > > > > +Following is the functionality that is required of the classifier > > API, > > > > and its underlying implementation. > > > > > +The details and order of the following paragraph is informative, > > and is > > > > only intended to help convey the functional scope of a classifier and > > > > provide context for the API. > > > > > +In reality, implementations may execute many of these steps > > > > concurrently, or in different order while maintaining the evident > > > > dependencies: > > > > > + > > > > > +-# Apply a set of \e classification \e rules to the header of an > > > > incoming packet, identify the header fields, e.g., \e ethertype, IP > > > > version, IP protocol, transport layer port numbers, IP DiffServ, VLAN > > id, > > > > 802.1p priority. > > > > > + > > > > > +-# Store these fields as packet meta data for application use, and > > for > > > > the remainder of parser operations. > > > > > +The \e odp_pktio is also stored as one of the meta data fields for > > > > subsequent use. > > > > > + > > > > > +-# Compute an \e odp_cos (Class of Service) value from a subset of > > > > supported fields from 1) above. > > > > > > > > Remove (Class of Service)? > > > > > > > > this has been covered above right? > > > > > > > > > + > > > > > + > > > > > +-# Based on the \e odp_cos from 3) above, select the \e odp_queue > > > > through which the packet is delivered to the application. > > > > > + > > > > > +-# Validate the packet data integrity (checksums, FCS) and > > correctness > > > > (e.g., length fields) and store the validation result, along with > > optional > > > > error layer and type indicator, in packet meta data. > > > > > +Optionally, if a packet fails validation, override the \e odp_cos > > > > selection in step 3 to a class of service designated for errored > > packets. > > > > > + > > > > > +-# Since the selected \e odp_queue may require preservation of > > packet > > > > order, i.e., SYNC_ATOMIC or SYNC_ORDERED, optionally select the packet > > > > header fields from which the parser calculates a \e odp_flow_signature, > > > > which may be a unique flow identifier or a hash, such that the packets > > > > which are assigned the same \e odp_flow_signature are scheduled in the > > same > > > > order they are received. > > > > > + > > > > > +-# Based on the \e odp_cos from 3) above, select the \e > > odp_buffer_pool > > > > that should be used to acquire a buffer to store the packet data and > > meta > > > > data. > > > > > + > > > > > +-# Allocate a buffer from \e odp_buffer_pool selected in 6) above > > and > > > > logically store the packet data and meta data to the allocated buffer, > > or > > > > in accordance with class-of-service drop policy and subject to pool > > buffer > > > > availability, optionally discard the packet. > > > > > + > > > > > +-# Enqueue the buffer into the \e odp_queue selected in 4) above. > > > > > + > > > > > +The above is an abstract description of the classifier > > functionality, > > > > and may be applied to a variety of applications in many different ways. > > > > > +The ultimate meaning of how this functionality applies to an > > > > application also depends on other ODP modules, so the above may not > > > > complete a full depiction. > > > > > +For instance, the exact meaning of \e priority, which is a per-queue > > > > attribute is influenced by the ODP scheduler semantics, and the system > > > > behavior under stress depends on the ODP buffer pool module behavior. > > > > > + > > > > > +For the sole purpose of illustrating the above abstract > > functionality, > > > > here is an example of a Layer-2 (IEEE 802.1D) bridge application: > > > > > +Such a forwarding application that also adheres to IEEE 802.1p/q > > > > priority, which has 8 traffic priority levels, might create 8 \e > > > > odp_buffer_pool instances, one for each PCP priority level, and 8 \e > > > > odp_queue instances one per priority level. > > > > > +Incoming packets will be inspected for a VLAN header; the PCP field > > > > will be extracted, and used to select both the pool and the queue. > > > > > +Because each queue will be assigned a priority value, the packets > > with > > > > highest PCP values will be scheduled before any packet with a lower PCP > > > > value. > > > > > +Also, in a case of congestion, buffer pools for lower priority > > packets > > > > will be depleted earlier than the pools containing packets of the high > > > > priority, and hence the lower priority packets will be dropped > > (assuming > > > > that is the only flow control method that is supported in the platform) > > > > while higher priority packets will continue to be received into > > buffers and > > > > processed. > > > > > +@subsection flow_diagram Classification Processing Flow Diagram > > > > > +@image html classification_flow.png "Figure 1: Classification Flow > > > > Diagram" > > > > > +@image latex classification_flow.eps "Figure 1: Classification Flow > > > > Diagram" > > > > > > > > I can't see the full image when I open the pdf > > > > > > > > > + > > > > > +@section api_elements API Elements > > > > > +While the above description refers to the abstracted packet > > classifier, > > > > the following is the description of the API designed to program the > > packet > > > > classifier, and is intended to add clarity to the functions provided > > > > further below. > > > > > +@subsection cos_creation Class of Service Creation and Binding > > > > > +To program the classifier, a class-of-service instance must be > > created, > > > > which will contain the packet filtering resources that it may require. > > > > > +All subsequent calls refer to one or more of these resources. > > > > > +Each class of service instance must be associated with a single > > queue > > > > or queue group, which will be the destination of all packets matching > > that > > > > particular filter. > > > > > +The queue assignment is implemented as a separate function call such > > > > that the queue may be modified at any time, without tearing down the > > > > filters that define the class of service. > > > > > +In other words, it is possible to change the destination queue for a > > > > class of service defined by its filters quickly and dynamically. > > > > > +Optionally, on platforms that support multiple packet buffer pools, > > > > each class of service may be assigned a different pool such that when > > > > buffers are exhausted for one class of service, other classes are not > > > > negatively impacted and continue to be processed. > > > > > + > > > > > +@subsection default_packet_handling Default packet handling > > > > > +There SHOULD be one \b odp_cos assigned to each port with the \c > > > > odp_cos_pktio_set() function, which will function as the default > > > > class-of-service for all packets received from an ingress port, that > > do not > > > > match any of the filters defined subsequently. > > > > > +At minimum this default class-of-service MUST have a queue and a > > buffer > > > > pool assigned to it on platforms that support multiple packet buffer > > pools. > > > > > +Multiple odp_pktio instances (i.e., multiple ports) MAY each have > > their > > > > own default odp_cos, or MAY share a odp_cos with other ports, based on > > > > application requirements. > > > > > + > > > > > +@subsection packet_classification Packet Classification > > > > > +For each odp_pktio port, the API allows the assignment of a > > > > class-of-service to a packet using one of three methods: > > > > > + > > > > > +-# The packet may be assigned a specific class-of-service based on > > its > > > > Layer-2 (802.1P/902.1Q VLAN tag) priority field. > > > > > +Since the standard field defines 8 discrete priority levels, the API > > > > allows to assign an odp_cos to each of these priority levels with the > > \c > > > > odp_cos_with_l2_priority() function. > > > > > + > > > > > +-# Similarly, a class-of-service may be assigned using the Layer-3 > > (IP > > > > DiffServ) header field. > > > > > +The application supplies an array of \e odp_cos values that covers > > the > > > > entire range of the standard protocol header field, where array > > elements do > > > > not need to contain unique values. > > > > > +There is also a need to specify if Layer-3 priority takes precedence > > > > over Layer-2 priority in a packet with both headers present. > > > > > + > > > > > +-# Additionally, the application may also program a number of \e > > > > pattern \e matching \e rules that assign a class-of-service for packets > > > > with header fields matching specified values. > > > > > +The field-matching rules take precedence over the previously > > described > > > > priority-based assignment of a class-of-service. > > > > > +Using these matching rules the application should be able for > > example > > > > to identify all packets containing VoIP traffic based on the protocol > > being > > > > UDP, and a specific destination or source port numbers, and > > appropriately > > > > assign these packets an class-of-service that maps to a higher priority > > > > queue, assuring voice packets a lower and bound latency. > > > > > + > > > > > +@subsection scaling_and_flow Scaling and Flow Discrimination > > > > > +In addition to classifying packets and routing them to those queues > > > > with the appropriate priority, and optionally limiting their memory > > > > consumption by designating certain classes of packets to specific > > buffer > > > > pools, the classifier API also facilitates the scaling of data-plane > > > > application on multi-core systems by creating a mechanism to define > > which > > > > packet headers need to be combined to result in a value representing a > > > > specific packet flow. > > > > > +The classifier generates a signature, which can be a checksum or > > hash > > > > of arbitrary strength that covers those packet header fields that are > > > > identified by the application as identifying flows. > > > > > + > > > > > +The \e flow \e signatures that result from hashing are then stored > > with > > > > the packet meta data (along with its class-of-service and its ingress > > \e > > > > odp_pktio port), and subsequently may be utilized by the > > implementation of > > > > a scheduler queue to maintain the order of packets with the same flow > > > > signature, while allowing packets with different signatures to be > > processed > > > > concurrently and independently on different processing cores. > > > > > + > > > > > +@subsection packet_meta_data Packet meta data Elements > > > > > +Here are the specific information elements that SHOULD be stored > > within > > > > the packet meta data structure: > > > > > +- Protocol fields that are decoded and extracted by the parsing > > phase > > > > > +- Flow-signature calculated from a prescribed collection of protocol > > > > fields > > > > > +- The class-of-service identifier that is selected for the packet > > > > > +- The ingress port identifier > > > > > +- The result of packet validation, including an indication of the > > type > > > > of error detected, if any > > > > > + > > > > > +The ODP packet API module SHALL provide accessors for retrieving the > > > > above meta data fields from the container buffer in an > > > > implementation-independent manner. > > > > > + > > > > > +@section api_definitions API Definitions > > > > > +@subsection data_types Data Types > > > > > +The following data types are referenced in the API descriptions > > > > described below. > > > > > +The names are part of the ODP API and MUST be present in any > > conforming > > > > implementation, however the type values shown here are illustrative and > > > > implementations SHOULD either use these or substitute their own type > > values > > > > that are appropriate to the underlying platform. > > > > > + > > > > > +@verbatim > > > > > +/** > > > > > + * 'odp_pktio_t' value to indicate any port > > > > > + */ > > > > > +#define ODP_PKTIO_ANY ((odp_pktio_t)~0) > > > > > + > > > > > + > > > > > +/** > > > > > + * 'odp_pktio_t' value to indicate an error > > > > > + */ > > > > > +#define ODP_PKTIO_INVALID ((odp_pktio_t)0) > > > > > + > > > > > + > > > > > +/** > > > > > + * Class of service instance type > > > > > + */ > > > > > +typedef uint32_t odp_cos_t; > > > > > + > > > > > + > > > > > +/** > > > > > + * flow signature type, only used for packet meta data field. > > > > > + */ > > > > > +typedef uint32_t odp_flowsig_t; > > > > > + > > > > > + > > > > > +/** > > > > > + * This value is returned from odp_cos_create() on failure, > > > > > + * May also be used as a “sink” class of service that > > > > > + * results in packets being discarded. > > > > > + */ > > > > > +#define ODP_COS_INVALID ((odp_cos_t)~0) > > > > > +@endverbatim > > > > > + > > > > > +@subsection cos_routines Class of Service Routines > > > > > +Conforming ODP implementations MUST provide the following > > > > Classification APIs: > > > > > +@subsubsection cos_create odp_cos_create > > > > > +@verbatim > > > > > +/** > > > > > + * Create a class-of-service > > > > > + * > > > > > + * @param name is a string intended for debugging purposes. > > > > > + * > > > > > + * @return Class of service instance identifier, > > > > > + * or ODP_COS_INVALID on error. > > > > > + */ > > > > > + > > > > > +odp_cos_t odp_cos_create(const char *name); > > > > > +@endverbatim > > > > > + > > > > > +This routine is used to create a class of service that can be the > > > > target of classifier rules. > > > > > +The number of such classes supported is implementation-defined. > > > > > +Attempts to create more than are supported by the implementation > > will > > > > result in an \c ODP_COS_INVALID return and errno being set to \c > > > > ODP_IMPLEMENTATION_LIMIT. > > > > > + > > > > > +@subsubsection cos_destroy odp_cos_destroy > > > > > +@verbatim > > > > > +/** > > > > > + * Discard a class-of-service along with all its associated > > resources > > > > > + * > > > > > + * @param cos_id class-of-service instance. > > > > > + * > > > > > + * @return 0 on success, -1 on error. > > > > > + */ > > > > > + > > > > > +int odp_cos_destroy(odp_cos_t cos_id); > > > > > +@endverbatim > > > > > + > > > > > +This routine is the bracketing routine for odp_cos_create(). > > > > > +It is used to destroy an existing CoS. > > > > > +It is the caller’s responsibility to ensure that no active pattern > > > > matching rules refer to the CoS prior to calling this routine. > > > > > +Results are unpredictable if this restriction is not met. > > > > > +@subsubsection cos_set_queue odp_cos_set_queue > > > > > +@verbatim > > > > > +/** > > > > > + * Assign a queue for a class-of-service > > > > > + * > > > > > + * @param cos_id class-of-service instance. > > > > > + * > > > > > + * @param queue_id is the identifier of a queue where all > > > > packets > > > > > + * of this specific class of service will be > > enqueued. > > > > > + * > > > > > + * @return 0 on success, negative error code on failure. > > > > > + */ > > > > > + > > > > > +int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); > > > > > +@endverbatim > > > > > + > > > > > +This routine associates a target queue with a CoS such that all > > packets > > > > assigned to this CoS will be enqueued to the specified queue_id at the > > end > > > > of classification processing. > > > > > +@subsubsection cos_set_queue_group odp_cos_set_queue_group > > > > > +@verbatim > > > > > +/** > > > > > + * Assign a homogenous queue-group to a class-of-service. > > > > > + * > > > > > + * @param cos_id identifier of class-of-service instance > > > > > + * @param queue_group_id identifier of the queue group to receive > > > > packets > > > > > + * associated with this class of service. > > > > > + * > > > > > + * @return 0 on success, negative error code on > > failure. > > > > > + */ > > > > > + > > > > > +int odp_cos_set_queue_group(odp_cos_t cos_id, odp_queue_group_t > > > > queue_group_id); > > > > > +@endverbatim > > > > > + > > > > > +This routine associates a target queue group with a CoS such that > > all > > > > packets assigned to this CoS will be distributed to the specified > > > > queue_group_id at the end of classification processing. > > > > > +@subsubsection cos_set_pool odp_cos_set_pool > > > > > +@verbatim > > > > > +/** > > > > > + * Assign packet buffer pool for specific class-of-service > > > > > + * > > > > > + * @param cos_id class-of-service instance. > > > > > + * @param pool_id is a buffer pool identifier where all packet > > buffers > > > > > + * will be sourced to store packet that belong to > > this > > > > > + * class of service. > > > > > + * > > > > > + * @return 0 on success negative error code on failure. > > > > > + * > > > > > + * > > > > > + */ > > > > > + > > > > > +int odp_cos_set_pool(odp_cos_t cos_id, odp_buffer_pool_t pool_id); > > > > > +@endverbatim > > > > > + > > > > > +This OPTIONAL routine associates a target buffer pool with a CoS > > such > > > > that all packets assigned to this CoS will be stored in packet buffers > > > > allocated from the designated pool_id. > > > > > + > > > > > + > > > > > +@subsection cos_drop_policy Class of Service Drop Policy Routines > > > > > +These routines control how drop policies are to be observed for a > > given > > > > class of service. > > > > > +@subsubsection drop_data_types Data types > > > > > +~~~~~{.c} > > > > > +enum odp_cos_drop_e { > > > > > + ODP_COS_DROP_POOL, /**< Follow buffer pool drop > > policy */ > > > > > + ODP_COS_DROP_NEVER, /**< Never drop, ignoring buffer > > pool > > > > policy */ > > > > > +}; > > > > > +typedef enum odp_drop_e odp_drop_t; > > > > > +~~~~~ > > > > > + > > > > > +@subsubsection cos_set_drop odp_cos_set_drop > > > > > +@verbatim > > > > > +/** > > > > > + * Assign packet drop policy for specific class-of-service > > > > > + * > > > > > + * @param cos_id class-of-service instance. > > > > > + * @param drop_policy is the desired packet drop policy for this > > > > class. > > > > > + * > > > > > + * @return 0 on success negative error code on failure. > > > > > + */ > > > > > + > > > > > +int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_t drop_policy); > > > > > +@endverbatim > > > > > + > > > > > +This routine sets the drop policy for a class of service. > > > > > +It is an OPTIONAL routine. > > > > > +If an implementation does not provide this function it MUST supply a > > > > definition of it that simply returns ODP_FUNCTION_NOT_AVAILABLE. > > > > > +@subsubsection pktio_set_default_cos odp_pktio_set_default_cos > > > > > +@verbatim > > > > > +/** > > > > > + * Setup per-port default class-of-service > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @param default_cos class-of-service set to all packets arriving > > > > > + * at the 'pktio_in' ingress port, unless overridden by > > > > subsequent > > > > > + * header-based filters. > > > > > + * > > > > > + * @return 0 on success negative error code on failure. > > > > > + * > > > > > + * > > > > > + * @note This may replace the default queue per pktio. > > > > > + */ > > > > > + > > > > > +int odp_pktio_set_default_cos(odp_pktio_t pktio_in, odp_cos_t > > > > default_cos); > > > > > +@endverbatim > > > > > + > > > > > +This routine specifies a default class of service for a given pktio > > > > instance. > > > > > +Incoming packets on the specified pktio are assigned to this class > > of > > > > service if no other pattern matching rule obtains. > > > > > +@subsubsection pktio_set_error_cos odp_pktio_set_error_cos > > > > > +@verbatim > > > > > +/** > > > > > + * Setup per-port error class-of-service > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @param error_cos class-of-service set to all packets arriving > > > > > + * at the 'pktio_in' ingress port that contain an error. > > > > > + * > > > > > + * @return 0 on success negative error code on failure. > > > > > + */ > > > > > + > > > > > +int odp_pktio_set_error_cos(odp_pktio_t pktio_in, odp_cos_t > > error_cos); > > > > > +@endverbatim > > > > > + > > > > > +This OPTIONAL function assigns a class-of-service used to handle > > > > packets containing various types of errors. > > > > > +The specific errors types include L2 FCS and optionally L3/L4 > > checksum > > > > errors, malformed headers, etc., depending on platform capabilities. > > > > > +The specified error_cos MAY simply discard these packets or deliver > > > > them via a queue to the application for further processing. > > > > > +@subsubsection pktio_set_skip odp_pktio_set_skip > > > > > +@verbatim > > > > > +/** > > > > > + * Setup per-port header offset > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @param offset is the number of bytes the classifier must skip. > > > > > + * > > > > > + * @return Success or ODP_FUNCTION_NOT_AVAILABLE > > > > > + */ > > > > > + > > > > > +int odp_pktio_set_skip(odp_pktio_t pktio_in, size_t offset); > > > > > +@endverbatim > > > > > + > > > > > +This OPTIONAL function applies to ports that carry an additional > > > > headers preceding the standard Ethernet header. > > > > > +Such headers are typically vendor-specific and thus the classifier > > is > > > > not required to parse such headers, but the size of a custom header is > > > > critical for the classifier to be able to parse standard protocol > > headers > > > > that normally follow. > > > > > +@subsubsection cos_set_headroom odp_cos_set_headroom > > > > > +@verbatim > > > > > +/** > > > > > + * Specify per-port buffer headroom > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @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. > > > > > + * > > > > > + * @return Success or ODP_PARAMETER_ERROR, > > > > > + * or ODP_FUNCTION_NOT_AVAILABLE > > > > > + */ > > > > > + > > > > > +int odp_cos_set_headroom(odp_cos_t cos_id, size_t req_room); > > > > > +@endverbatim > > > > > + > > > > > +This OPTIONAL routine specifies the number of bytes of headroom that > > > > should be reserved for each packet assigned to this class of service. > > > > > +Each implementation defines an ODP_PACKET_MAX_HEADROOM limit that > > sets > > > > an upper bound on the size of the headroom that can be reserved for a > > > > packet. > > > > > +@subsubsection cos_with_l2_priority odp_cos_with_l2_priority > > > > > +@verbatim > > > > > +/** > > > > > + * Request to override per-port class of service > > > > > + * based on Layer-2 priority field if present. > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @param num_qos is the number of QoS levels, typically 8. > > > > > + * @param qos_table are the values of the Layer-2 QoS header > > field. > > > > > + * @param cos_table is the class-of-service assigned to each of > > the > > > > > + * allowed Layer-2 QOS levels. > > > > > + * @return 0 on success negative error code on failure. > > > > > + */ > > > > > + > > > > > +int odp_cos_with_l2_priority(odp_pktio_t pktio_in, > > > > > + size_t num_qos, > > > > > + uint8_t qos_table[], /**< > > > > 'num_qos' elements */ > > > > > + odp_cos_t cos_table[]); /**< > > > > 'num_qos' elements */ > > > > > +@endverbatim > > > > > + > > > > > +This routine is used to assign classes of service based on the > > layer 2 > > > > (L2) priority associated with input packets received on the specified > > > > pktio_in. > > > > > +For each of the values in qos_table[], the corresponding value in > > > > cos_table[] will be assigned. > > > > > +@subsubsection cos_with_l3_dscp odp_cos_with_l3_dscp > > > > > +@verbatim > > > > > +/** > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @param num_qos is the number of allowed Layer-3 QoS levels. > > > > > + * @param qos_table are the values of the Layer-3 QoS header > > field. > > > > > + * @param cos_table is the class-of-service assigned to each of > > the > > > > > + * allowed Layer-3 QOS levels. > > > > > + * @param l3_preference when true, Layer-3 QoS overrides L2 QoS > > when > > > > present. > > > > > + * > > > > > + * @return 0 on success negative error code on failure. > > > > > + */ > > > > > + > > > > > +int odp_cos_with_l3_qos(odp_pktio_t pktio_in, > > > > > + size_t num_qos, > > > > > + uint8_t qos_table[], /**< 'num_qos' > > > > elements */ > > > > > + odp_cos_t cos_table[], /**< > > 'num_qos' > > > > elements */ > > > > > + odp_bool_t l3_preference); > > > > > +@endverbatim > > > > > + > > > > > +This OPTIONAL routine is used to assign classes of service based on > > the > > > > layer 3 (L3) Differentiated Services (DS) designation. > > > > > +This is the DSCP field of an IPv4 header or the first six bits of > > the > > > > Traffic Class of an IPv6 header. > > > > > +For each of the values in qos_table[], the corresponding value in > > > > cos_table[] will be assigned. > > > > > +The l3_preference flag is use to control whether the CoS assigned by > > > > this routine takes precedence over the CoS assigned by > > > > odp_cos_with_l2_priority() in the event that both apply to the same > > packet. > > > > > + > > > > > +@subsection pmrs Pattern Matching Rules > > > > > +While the above routines permit class of service assignments to be > > made > > > > based on static criteria, the real power of classification is the > > ability > > > > to identify flows based on the variable contents of packet headers. > > > > > +To do this ODP provides support for defining pattern matching rules > > > > (PMRs) that operate based on values contained in specified header > > fields. > > > > > + > > > > > +Associated with PMRs are enums that are used to specify standard > > packet > > > > header fields: > > > > > +@subsubsection cos_hdr_flow_fields odp_cos_hdr_flow_fields_e > > > > > +@verbatim > > > > > +/** > > > > > + * Packet header field enumeration > > > > > + * for fields that may be used to calculate > > > > > + * the flow signature, if present in a packet. > > > > > + */ > > > > > + > > > > > +enum odp_cos_hdr_flow_fields_e { > > > > > + ODP_COS_FHDR_IN_PKTIO, /**< Ingress port number */ > > > > > + ODP_COS_FHDR_L2_SAP, /**< Ethernet Source MAC > > address > > > > */ > > > > > + ODP_COS_FHDR_L2_DAP, /**< Ethernet Destination MAC > > > > address */ > > > > > + ODP_COS_FHDR_L2_VID, /**< Ethernet VLAN ID */ > > > > > + ODP_COS_FHDR_L3_FLOW /**< IPv6 flow_id */ > > > > > + ODP_COS_FHDR_L3_SAP, /**< IP source address */ > > > > > + ODP_COS_FHDR_L3_DAP, /**< IP destination address */ > > > > > + ODP_COS_FHDR_L4_PROTO, /**< IP protocol (e.g. > > > > TCP/UDP/ICMP) */ > > > > > + ODP_COS_FHDR_L4_SAP, /**< Transport source port */ > > > > > + ODP_COS_FHDR_L4_DAP, /**< Transport destination > > port */ > > > > > + ODP_COS_FHDR_IPSEC_SPI, /**< IPsec session identifier > > */ > > > > > + ODP_COS_FHDR_LD_VNI, /**< NVGRE/VXLAN network > > > > identifier */ > > > > > + ODP_COS_FHDR_USER /**< Application-specific > > header > > > > field(s) */ > > > > > +}; > > > > > +@endverbatim > > > > > + > > > > > +Conforming ODP implementations SHOULD implement efficient flow set > > > > management routines such as these: > > > > > + > > > > > +~~~~~{.c} > > > > > +/** > > > > > + * Set of header fields that take part in flow signature hash > > > > calculation: > > > > > + * bit positions per 'odp_cos_hdr_flow_fields_e' enumeration. > > > > > + * > > > > > +typedef uint16_t odp_cos_flow_set_t; > > > > > + > > > > > + > > > > > +/** > > > > > + * Set a member of the flow signature fields data set > > > > > + * > > > > > +static inline odp_cos_flow_set_t > > > > > +odp_cos_flow_set( odp_cos_flow_set_t set, > > > > > + enum odp_cos_hdr_flow_fields_e field) > > > > > +{ > > > > > + return set | (1U << field); > > > > > +} > > > > > + > > > > > + > > > > > +/** > > > > > + * Test a member of the flow signature fields data set > > > > > + * > > > > > +static inline bool > > > > > +odp_cos_flow_is_set( odp_cos_flow_set_t set, > > > > > + enum odp_cos_hdr_flow_fields_e field) > > > > > +{ > > > > > + return (set & (1U << field)) != 0; > > > > > +} > > > > > +~~~~~ > > > > > + > > > > > +These routines are intended to be used in support of the following > > flow > > > > signature APIs: > > > > > + > > > > > +@subsubsection cos_class_flow_sig odp_cos_class_flow_signature > > > > > +@verbatim > > > > > +/** > > > > > + * Set up set of headers used to calculate a flow signature > > > > > + * based on class-of-service. > > > > > + * > > > > > + * @param cos_id class of service instance identifier > > > > > + * @param req_data_set requested data-set for flow signature > > calculation > > > > > + * > > > > > + * @return data-set that was successfully applied. All-zeros data > > set > > > > > + * indicates a failure to assign any of the requested fields, or > > other > > > > > + * error. > > > > > + */ > > > > > + > > > > > +odp_cos_flow_set_t > > > > > +odp_cos_class_flow_signature(odp_cos_t cos_id, > > > > > + odp_cos_flow_set_t req_data_set); > > > > > +@endverbatim > > > > > + > > > > > +This OPTIONAL routine associates a fow set with a class of service > > for > > > > flow signature calculation. > > > > > + > > > > > +@subsubsection cos_port_flow_sig odp_cos_port_flow_signature > > > > > +@verbatim > > > > > +/** > > > > > + * Set up set of headers used to calculate a flow signature > > > > > + * based on ingress port. > > > > > + * > > > > > + * @param pktio_in ingress port identifier. > > > > > + * @param req_data_set requested data-set for flow signature > > calculation > > > > > + * > > > > > + * @return data-set that was successfully applied. An all-zeros > > data-set > > > > > + * indicates a failure to assign any of the requested fields, or > > other > > > > > + * error. > > > > > + */ > > > > > + > > > > > +odp_cos_flow_set_t > > > > > +odp_cos_port_flow_signature(odp_pktio_t pktio_in, > > > > > + odp_cos_flow_set_t req_data_set); > > > > > +@endverbatim > > > > > + > > > > > +@subsection pmr_routines Pattern Matching Rules Routines > > > > > +The following data structures SHOULD be implemented to support the > > > > definition of pattern matching routines by conforming ODP > > implementations: > > > > > + > > > > > +~~~~~{.c} > > > > > +/** > > > > > + * PMR - Packet Matching Rule > > > > > + * Up to 32 bit of ternary matching of one of the available header > > > > fields > > > > > + * > > > > > + > > > > > + > > > > > +#define ODP_PMR_INVAL ((odp_pmr_t)NULL) > > > > > +typedef struct odp_pmr_s *odp_pmr_t; > > > > > +~~~~~ > > > > > + > > > > > +@subsecion terms Terms > > > > > +Terms are the elements of a PMR and are identified by the following > > > > enum: > > > > > + > > > > > +@verbatim > > > > > +enum odp_pmr_term_e { > > > > > + ODP_PMR_LEN, /**< Total length of received packet > > */ > > > > > + ODP_PMR_ETHTYPE_0, /**< Initial (outer) Ethertype only > > > > (*val=uint16_t)*/ > > > > > + ODP_PMR_ETHTYPE_X, /**< Ethertype of most inner VLAN tag > > > > (*val=uint16_t)*/ > > > > > + ODP_PMR_VLAN_ID_0, /**< First VLAN ID (outer) > > > > (*val=uint16_t) */ > > > > > + ODP_PMR_VLAN_ID_X, /**< Last VLAN ID (inner) > > (*val=uint16_t) > > > > */ > > > > > + ODP_PMR_DMAC, /**< destination MAC address > > > > (*val=uint64_t) */ > > > > > + ODP_PMR_IPPROTO, /**< IP Protocol or IPv6 Next Header > > > > (*val=uint8_t) */ > > > > > + ODP_PMR_UDP_DPORT, /**< Destination UDP port, implies > > > > IPPROTO=17 */ > > > > > + ODP_PMR_TCP_DPORT, /**< Destination TCP port implies > > > > IPPROTO=6 */ > > > > > + ODP_PMR_UDP_SPORT, /**< Source UDP Port (*val=uint16_t) > > */ > > > > > + ODP_PMR_TCP_SPORT, /**< Source TCP port (*val=uint16_t) > > */ > > > > > + ODP_PMR_SIP_ADDR, /**< Source IP address (uint32_t) */ > > > > > + ODP_PMR_DIP_ADDR, /**< Destination IP address > > (uint32_t) */ > > > > > + ODP_PMR_SIP6_ADDR, /**< Source IP address (uint8_t[16]) > > */ > > > > > + ODP_PMR_DIP6_ADDR, /**< Destination IP address > > (uint8_t[16]) > > > > */ > > > > > + ODP_PMR_IPSEC_SPI, /**< IPsec session > > > > identifier(*val=uint32_t) */ > > > > > + ODP_PMR_LD_VNI, /**< NVGRE/VXLAN network identifier > > > > (*val=uint32_t) */ > > > > > + > > > > > + > > > > > + /** Inner header may repeat above values with this offset */ > > > > > + ODP_PMR_INNER_HDR_OFF=32 > > > > > +}; > > > > > +@endverbatim > > > > > + > > > > > +@subsubsection tunnel_considerations Tunnel Considerations > > > > > +Note that PMRs may be extended to support tunnels and tenants > > (NVGRE, > > > > VXLAN) via the ODP_PMR_INNER_HDR_OFF enum. > > > > > +This enum is intended to be used as an “adder” to a PMR to indicate > > > > that the term refers to an inner header. > > > > > +For example, the term ODP_PMR_DMAC would refer to the destination > > MAC > > > > address of the packet if the packet is not a tunnel, or of the outer > > header > > > > (the tunnel) if the packet is a tunnel. > > > > > +To refer to the inner (tenant) destination MAC, the term would be > > > > specified as ODP_PMR_INNER_HDR_OFF+ODP_PMR_DMAC. > > > > > + > > > > > +@subsection pmr_apis PMR APIs > > > > > +The following APIs are provided to enable an ODP application to > > specify > > > > PMRs as a series of individual or cascaded terms: > > > > > +@subsubsection pmr_create_match odp_pmr_create_match > > > > > +@verbatim > > > > > +/** > > > > > + * Create a packet match rule with mask and value > > > > > + * > > > > > + * @param term is one value of the enumerated values supported > > > > > + * @param val is the value to match against the packet header > > > > > + * in native byte order. > > > > > + * @param mask is the mask to indicate which bits of the header > > > > > + * should be matched ('1') and which should be > > ignored > > > > ('0') > > > > > + * @param val_sz size of the ‘val’ and ‘mask’ arguments, > > > > > + * that must match the value size requirement of > > the > > > > > + * specific ‘term’. > > > > > + * > > > > > + * @return a handle of the matching rule or ODP_PMR_INVAL on error > > > > > + */ > > > > > + > > > > > +odp_pmr_t odp_pmr_create_match(enum odp_pmr_term_e term, > > > > > + const void *val, const void *mask, > > > > size_t val_sz); > > > > > +@endverbatim > > > > > + > > > > > +This routine creates a PMR that matches a single value to a term. > > > > > + > > > > > +@subsubsection pmr_create_range odp_pmr_create_range > > > > > +@verbatim > > > > > +/** > > > > > + * Create a packet match rule with value range > > > > > + * > > > > > + * @param term is one value of the enumerated values supported > > > > > + * @param val1 is the lower bound of the header field range. > > > > > + * @param val2 is the upper bound of the header field range. > > > > > + * @param val_sz size of the ‘val1’ and ‘val2’ arguments, > > > > > + * that must match the value size requirement of > > the > > > > > + * specific ‘term’. > > > > > + * > > > > > + * @return a handle of the matching rule or ODP_PMR_INVAL on error > > > > > + * @note: Range is inclusive [val1..val2]. > > > > > + */ > > > > > + > > > > > +odp_pmr_t odp_pmr_create_range(enum odp_pmr_term_e term, > > > > > + const void *val1, const void > > > > *val2, size_t val_sz); > > > > > +@endverbatim > > > > > + > > > > > +This routine creates a PMR that matches an inclusive range of > > values to > > > > a term. > > > > > + > > > > > +@subsubsection pmr_destroy odp_pmr_destroy > > > > > +@verbatim > > > > > +/** > > > > > + * Invalidate a packet match rule and vacate its resources > > > > > + * > > > > > + * @param pmr_id the identifier of the PMR to be destroyed > > > > > + * > > > > > + * @return Success or ODP_PMR_INVALID if the specified pmr_id not > > found. > > > > > + */ > > > > > + > > > > > +int odp_pmr_destroy(odp_omr_t pmr_id); > > > > > +@endverbatim > > > > > + > > > > > +This routine destroys a previously created PMR. > > > > > +If the PMR is currently associated with an active class of service > > it > > > > is unpredictable at which point the match defined by the PMR is > > deactivated > > > > in terms of packet flow. > > > > > +However, implementations MUST ensure that a PMR is either matched or > > > > not matched in its entirety such that dynamic changes to PMRs do not > > result > > > > in partial matches. > > > > > + > > > > > +@subsubsection pktio_pmr_cos odp_pktio_pmr_cos > > > > > +@verbatim > > > > > +/** > > > > > + * Apply a PMR to a pktio to assign a CoS. > > > > > + * > > > > > + * @param pmr_id the id of the PMR to be activated > > > > > + * @param src_pktio the pktio to which this PMR is to be applied > > > > > + * @param dst_cos the CoS to be assigned by this PMR > > > > > + * > > > > > + * @return Success or ODP_PARAMETER_ERROR > > > > > + */ > > > > > + > > > > > +int odp_pktio_pmr_cos(odp_pmr_t pmr_id, odp_pktio_t src_pktio, > > > > odp_cos_t dst_cos); > > > > > +@endverbatim > > > > > + > > > > > +This routine links a pktio to a corresponding class of service via a > > > > specified PMR. > > > > > +Any packet received on the specified src_pktio that matches the > > > > specified pmr_id will be assigned to the specified dst_cos. > > > > > +If multiple PMRs match the implementation MAY define an inherent > > > > precedence or it MAY be unpredictable as to which PMR will determine > > the > > > > assigned CoS. > > > > > +For this reason applications SHOULD NOT be written to use > > conflicting > > > > or ambiguous PMR definitions. > > > > > + > > > > > +@subsubsection cos_pmr_cos odp_cos_pmr_cos > > > > > +@verbatim > > > > > +/** > > > > > + * Cascade a PMR to refine packets from one CoS to another. > > > > > + * > > > > > + * @param pmr_id the id of the PMR to be activated > > > > > + * @param src_cos the id of the CoS to be filtered > > > > > + * @param dst_cos the id of the CoS to be assigned to packets > > > > filtered > > > > > + * from src_cos that match pmr_id. > > > > > + * > > > > > + * @return Success or ODP_PARAMETER_ERROR if an input is in error > > > > > + * or ODP_IMPLEMENTATION_LIMIT if cascade depth is > > > > exceeded > > > > > + */ > > > > > + > > > > > +int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t > > > > dst_cos); > > > > > +@endverbatim > > > > > + > > > > > +This routine is used to cascade PMRs by passing packets assigned to > > the > > > > src_cos through another PMR. > > > > > +Those matching are reassigned to the specified dst_cos. > > > > > +Note that this process can be repeated to an implementation-defined > > > > maximum supported cascade depth. > > > > > +When cascades are defined, the actual class of service assigned to a > > > > packet is the result of the longest chain of PMRs that can be matched > > > > against the packet. > > > > > + > > > > > +For example, suppose the following sequence of PMRs is in effect: > > > > > + > > > > > +@verbatim > > > > > +odp_pktio_pmr_cos(pmr_idA, pktio_id, cos_idA); > > > > > +odp_cos_pmr_cos(pmr_idB, cos_idA, cos_idB); > > > > > +odp_cos_pmr_cos(pmr_idC, cos_idB, cos_idC); > > > > > +odp_cos_pmr_cos(pmr_idD, cos_idC, cos_idD); > > > > > +@endverbatim > > > > > + > > > > > +If a packet arrives on pktio_id that matches pmr_idA it is assigned > > to > > > > cos_idA. > > > > > +But since it is now on cos_idA it is further filtered by pmr_idB > > and if > > > > it matches is reassigned to cos_idB. > > > > > +This process continues until no further more specific match is > > found to > > > > determine the final CoS that the packet receives. > > > > > + > > > > > +Note that given this rule set a packet that matched pmr_idA and > > pmr_idC > > > > it would be assigned to cos_idA because the rule that can assign > > packets to > > > > pmr_idC is only applicable to packets that are assigned to cos_idB, not > > > > cos_idA. > > > > > + > > > > > +Using cascaded PMRs it is possible to build quite sophisticated > > filters > > > > (up to the implementation limits supported by a given platform). > > > > > +For example, one could add additional rules to the above set: > > > > > + > > > > > +@verbatim > > > > > +odp_cos_pmr_cos(pmr_idAC, cos_idA, cos_idC); > > > > > +odp_cos_pmr_cos(pmr_idAD, cos_idA, cos_idD); > > > > > +@endverbatim > > > > > + > > > > > +To cover cases where some packets on cos_idA should be further > > sorted > > > > to cos_idB while others should be sorted directly to cos_idC or > > cos_idD. > > > > > +Again it is the application’s responsibility to ensure that the > > > > cascades remain unambiguous and that loops be avoided (e.g., having > > rules > > > > that bounce packets between cos_idA and cos_idB endlessly). > > > > > + > > > > > +@subsection pmr_stats PMR Statistics > > > > > +Conforming ODP implementations SHOULD maintain statistics regarding > > > > PMRs and provide the following routines for retrieving them: > > > > > + > > > > > +@subsubsection pmr_match_count odp_pmr_match_count > > > > > +@verbatim > > > > > +/** > > > > > + * Retrieve packet matcher statistics > > > > > + * > > > > > + * @param pmr_id the id of the PMR from which to retrieve the > > count > > > > > + * > > > > > + * @return The current number of matches for a given matcher > > instance. > > > > > + */ > > > > > + > > > > > +signed long odp_pmr_match_count(odp_pmr_t pmr_id); > > > > > +@endverbatim > > > > > + > > > > > +@subsubsection pmr_terms_cap odp_pmr_terms_cap > > > > > +@verbatim > > > > > +/** > > > > > + * Inquire about matching terms supported by the classifier > > > > > + * > > > > > + * @return A mask one bit per enumerated term, one for each of > > > > op_pmr_term_e > > > > > + */ > > > > > + > > > > > +unsigned long long odp_pmr_terms_cap(void); > > > > > +@endverbatim > > > > > + > > > > > +@subsubsection pmr_terms_avail odp_pmr_terms_avail > > > > > +@verbatim > > > > > +/** > > > > > + * Return the number of packet matching terms available for use > > > > > + * > > > > > + * @return A number of packet matcher resources available for use. > > > > > + */ > > > > > + > > > > > +unsigned odp_pmr_terms_avail(void); > > > > > +@endverbatim > > > > > + > > > > > +@subsection pmr_composite_rules Pattern Matching Composite Routines > > > > > +As a shorthand, applications MAY express pattern matching rules > > using a > > > > table rather than constructing them term-by-term. > > > > > +ODP implementations MUST support both methods of rule specification > > but > > > > MAY have implementation-specific restrictions on the complexity of > > > > table-based rules they support. > > > > > +Note that some implementations MAY be able to implement tables > > directly > > > > while others MAY choose to implement tables by internally generating > > the > > > > equivalent set of term generating calls. > > > > > + > > > > > +@subsubsection pmr_table_structure PMR Table Structure > > > > > +@verbatim > > > > > +/** > > > > > + * Following structure is used to define composite packet matching > > rules > > > > > + * in the form of an array of individual match or range rules. > > > > > + * The underlying platform may not support all or any specific > > > > combination > > > > > + * of value match or range rules, and the application should take > > care > > > > > + * of inspecting the return value when installing such rules, and > > > > perform > > > > > + * appropriate fallback action. > > > > > + */ > > > > > + > > > > > +typedef struct odp_pmr_match_t { > > > > > + enum odp_pmr_match_type_e { > > > > > + ODP_PMR_MASK, /**< Match a masked set > > of > > > > bits */ > > > > > + ODP_PMR_RANGE, /**< Match an integer > > range > > > > */ > > > > > + } match_type; > > > > > + union { > > > > > + struct { > > > > > + enum odp_pmr_term_e term; > > > > > + const void *val; > > > > > + const void *mask; > > > > > + unsigned int val_sz; > > > > > + } mask; /**< Match a masked set of bits */ > > > > > + struct { > > > > > + enum odp_pmr_term_e term; > > > > > + const void *val1; > > > > > + const void *val2; > > > > > + unsigned int val_sz; > > > > > + } range; /**< Match an integer range */ > > > > > + }; > > > > > +} odp_pmr_match_t; > > > > > + > > > > > + > > > > > +/** An opaque handle to a composite packet match rule-set */ > > > > > +typedef struct odp_pmr_set_s *odp_pmr_set_t; > > > > > +@endverbatim; > > > > > + > > > > > +The above structure is used with the following APIs to implement > > > > table-based PMRs: > > > > > + > > > > > +@subsubsection pmr_match_set_create odp_pmr_match_set_create > > > > > +@verbatim > > > > > +/** > > > > > + * Create a composite packet match rule > > > > > + * > > > > > + * @param num_terms is the number of terms in the match rule. > > > > > + * @param terms is an array of num_terms entries, one entry per > > > > > + * term desired. > > > > > + * @param dst_cos is the class-of-service to be assigned to > > packets > > > > > + * that match the compound rule-set, or a subset > > > > thereof, > > > > > + * if partly applied. > > > > > + * @param pmr_set_id is the returned handle to the composite rule > > set. > > > > > + * > > > > > + * @return The return value may be a negative number indicating a > > > > general > > > > > + * error, or a positive number indicating the number of ‘terms’ > > > > elements that > > > > > + * have been successfully mapped to the underlying platform > > > > classification engine, > > > > > + * and may be in the range from 1 to ‘num_terms’. > > > > > + */ > > > > > + > > > > > +int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, > > > > > + odp_pmr_set_t *pmr_set_id); > > > > > +@endverbatim > > > > > + > > > > > +This routine is used to create a PMR match set. > > > > > + It is the equivalent to a cascade of PMRs except that there are no > > > > “intermediate” classes of service defined. > > > > > +Instead, the entire match set either matches or does not match as a > > > > single entity. > > > > > + > > > > > +@subsubsection pmr_match_set_destroy odp_pmr_match_set_destroy > > > > > +@verbatim > > > > > +/** > > > > > + * Function to delete a composite packet match rule set > > > > > + * > > > > > + * All of the resources pertaining to the match set associated with > > the > > > > > + * class-of-service will be released, but the class-of-service will > > > > > + * remain intact. > > > > > + * > > > > > + * @param pmr_set_id a composite rule-set handle returned when > > created. > > > > > + * > > > > > + * @note Depending on the implementation details, destroying a > > rule-set > > > > > + * may not guarantee the availability of hardware resources to > > create > > > > the > > > > > + * same or essentially similar rule-set. > > > > > + */ > > > > > + > > > > > +int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); > > > > > +@endverbatim > > > > > + > > > > > +This routine destroys a PMR match set previously created by > > > > odp_pmr_match_set_create(). > > > > > + > > > > > +@subsubsection pktio_pmr_match_set_cos odp_pktio_pmr_match_set_cos > > > > > +@verbatim > > > > > +/** > > > > > + * Apply a PMR Match Set to a pktio to assign a CoS. > > > > > + * > > > > > + * @param pmr_set_id the id of the PMR match set to be activated > > > > > + * @param src_pktio the pktio to which this PMR match set is to be > > > > applied > > > > > + * @param dst_cos the CoS to be assigned by this PMR match set > > > > > + * > > > > > + * @return Success or ODP_PARAMETER_ERROR > > > > > + */ > > > > > + > > > > > +int odp_pktio_pmr_match_set_cos(odp_pmr_t pmr_id, odp_pktio_t > > src_pktio, > > > > > + odp_cos_t dst_cos); > > > > > +@endverbatim > > > > > + > > > > > +This routine is the same as odp_pktio_pmr_cos() except that it > > operates > > > > on PMR match sets rather than individual PMRs. > > > > > + > > > > > +@section items_pending Items pending resolution > > > > > +- Revise ‘odp_packet_io.h’ API with respect of default input queue > > per > > > > ‘pktio’ instance. > > > > > +- Revise ‘odp_queue.h’ API to support an arbitrary priority range, > > > > typically 8 priority levels with numeric priority values are > > > > platform-specific. > > > > > +- Add specific packet meta data fields to go into packet buffer > > which > > > > contain all meta data fields parsed and generated by the classifier, > > for > > > > later application use. > > > > > + > > > > > +@section implementation_notes Implementation Notes > > > > > +The following sections are not part of the specification, but shed > > > > light into the intent of the specification in several areas, describing > > > > some specific implementation approaches of these aspects. > > > > > + > > > > > +@subsection supporting_multi_pools Supporting multiple buffer pools > > > > > +The support of multiple buffer pools for containing packet buffers > > is > > > > optional, and may not be supported by some platforms. > > > > > +The importance of this feature stems from the need of protecting a > > > > networking application in the event of a congestion, or an attempted > > denial > > > > of service attack. > > > > > +Separating different classes of service to dedicated buffer pools > > > > allows the system to limit the memory resources that may be consumed > > by a > > > > particular type of traffic, thereby reserving buffer resources for > > other > > > > classes of traffic. > > > > > + > > > > > +In a software implementation, a packet would already be stored in > > > > memory when the classifier is invoked, and so it seems the classifier > > is > > > > unable to insert itself into the process of selecting a buffer pool. > > > > > +For obvious reasons the copying of a packet into a new buffer > > allocated > > > > from a different pool by the classifier is not a desirable solution. > > > > > + > > > > > +The recommended solution is to implement buffer pools in the form of > > > > buffer counters, while the actual buffers all belong to a single free > > list > > > > when not used to store a packet. > > > > > +In such an implementation, the classifier will be able to associate > > a > > > > packet already occupying a buffer to a different pool than the default > > by > > > > incrementing the buffer counter of the newly selected pool, and > > > > decrementing the counter representing the default pool. > > > > > +If however the selected pool counter has already reached a certain > > > > limit, the classifier would be able to e.g discard the packet instead > > of > > > > incrementing the destination pool counter, and thereby enforce the > > > > desirable semantics of distinct buffer pools per class of service. > > > > > + > > > > > +Other possible action that may be taken in response to running out > > of > > > > buffers or coming too low on buffers include back-pressure and > > > > random-early-detect with a discard probability inversely proportional > > to > > > > the number of free buffers in a pool. > > > > > +A related implementation topic is the ability to begin dropping some > > > > packets before a buffer pool is entirely exhausted. > > > > > +This is typically referred to as <em>Random Early Detect</em> (or > > > > “RED”). > > > > > +This is deemed to be a feature of the buffer pool implementation on > > a > > > > given platform, where in addition to a hard limit on the number of > > buffers > > > > that can be allocated to a pool, there can also be an option discard > > > > packets with a probability the increases as the number of outstanding > > > > buffers approaches that hard limit. > > > > > + > > > > > +@subsection resolving_gaps Resolving gaps between the API and > > hardware > > > > capabilities > > > > > +On platforms that support hardware packet accelerators, it is > > possible > > > > that the packet parsing and classification functionality is sufficient > > to > > > > address only a portion of the functionality specified within this > > document. > > > > > +This gap may be potentially bridged by augmenting the hardware > > > > classification capabilities with a software logic implemented as part > > of > > > > the platform. > > > > > +In that case, the platform will have to curve out a fraction of the > > > > processing resources and dedicate those to the software classification > > > > logic, which would be invoked for packets that the hardware platform > > was > > > > unable to classify completely. > > > > > +At the time of this writing, it is believed however that the > > > > performance penalty that will be incurred as a result of software > > > > augmentation is unjustified for most application, i.e. > > > > > +it is preferred to lose the precision of packet prioritization while > > > > maintaining full hardware packet processing speed. > > > > > + > > > > > +@subsection loopback_case The case for loopback ports, and some of > > > > their uses > > > > > +In some applications, it may be desirable to be able to run a single > > > > packet through the classifier more than once. > > > > > +For example, an encrypted IPsec packet is received from a physical > > port. > > > > > +The encrypted packet is assigned a class of service based on its > > outer > > > > unencrypted header fields. > > > > > +Later, processing the packet entails decrypting the payload of the > > > > packet, authenticating it, and removing the original outer headers, > > which > > > > reveals a new set of protocol headers which need to be used to > > re-classify > > > > the packet, and assign it a new priority and buffer pool. > > > > > +An elegant solution for this use case would be to take advantage of > > > > “loopback” logical ports that may be implemented in certain platforms, > > by > > > > transmitting decapsulated packet into a loop-back port. > > > > > +The same packet then is received from a loop-back port and is > > examined > > > > by the classifier in accordance to the rules assigned to the loopback > > > > odp_pktio logical port instance. > > > > > +Similar mechanism may be applied to tunnel termination processing, > > > > fragment reassembly et al. > > > > > + > > > > > +@section related_topics Related Topics > > > > > +The following section discusses aspects of the ODP API that are not > > > > integral to the classifier, which only applies to ingress > > preprocessing. > > > > > +This section covers miscellaneous aspects of the API that need to be > > > > addressed, and are related to packet buffer processing and egress > > > > post-processing. > > > > > +Additional packet buffer manipulation APIs > > > > > +The need for these following calls are made evident by the need to > > > > encapsulate, i.e., remove some headers and add other, thereby changing > > the > > > > size of the headers of a packet during processing. > > > > > + > > > > > +@subsection initial_headroom Configuring initial packet buffer > > headroom > > > > > +The following function is provided to configure the pktio receive > > > > mechanism to (optionally)reserve some headroom between start of the > > first > > > > buffer to the first byte of the first packet data byte, which > > subsequently > > > > could be used to increase the header size “in-place”, without > > allocating > > > > additional gather list elements. > > > > > +If the request is granted, at least <req_bytes> bytes will be > > reserved > > > > in the front of the packet data: > > > > > +@verbatim > > > > > +int odp_pktio_set_headroom(odp_pktio_t port_id, unsigned req_bytes); > > > > > +@endverbatim > > > > > +The return value should be negative if the request can not be > > > > satisfied, or positive otherwise indicating the actual minimum headroom > > > > reserved. > > > > > +Note that the implementation may reserve more than the requested > > amount > > > > of headroom, and hence on platforms that are unable to support > > per-port (or > > > > per CoS) headroom configuration, a system-wide headroom configuration > > may > > > > be set to the largest of all such requests, and thus satisfy the > > > > requirement. > > > > > +In addition to the above per-port headroom configuration call, there > > > > should be an optional, per-CoS call that allows the reservation of > > > > different amounts of packet buffer headroom for packets that match > > certain > > > > criteria: for example, the following call allows the application to > > request > > > > that only packets that are expected to be encapsulated in a tunnel, be > > > > augmented with a large headroom amount, while packets that are received > > > > from a tunnel, and are IP fragments, be assigned a different headroom > > > > requirement (see definition for odp_cos_set_headroom() above. > > > > > +Egress packet scheduling, prioritization and ordering > > > > > + > > > > > + > > > > > +Open Issues > > > > > +* Parallel matching rules relative precedence. > > > > > +* Specify application-defined header field declaration APIs. > > > > > +* Review RFC 4301 for match requirements for IPsec SA, consider the > > use > > > > of L4 port ranges instead of or in addition to value & mask matching > > > > criteria. > > > > > +* Consider the type of packet checks should route a packet through > > the > > > > error CoS: L2 is a safe choice, but L3/L4 checksum or other exceptions > > > > deserve consideration. > > > > > +Usage Examples > > > > > +Following is a simple sample configuration using the API elements > > > > described above. > > > > > +TBD. > > > > > > > > TBD?? > > > > > > > > Cheers, > > > > Anders > > > > > > > > -- > > Anders Roxell > > [email protected] > > M: +46 709 71 42 85 | IRC: roxell > > -- Anders Roxell [email protected] M: +46 709 71 42 85 | IRC: roxell _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
