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>
Reviewed-and-tested-by: Bill Fischofer <bill.fischofer@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>

1 files changed, 73 insertions, 0 deletions

diff --git a/doc/users-guide/users-guide-tm.adoc b/doc/users-guide/users-guide-tm.adoc
index 1182cb246..36fa9ece8 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