| Message ID | 1410461131-5498-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
Stuart can you test this before I applies the patch. I will silently fix a warning that I had a chat with Bill about via HO. -If the request is granted, at least <req_bytes> bytes will be reserved in the front of the packet data: +If the request is granted, at least \e req_bytes bytes will be reserved in the front of the packet data: And change the commit message to: "classification_design: fix formatting issues" Cheers, Anders On 2014-09-11 13:45, Bill Fischofer wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > classification_design.dox | 78 ++++++++++++++++++++++++++--------------------- > 1 file changed, 43 insertions(+), 35 deletions(-) > > diff --git a/classification_design.dox b/classification_design.dox > index 58ffb51..b6a6f24 100644 > --- a/classification_design.dox > +++ b/classification_design.dox > @@ -1,4 +1,4 @@ > -/* Copyright (c) 2014, Linaro Limited > +/* Copyright (c) 2014, Linaro Limited > * All rights reserved > * > * SPDX-License-Identifier: BSD-3-Clause > @@ -19,12 +19,15 @@ Rule Matching, in turn, takes the result of parsing and sorts packets into Class > 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 > @@ -77,9 +80,11 @@ While the above description refers to the abstracted packet classifier, the foll > @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 > @@ -121,7 +126,6 @@ The ODP packet API module SHALL provide accessors for retrieving the above meta > @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 > /** > @@ -244,19 +248,19 @@ This routine associates a target queue group with a CoS such that all packets as > 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. > +This 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} > +@verbatim > 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; > -~~~~~ > +@endverbatim > > @subsubsection cos_set_drop odp_cos_set_drop > @verbatim > @@ -311,7 +315,7 @@ Incoming packets on the specified pktio are assigned to this class of service if > 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. > +This 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 > @@ -328,7 +332,7 @@ The specified error_cos MAY simply discard these packets or deliver them via a q > 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. > +This 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 > @@ -347,7 +351,7 @@ Such headers are typically vendor-specific and thus the classifier is not requir > 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. > +This 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 > @@ -385,10 +389,10 @@ For each of the values in qos_table[], the corresponding value in cos_table[] wi > * @return 0 on success negative error code on failure. > */ > > -int odp_cos_with_l3_qos(odp_pktio_t pktio_in, > +int odp_cos_with_l3_dscp(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_cos_t cos_table[], /**< 'num_qos' elements */ > odp_bool_t l3_preference); > @endverbatim > > @@ -429,7 +433,7 @@ enum odp_cos_hdr_flow_fields_e { > > Conforming ODP implementations SHOULD implement efficient flow set management routines such as these: > > -~~~~~{.c} > +@verbatim > /** > * Set of header fields that take part in flow signature hash calculation: > * bit positions per 'odp_cos_hdr_flow_fields_e' enumeration. > @@ -457,7 +461,7 @@ odp_cos_flow_is_set( odp_cos_flow_set_t set, > { > return (set & (1U << field)) != 0; > } > -~~~~~ > +@endverbatim > > These routines are intended to be used in support of the following flow signature APIs: > > @@ -480,7 +484,7 @@ 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. > +This OPTIONAL routine associates a flow set with a class of service for flow signature calculation. > > @subsubsection cos_port_flow_sig odp_cos_port_flow_signature > @verbatim > @@ -501,21 +505,23 @@ odp_cos_port_flow_signature(odp_pktio_t pktio_in, > odp_cos_flow_set_t req_data_set); > @endverbatim > > +This routine associates a flow set with an input port for flow signature claculation. > + > @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} > +@verbatim > /** > * 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; > -~~~~~ > +@endverbatim > > -@subsecion terms Terms > +@subsection terms Terms > Terms are the elements of a PMR and are identified by the following enum: > > @verbatim > @@ -737,24 +743,24 @@ Note that some implementations MAY be able to implement tables directly while ot > */ > > 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 */ > - }; > + 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; > > > @@ -851,6 +857,7 @@ In such an implementation, the classifier will be able to associate a packet alr > 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. > @@ -885,6 +892,7 @@ 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). > > @subsection open_issues Open Issues > -- > 1.8.3.2 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp
diff --git a/classification_design.dox b/classification_design.dox index 58ffb51..b6a6f24 100644 --- a/classification_design.dox +++ b/classification_design.dox @@ -1,4 +1,4 @@ -/* Copyright (c) 2014, Linaro Limited +/* Copyright (c) 2014, Linaro Limited * All rights reserved * * SPDX-License-Identifier: BSD-3-Clause @@ -19,12 +19,15 @@ Rule Matching, in turn, takes the result of parsing and sorts packets into Class 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 @@ -77,9 +80,11 @@ While the above description refers to the abstracted packet classifier, the foll @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 @@ -121,7 +126,6 @@ The ODP packet API module SHALL provide accessors for retrieving the above meta @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 /** @@ -244,19 +248,19 @@ This routine associates a target queue group with a CoS such that all packets as 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. +This 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} +@verbatim 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; -~~~~~ +@endverbatim @subsubsection cos_set_drop odp_cos_set_drop @verbatim @@ -311,7 +315,7 @@ Incoming packets on the specified pktio are assigned to this class of service if 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. +This 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 @@ -328,7 +332,7 @@ The specified error_cos MAY simply discard these packets or deliver them via a q 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. +This 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 @@ -347,7 +351,7 @@ Such headers are typically vendor-specific and thus the classifier is not requir 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. +This 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 @@ -385,10 +389,10 @@ For each of the values in qos_table[], the corresponding value in cos_table[] wi * @return 0 on success negative error code on failure. */ -int odp_cos_with_l3_qos(odp_pktio_t pktio_in, +int odp_cos_with_l3_dscp(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_cos_t cos_table[], /**< 'num_qos' elements */ odp_bool_t l3_preference); @endverbatim @@ -429,7 +433,7 @@ enum odp_cos_hdr_flow_fields_e { Conforming ODP implementations SHOULD implement efficient flow set management routines such as these: -~~~~~{.c} +@verbatim /** * Set of header fields that take part in flow signature hash calculation: * bit positions per 'odp_cos_hdr_flow_fields_e' enumeration. @@ -457,7 +461,7 @@ odp_cos_flow_is_set( odp_cos_flow_set_t set, { return (set & (1U << field)) != 0; } -~~~~~ +@endverbatim These routines are intended to be used in support of the following flow signature APIs: @@ -480,7 +484,7 @@ 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. +This OPTIONAL routine associates a flow set with a class of service for flow signature calculation. @subsubsection cos_port_flow_sig odp_cos_port_flow_signature @verbatim @@ -501,21 +505,23 @@ odp_cos_port_flow_signature(odp_pktio_t pktio_in, odp_cos_flow_set_t req_data_set); @endverbatim +This routine associates a flow set with an input port for flow signature claculation. + @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} +@verbatim /** * 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; -~~~~~ +@endverbatim -@subsecion terms Terms +@subsection terms Terms Terms are the elements of a PMR and are identified by the following enum: @verbatim @@ -737,24 +743,24 @@ Note that some implementations MAY be able to implement tables directly while ot */ 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 */ - }; + 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; @@ -851,6 +857,7 @@ In such an implementation, the classifier will be able to associate a packet alr 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. @@ -885,6 +892,7 @@ 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). @subsection open_issues Open Issues
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- classification_design.dox | 78 ++++++++++++++++++++++++++--------------------- 1 file changed, 43 insertions(+), 35 deletions(-)