Re: [lng-odp] [API-NEXT PATCH] doc: user-guide documentation for classification
On 16 February 2016 at 06:52, Bala Manoharan wrote: > Hi, > > On 15 February 2016 at 20:52, Christophe Milard < > christophe.mil...@linaro.org> wrote: > >> >> >> On 15 February 2016 at 15:12, Balasubramanian Manoharan < >> bala.manoha...@linaro.org> wrote: >> >>> Adds user-guide documentation for classification module >>> >>> Signed-off-by: Balasubramanian Manoharan >>> --- >>> doc/users-guide/users-guide-cls.adoc | 220 >>> +++ >>> 1 file changed, 220 insertions(+) >>> create mode 100644 doc/users-guide/users-guide-cls.adoc >>> >>> diff --git a/doc/users-guide/users-guide-cls.adoc >>> b/doc/users-guide/users-guide-cls.adoc >>> new file mode 100644 >>> index 000..3089f86 >>> --- /dev/null >>> +++ b/doc/users-guide/users-guide-cls.adoc >>> @@ -0,0 +1,220 @@ >>> +== Classification \(CLS) >>> + >>> +ODP is a framework for software-based packet forwarding/filtering >>> applications, >>> +and the purpose of the Packet Classification 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. >>> + >>> +=== Functional Description >>> + >>> +Following is the functionality that is required of the classification >>> 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 aznd provide context for the API. In reality, >>> implementations may >>> >> >> typo: "and", not aznd >> > > Good catch :) > >> >> >>> +execute many of these steps concurrently, or in different order while >>> +maintaining the evident dependencies: >>> + >>> +1. Apply a set of classification rules to the header of an incoming >>> packet, >>> +identify the header fields, e.g. ,ethertype, IP version, IP protocol, >>> transport >>> +layer port numbers, IP DiffServ, VLAN id, 802.1p priority. >>> + >>> +2. Store these fields as packet meta data for application use, and for >>> the >>> +remainder of parser operations. The odp_pktio is also stored as one of >>> the meta >>> +data fields for subsequent use. >>> + >>> +3. Compute an odp_cos (Class of Service) value from a subset of >>> supported fields >>> +from 1) above. >>> + >>> +4. Based on the odp_cos from 3) above, select the odp_queue through >>> which the >>> +packet is delivered to the application. >>> + >>> +5. 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 odp_cos selection in step 3 to a class of >>> service >>> +designated for errored packets. >>> + >>> +6. Based on the odp_cos from 3) above, select the odp_buffer_pool that >>> should be >>> +used to acquire a buffer to store the packet data and meta data. >>> + >>> +7. Allocate a buffer from odp_buffer_pool selected in 6) above and >>> logically[1] >>> +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. >>> + >>> +8. Enqueue the buffer into the 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 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 odp_buffe
Re: [lng-odp] [API-NEXT PATCH] doc: user-guide documentation for classification
Hi, On 15 February 2016 at 20:52, Christophe Milard < christophe.mil...@linaro.org> wrote: > > > On 15 February 2016 at 15:12, Balasubramanian Manoharan < > bala.manoha...@linaro.org> wrote: > >> Adds user-guide documentation for classification module >> >> Signed-off-by: Balasubramanian Manoharan >> --- >> doc/users-guide/users-guide-cls.adoc | 220 >> +++ >> 1 file changed, 220 insertions(+) >> create mode 100644 doc/users-guide/users-guide-cls.adoc >> >> diff --git a/doc/users-guide/users-guide-cls.adoc >> b/doc/users-guide/users-guide-cls.adoc >> new file mode 100644 >> index 000..3089f86 >> --- /dev/null >> +++ b/doc/users-guide/users-guide-cls.adoc >> @@ -0,0 +1,220 @@ >> +== Classification \(CLS) >> + >> +ODP is a framework for software-based packet forwarding/filtering >> applications, >> +and the purpose of the Packet Classification 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. >> + >> +=== Functional Description >> + >> +Following is the functionality that is required of the classification >> 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 aznd provide context for the API. In reality, implementations >> may >> > > typo: "and", not aznd > Good catch :) > > >> +execute many of these steps concurrently, or in different order while >> +maintaining the evident dependencies: >> + >> +1. Apply a set of classification rules to the header of an incoming >> packet, >> +identify the header fields, e.g. ,ethertype, IP version, IP protocol, >> transport >> +layer port numbers, IP DiffServ, VLAN id, 802.1p priority. >> + >> +2. Store these fields as packet meta data for application use, and for >> the >> +remainder of parser operations. The odp_pktio is also stored as one of >> the meta >> +data fields for subsequent use. >> + >> +3. Compute an odp_cos (Class of Service) value from a subset of >> supported fields >> +from 1) above. >> + >> +4. Based on the odp_cos from 3) above, select the odp_queue through >> which the >> +packet is delivered to the application. >> + >> +5. 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 odp_cos selection in step 3 to a class of >> service >> +designated for errored packets. >> + >> +6. Based on the odp_cos from 3) above, select the odp_buffer_pool that >> should be >> +used to acquire a buffer to store the packet data and meta data. >> + >> +7. Allocate a buffer from odp_buffer_pool selected in 6) above and >> logically[1] >> +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. >> + >> +8. Enqueue the buffer into the 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 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 odp_buffer_pool instances, one for each >> PCP >> +priority level, and 8 odp_queue instances one per priority level. >> Incoming >> +packets will be inspected for a VLAN header; the PCP field will be >> extracted, >
Re: [lng-odp] [API-NEXT PATCH] doc: user-guide documentation for classification
On 15 February 2016 at 15:12, Balasubramanian Manoharan < bala.manoha...@linaro.org> wrote: > Adds user-guide documentation for classification module > > Signed-off-by: Balasubramanian Manoharan > --- > doc/users-guide/users-guide-cls.adoc | 220 > +++ > 1 file changed, 220 insertions(+) > create mode 100644 doc/users-guide/users-guide-cls.adoc > > diff --git a/doc/users-guide/users-guide-cls.adoc > b/doc/users-guide/users-guide-cls.adoc > new file mode 100644 > index 000..3089f86 > --- /dev/null > +++ b/doc/users-guide/users-guide-cls.adoc > @@ -0,0 +1,220 @@ > +== Classification \(CLS) > + > +ODP is a framework for software-based packet forwarding/filtering > applications, > +and the purpose of the Packet Classification 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. > + > +=== Functional Description > + > +Following is the functionality that is required of the classification > 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 aznd provide context for the API. In reality, implementations > may > typo: "and", not aznd > +execute many of these steps concurrently, or in different order while > +maintaining the evident dependencies: > + > +1. Apply a set of classification rules to the header of an incoming > packet, > +identify the header fields, e.g. ,ethertype, IP version, IP protocol, > transport > +layer port numbers, IP DiffServ, VLAN id, 802.1p priority. > + > +2. Store these fields as packet meta data for application use, and for the > +remainder of parser operations. The odp_pktio is also stored as one of > the meta > +data fields for subsequent use. > + > +3. Compute an odp_cos (Class of Service) value from a subset of supported > fields > +from 1) above. > + > +4. Based on the odp_cos from 3) above, select the odp_queue through which > the > +packet is delivered to the application. > + > +5. 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 odp_cos selection in step 3 to a class of service > +designated for errored packets. > + > +6. Based on the odp_cos from 3) above, select the odp_buffer_pool that > should be > +used to acquire a buffer to store the packet data and meta data. > + > +7. Allocate a buffer from odp_buffer_pool selected in 6) above and > logically[1] > +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. > + > +8. Enqueue the buffer into the 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 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 odp_buffer_pool instances, one for each > PCP > +priority level, and 8 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
[lng-odp] [API-NEXT PATCH] doc: user-guide documentation for classification
Adds user-guide documentation for classification module Signed-off-by: Balasubramanian Manoharan --- doc/users-guide/users-guide-cls.adoc | 220 +++ 1 file changed, 220 insertions(+) create mode 100644 doc/users-guide/users-guide-cls.adoc diff --git a/doc/users-guide/users-guide-cls.adoc b/doc/users-guide/users-guide-cls.adoc new file mode 100644 index 000..3089f86 --- /dev/null +++ b/doc/users-guide/users-guide-cls.adoc @@ -0,0 +1,220 @@ +== Classification \(CLS) + +ODP is a framework for software-based packet forwarding/filtering applications, +and the purpose of the Packet Classification 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. + +=== Functional Description + +Following is the functionality that is required of the classification 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 aznd provide context for the API. In reality, implementations may +execute many of these steps concurrently, or in different order while +maintaining the evident dependencies: + +1. Apply a set of classification rules to the header of an incoming packet, +identify the header fields, e.g. ,ethertype, IP version, IP protocol, transport +layer port numbers, IP DiffServ, VLAN id, 802.1p priority. + +2. Store these fields as packet meta data for application use, and for the +remainder of parser operations. The odp_pktio is also stored as one of the meta +data fields for subsequent use. + +3. Compute an odp_cos (Class of Service) value from a subset of supported fields +from 1) above. + +4. Based on the odp_cos from 3) above, select the odp_queue through which the +packet is delivered to the application. + +5. 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 odp_cos selection in step 3 to a class of service +designated for errored packets. + +6. Based on the odp_cos from 3) above, select the odp_buffer_pool that should be +used to acquire a buffer to store the packet data and meta data. + +7. Allocate a buffer from odp_buffer_pool selected in 6) above and logically[1] +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. + +8. Enqueue the buffer into the 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 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 odp_buffer_pool instances, one for each PCP +priority level, and 8 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. + +=== Class of Servi
