| Message ID | 1463116983-26462-1-git-send-email-bala.manoharan@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
On Fri, May 13, 2016 at 12:23 AM, Balasubramanian Manoharan < bala.manoharan@linaro.org> wrote: > Updates packet marking api documentation to traffic manager user guide > > Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org> > --- > doc/users-guide/users-guide-tm.adoc | 73 > +++++++++++++++++++++++++++++++++++++ > 1 file changed, 73 insertions(+) > > diff --git a/doc/users-guide/users-guide-tm.adoc > b/doc/users-guide/users-guide-tm.adoc > index 12685b2..0bbbb6c 100644 > --- a/doc/users-guide/users-guide-tm.adoc > +++ b/doc/users-guide/users-guide-tm.adoc > @@ -263,6 +263,79 @@ settings for any TM system, though in most cases a TM > system can (and should) > be created/instantiated with smaller values, since lower values will often > result in faster operation and/or less memory used. > > +==== Packet Marking > + > +Packet Marking API is used to mark the packet based upon the final packet > color > grammar: The Packet Marking API > +assigned to the packet when it reaches the egress node. > +This is an optional feature and if available on the platform is used to > reflect > +the packet color on IPv4/IPv6 DiffServ filed in accordance with RFC 2474. > Since this results in an HTML doc, RFC's should be annotated as hyperlinks, e.g.: https://www.ietf.org/rfc/rfc2474.txt[RFC 2474] > +There are three different packet marking fields supported they are, > +1). Assured forwarding in accordance with RFC 2597, the DSCP is marked to > https://www.ietf.org/rfc/rfc2597.txt[RFC 2597] > +set the packet Drop precedence in accordance with the color, i.e High Drop > +precedence for RED, Medium Drop precedence for YELLOW and leave the DSCP > +unchangesd if the color is GREEN. > Typo: unchanged > +2). Explicit Congestion Notification protocol per RFC 3168, where a router > https://www.ietf.org/rfc/rfc3168.txt[RFC 3168] > +encountering congestion can notifiy it by setting the lower 2 bits in > Typo: notify > +DiffServ field to "11" Congestion Encountered code, which will ultimately > +reduce the transmission rate of the packet sender. > +3). In IEEE 802.1q VLAN tag header contains a DE - Drop Eligibility bit > for > +marking a packet for Downstream switches, and is valid for Ethernet packet > +containing a VLAN tag. > + > +RFC 3168 is only valid for TCP packets whereas RFC 2597 is valid for > IPv4/IPv6 > +traffic. > + > +The values are set per color and hence the implementation may support > these > +parameters only for a specific colors. marking_colors_supported field in > +capabilities structure can be used to check which colors are supported for > +marking. > + > +Vlan Marking. > ===== Vlan Marking [These are sub-sections and should be annotated as such] > + > +This vlan marking is used to enable the drop eligibility on the packet > +based on the packet color. If drop eligibility is enabled then the > +implementation will set the one bit VLAN Drop Eligibility Indicator (DEI) > +field (but only for pkts that already carry a VLAN tag) of a packet based > I'd spell out packets here. The use of the abbreviation should only be for APIs that do so. > +upon the final pkt color assigned to the pkt when it reaches the egress > Again, packet, not pkt here. > +node. When drop_eligible_enabled is false, then the given color has > +no effect on the VLAN fields. See IEEE 802.1q for more details. > Since IEEE docs are protected, best to just link this one to the Wikipedia article on it: See https://en.wikipedia.org/wiki/IEEE_802.1Q[IEEE 802.1q] for more details. > +vlan_marking_supported boolean in capability structure indicates whether > this > `vlan_marking_supported` > +feature is supported by the implementation. > + > +Explicit Congestion Notification Marking. > ===== Explicit Congestion Notification Marking [No period follows subsection title] > + > +The odp_tm_ecn_marking() function allows one to configure the TM > Annotate APIs with backticks `odp_tm_ecn_marking()` to make them monospace font for consistency with the rest of the User Guide. > +egress so that the two bit ECN subfield of the eight bit TOS field of an > +IPv4 pkt OR the eight bit Traffic Class (TC) field of an IPv6 pkt can be > packet, not pkt > +selectively modified based upon the final color assigned to the pkt when > it > packet > +reaches the egress. Note that the IPv4 header checksum will be updated - > +but only if the IPv4 TOS field actually changes as a result of this > +setting or the odp_tm_drop_prec_marking setting. For IPv6, since there is > `odp_tm_drop_prec_marking()` > +no header checksum, nothing needs to be done. If ECN is enabled for a > +particular color then ECN subfield will be set to ECN_CE ie congestion > i.e., (periods are required here. If you want to be grammatically perfect, these latinisms should be italicized and followed by a comma: _i.e.,_ ) > +experienced. > +ecn_marking_supported boolean in capability structure indicates whether > this > `ecn_marking_supported` > +feature is supported by the implementation. > + > +Drop Precedence Marking. > ===== Drop Precedence Marking [No period follows subsection heading] + > +The Drop precedence marking allows one to configure the TM > +egress to support Assured forwarding in accordance with RFC 2597. > +The Drop Precedence bits are contained within the six bit Differentiated > +Services Code Point subfield of the IPv4 TOS field or the IPv6 Traffic > +Class (TC) field. Specifically the Drop Precedence sub-subfield can be > +accessed with a DSCP bit mask of 0x06. When enabled for a given color, > +these two bits will be set to Medium Drop Precedence (value 0x4) if the > +color is ODP_PACKET_YELLOW, set to High Drop Precedence (value 0x6) if > +the color is ODP_PACKET_RED. > + > +Note that the IPv4 header checksum will be updated - but only if the > +IPv4 TOS field actually changes as a result of this setting or the > +odp_tm_ecn_marking setting. For IPv6, since there is no header checksum, > `odp_tm_ecn_marking()` > +nothing else needs to be done. > +drop_prec_marking_supported boolean in capability structure indicates > whether > The `drop_prec_marking_supported` boolean in the capability... > +this feature is supported by the implementation. > + > === Examples > > .Create a tm_node chain for two nodes and associate the scheduler > -- > 1.9.1 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
Hi, I have incorporated all the comments in V2 except adding reference for IEEE802.1Q I am little skeptical about adding a wikipedia page as reference. Regards, Bala On 15 May 2016 at 03:09, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > On Fri, May 13, 2016 at 12:23 AM, Balasubramanian Manoharan < > bala.manoharan@linaro.org> wrote: > >> Updates packet marking api documentation to traffic manager user guide >> >> Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org> >> --- >> doc/users-guide/users-guide-tm.adoc | 73 >> +++++++++++++++++++++++++++++++++++++ >> 1 file changed, 73 insertions(+) >> >> diff --git a/doc/users-guide/users-guide-tm.adoc >> b/doc/users-guide/users-guide-tm.adoc >> index 12685b2..0bbbb6c 100644 >> --- a/doc/users-guide/users-guide-tm.adoc >> +++ b/doc/users-guide/users-guide-tm.adoc >> @@ -263,6 +263,79 @@ settings for any TM system, though in most cases a >> TM system can (and should) >> be created/instantiated with smaller values, since lower values will >> often >> result in faster operation and/or less memory used. >> >> +==== Packet Marking >> + >> +Packet Marking API is used to mark the packet based upon the final >> packet color >> > > grammar: The Packet Marking API > > >> +assigned to the packet when it reaches the egress node. >> +This is an optional feature and if available on the platform is used to >> reflect >> +the packet color on IPv4/IPv6 DiffServ filed in accordance with RFC 2474. >> > > Since this results in an HTML doc, RFC's should be annotated as > hyperlinks, e.g.: > https://www.ietf.org/rfc/rfc2474.txt[RFC 2474] > > >> +There are three different packet marking fields supported they are, >> +1). Assured forwarding in accordance with RFC 2597, the DSCP is marked to >> > > https://www.ietf.org/rfc/rfc2597.txt[RFC 2597] > > >> +set the packet Drop precedence in accordance with the color, i.e High >> Drop >> +precedence for RED, Medium Drop precedence for YELLOW and leave the DSCP >> +unchangesd if the color is GREEN. >> > > Typo: unchanged > > >> +2). Explicit Congestion Notification protocol per RFC 3168, where a >> router >> > > https://www.ietf.org/rfc/rfc3168.txt[RFC 3168] > > >> +encountering congestion can notifiy it by setting the lower 2 bits in >> > > Typo: notify > > >> +DiffServ field to "11" Congestion Encountered code, which will ultimately >> +reduce the transmission rate of the packet sender. >> +3). In IEEE 802.1q VLAN tag header contains a DE - Drop Eligibility bit >> for >> +marking a packet for Downstream switches, and is valid for Ethernet >> packet >> +containing a VLAN tag. >> + >> +RFC 3168 is only valid for TCP packets whereas RFC 2597 is valid for >> IPv4/IPv6 >> +traffic. >> + >> +The values are set per color and hence the implementation may support >> these >> +parameters only for a specific colors. marking_colors_supported field in >> +capabilities structure can be used to check which colors are supported >> for >> +marking. >> + >> +Vlan Marking. >> > > ===== Vlan Marking > [These are sub-sections and should be annotated as such] > > >> + >> +This vlan marking is used to enable the drop eligibility on the packet >> +based on the packet color. If drop eligibility is enabled then the >> +implementation will set the one bit VLAN Drop Eligibility Indicator (DEI) >> +field (but only for pkts that already carry a VLAN tag) of a packet based >> > > I'd spell out packets here. The use of the abbreviation should only be for > APIs that do so. > > >> +upon the final pkt color assigned to the pkt when it reaches the egress >> > > Again, packet, not pkt here. > > >> +node. When drop_eligible_enabled is false, then the given color has >> +no effect on the VLAN fields. See IEEE 802.1q for more details. >> > > Since IEEE docs are protected, best to just link this one to the Wikipedia > article on it: > See https://en.wikipedia.org/wiki/IEEE_802.1Q[IEEE 802.1q] for more > details. > > >> +vlan_marking_supported boolean in capability structure indicates whether >> this >> > > `vlan_marking_supported` > > >> +feature is supported by the implementation. >> + >> +Explicit Congestion Notification Marking. >> > > ===== Explicit Congestion Notification Marking > [No period follows subsection title] > > >> + >> +The odp_tm_ecn_marking() function allows one to configure the TM >> > > Annotate APIs with backticks `odp_tm_ecn_marking()` to make them monospace > font for consistency with the rest of the User Guide. > > >> +egress so that the two bit ECN subfield of the eight bit TOS field of an >> +IPv4 pkt OR the eight bit Traffic Class (TC) field of an IPv6 pkt can be >> > > packet, not pkt > > >> +selectively modified based upon the final color assigned to the pkt when >> it >> > > packet > > >> +reaches the egress. Note that the IPv4 header checksum will be updated - >> +but only if the IPv4 TOS field actually changes as a result of this >> +setting or the odp_tm_drop_prec_marking setting. For IPv6, since there >> is >> > > `odp_tm_drop_prec_marking()` > > >> +no header checksum, nothing needs to be done. If ECN is enabled for a >> +particular color then ECN subfield will be set to ECN_CE ie congestion >> > > i.e., (periods are required here. If you want to be grammatically > perfect, these latinisms should be italicized and followed by a comma: > _i.e.,_ ) > > >> +experienced. >> +ecn_marking_supported boolean in capability structure indicates whether >> this >> > > `ecn_marking_supported` > > >> +feature is supported by the implementation. >> + >> +Drop Precedence Marking. >> > > ===== Drop Precedence Marking > [No period follows subsection heading] > > + >> +The Drop precedence marking allows one to configure the TM >> +egress to support Assured forwarding in accordance with RFC 2597. >> +The Drop Precedence bits are contained within the six bit Differentiated >> +Services Code Point subfield of the IPv4 TOS field or the IPv6 Traffic >> +Class (TC) field. Specifically the Drop Precedence sub-subfield can be >> +accessed with a DSCP bit mask of 0x06. When enabled for a given color, >> +these two bits will be set to Medium Drop Precedence (value 0x4) if the >> +color is ODP_PACKET_YELLOW, set to High Drop Precedence (value 0x6) if >> +the color is ODP_PACKET_RED. >> + >> +Note that the IPv4 header checksum will be updated - but only if the >> +IPv4 TOS field actually changes as a result of this setting or the >> +odp_tm_ecn_marking setting. For IPv6, since there is no header checksum, >> > > `odp_tm_ecn_marking()` > > >> +nothing else needs to be done. >> +drop_prec_marking_supported boolean in capability structure indicates >> whether >> > > The `drop_prec_marking_supported` boolean in the capability... > > >> +this feature is supported by the implementation. >> + >> === Examples >> >> .Create a tm_node chain for two nodes and associate the scheduler >> -- >> 1.9.1 >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > >
diff --git a/doc/users-guide/users-guide-tm.adoc b/doc/users-guide/users-guide-tm.adoc index 12685b2..0bbbb6c 100644 --- a/doc/users-guide/users-guide-tm.adoc +++ b/doc/users-guide/users-guide-tm.adoc @@ -263,6 +263,79 @@ settings for any TM system, though in most cases a TM system can (and should) be created/instantiated with smaller values, since lower values will often result in faster operation and/or less memory used. +==== Packet Marking + +Packet Marking API is used to mark the packet based upon the final packet color +assigned to the packet when it reaches the egress node. +This is an optional feature and if available on the platform is used to reflect +the packet color on IPv4/IPv6 DiffServ filed in accordance with RFC 2474. +There are three different packet marking fields supported they are, +1). Assured forwarding in accordance with RFC 2597, the DSCP is marked to +set the packet Drop precedence in accordance with the color, i.e High Drop +precedence for RED, Medium Drop precedence for YELLOW and leave the DSCP +unchangesd if the color is GREEN. +2). Explicit Congestion Notification protocol per RFC 3168, where a router +encountering congestion can notifiy it by setting the lower 2 bits in +DiffServ field to "11" Congestion Encountered code, which will ultimately +reduce the transmission rate of the packet sender. +3). In IEEE 802.1q VLAN tag header contains a DE - Drop Eligibility bit for +marking a packet for Downstream switches, and is valid for Ethernet packet +containing a VLAN tag. + +RFC 3168 is only valid for TCP packets whereas RFC 2597 is valid for IPv4/IPv6 +traffic. + +The values are set per color and hence the implementation may support these +parameters only for a specific colors. marking_colors_supported field in +capabilities structure can be used to check which colors are supported for +marking. + +Vlan Marking. + +This vlan marking is used to enable the drop eligibility on the packet +based on the packet color. If drop eligibility is enabled then the +implementation will set the one bit VLAN Drop Eligibility Indicator (DEI) +field (but only for pkts that already carry a VLAN tag) of a packet based +upon the final pkt color assigned to the pkt when it reaches the egress +node. When drop_eligible_enabled is false, then the given color has +no effect on the VLAN fields. See IEEE 802.1q for more details. +vlan_marking_supported boolean in capability structure indicates whether this +feature is supported by the implementation. + +Explicit Congestion Notification Marking. + +The odp_tm_ecn_marking() function allows one to configure the TM +egress so that the two bit ECN subfield of the eight bit TOS field of an +IPv4 pkt OR the eight bit Traffic Class (TC) field of an IPv6 pkt can be +selectively modified based upon the final color assigned to the pkt when it +reaches the egress. Note that the IPv4 header checksum will be updated - +but only if the IPv4 TOS field actually changes as a result of this +setting or the odp_tm_drop_prec_marking setting. For IPv6, since there is +no header checksum, nothing needs to be done. If ECN is enabled for a +particular color then ECN subfield will be set to ECN_CE ie congestion +experienced. +ecn_marking_supported boolean in capability structure indicates whether this +feature is supported by the implementation. + +Drop Precedence Marking. + +The Drop precedence marking allows one to configure the TM +egress to support Assured forwarding in accordance with RFC 2597. +The Drop Precedence bits are contained within the six bit Differentiated +Services Code Point subfield of the IPv4 TOS field or the IPv6 Traffic +Class (TC) field. Specifically the Drop Precedence sub-subfield can be +accessed with a DSCP bit mask of 0x06. When enabled for a given color, +these two bits will be set to Medium Drop Precedence (value 0x4) if the +color is ODP_PACKET_YELLOW, set to High Drop Precedence (value 0x6) if +the color is ODP_PACKET_RED. + +Note that the IPv4 header checksum will be updated - but only if the +IPv4 TOS field actually changes as a result of this setting or the +odp_tm_ecn_marking setting. For IPv6, since there is no header checksum, +nothing else needs to be done. +drop_prec_marking_supported boolean in capability structure indicates whether +this feature is supported by the implementation. + === Examples .Create a tm_node chain for two nodes and associate the scheduler
Updates packet marking api documentation to traffic manager user guide Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org> --- doc/users-guide/users-guide-tm.adoc | 73 +++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+)