[PATCHv2] doc: users-guide: add packet marking documentation

Updates packet marking api documentation to traffic manager user guide

Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org>
---
v2: document format update
 doc/users-guide/users-guide-tm.adoc | 73 +++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

FYI

@Bill: Looks like you did a reply instead of reply-all :)

Regards,
Bala

---------- Forwarded message ----------
From: Bill Fischofer <bill.fischofer@linaro.org>
Date: 16 May 2016 at 20:20
Subject: Re: [PATCHv2] doc: users-guide: add packet marking documentation
To: Balasubramanian Manoharan <bala.manoharan@linaro.org>




On Mon, May 16, 2016 at 2:51 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>


Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org>

>
> ---
> v2: document format update
>  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..e02697b 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
> +
> +The Packet Marking API is used to mark the packet based upon the final packet
> +color assigned to it 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 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 https://www.ietf.org/rfc/rfc2597.txt[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
> +unchanged if the color is GREEN.
> +2). Explicit Congestion Notification protocol per https://www.ietf.org/rfc/rfc3168.txt[RFC 3168], where a router
> +encountering congestion can notify 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 packets that already carry a VLAN tag) of a packet based
> +upon the final packet color assigned to the packet 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 packet OR the eight bit Traffic Class (TC) field of an IPv6 packet can be
> +selectively modified based upon the final color assigned to the packet 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_  _i.e.,_ 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 https://www.ietf.org/rfc/rfc2597.txt[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
> --
> 1.9.1
>

On Monday, May 16, 2016, 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
> <javascript:;>>


Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org>

> ---
> v2: document format update
>  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..e02697b 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
> +
> +The Packet Marking API is used to mark the packet based upon the final
> packet
> +color assigned to it 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
> 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
> https://www.ietf.org/rfc/rfc2597.txt[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
> +unchanged if the color is GREEN.
> +2). Explicit Congestion Notification protocol per
> https://www.ietf.org/rfc/rfc3168.txt[RFC 3168], where a router
> +encountering congestion can notify 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 packets that already carry a VLAN tag) of a packet
> based
> +upon the final packet color assigned to the packet 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 packet OR the eight bit Traffic Class (TC) field of an IPv6 packet
> can be
> +selectively modified based upon the final color assigned to the packet
> 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_  _i.e.,_
> 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
> https://www.ietf.org/rfc/rfc2597.txt[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
> --
> 1.9.1
>
>

Sorry about that. Fixed.

On Monday, May 16, 2016, Bala Manoharan <bala.manoharan@linaro.org> wrote:

> FYI
>
> @Bill: Looks like you did a reply instead of reply-all :)
>
> Regards,
> Bala
>
> ---------- Forwarded message ----------
> From: Bill Fischofer <bill.fischofer@linaro.org <javascript:;>>
> Date: 16 May 2016 at 20:20
> Subject: Re: [PATCHv2] doc: users-guide: add packet marking documentation
> To: Balasubramanian Manoharan <bala.manoharan@linaro.org <javascript:;>>
>
>
>
>
> On Mon, May 16, 2016 at 2:51 AM, Balasubramanian Manoharan
> <bala.manoharan@linaro.org <javascript:;>> wrote:
> >
> > Updates packet marking api documentation to traffic manager user guide
> >
> > Signed-off-by: Balasubramanian Manoharan <bala.manoharan@linaro.org
> <javascript:;>>
>
>
> Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org
> <javascript:;>>
>
> >
> > ---
> > v2: document format update
> >  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..e02697b 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
> > +
> > +The Packet Marking API is used to mark the packet based upon the final
> packet
> > +color assigned to it 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
> 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
> https://www.ietf.org/rfc/rfc2597.txt[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
> > +unchanged if the color is GREEN.
> > +2). Explicit Congestion Notification protocol per
> https://www.ietf.org/rfc/rfc3168.txt[RFC 3168], where a router
> > +encountering congestion can notify 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 packets that already carry a VLAN tag) of a packet
> based
> > +upon the final packet color assigned to the packet 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 packet OR the eight bit Traffic Class (TC) field of an IPv6 packet
> can be
> > +selectively modified based upon the final color assigned to the packet
> 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_  _i.e.,_
> 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
> https://www.ietf.org/rfc/rfc2597.txt[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
> > --
> > 1.9.1
> >
>

Merged,
Maxim.

On 05/17/16 05:40, Bill Fischofer wrote:
> On Monday, May 16, 2016, 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
>> <javascript:;>>
>
> Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org>
>
>> ---
>> v2: document format update
>>   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..e02697b 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
>> +
>> +The Packet Marking API is used to mark the packet based upon the final
>> packet
>> +color assigned to it 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
>> 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
>> https://www.ietf.org/rfc/rfc2597.txt[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
>> +unchanged if the color is GREEN.
>> +2). Explicit Congestion Notification protocol per
>> https://www.ietf.org/rfc/rfc3168.txt[RFC 3168], where a router
>> +encountering congestion can notify 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 packets that already carry a VLAN tag) of a packet
>> based
>> +upon the final packet color assigned to the packet 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 packet OR the eight bit Traffic Class (TC) field of an IPv6 packet
>> can be
>> +selectively modified based upon the final color assigned to the packet
>> 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_  _i.e.,_
>> 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
>> https://www.ietf.org/rfc/rfc2597.txt[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
>> --
>> 1.9.1
>>
>>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> https://lists.linaro.org/mailman/listinfo/lng-odp