Buffer Occupancy

telemetry/specs/INT.mdk

@@ -2,7 +2,7 @@ Title         : In-band Network Telemetry (INT) Dataplane Specification
 Title Note : Working draft. Note: consider using tagged versions for implementation.
 Title Footer: 2018-05-08
 Author : The P4.org Applications Working Group. Contributions from
-Affiliation : *Alibaba, Arista, Barefoot Networks, Dell, Intel, Marvell, Netronome, VMware*
+Affiliation : *Alibaba, Arista, Barefoot Networks, Cisco Systems, Dell, Intel, Marvell, Netronome, VMware*
 Heading depth: 5
 Pdf Latex: xelatex
 Document Class: [11pt]article
@@ -316,7 +316,16 @@ simply leaves those decisions to device vendors.
 
 * Queue occupancy
   - The build-up of traffic in the queue (in bytes, cells, or packets) that the
-INT packet observes in the device while being forwarded.
+INT packet observes in the device while being forwarded. The format of this 4-octet 
+metadata field is switch implementation specific and the YANG model shall describe 
+the format and units of this metadata field in the metadata stack.
+
+* Buffer occupancy
+  - The build-up of traffic in the buffer (in bytes, cells, or packets) that the
+INT packet observes in the device while being forwarded. Use case is when the buffer 
+is shared between multiple queue. The format of this 4-octet metadata field is switch 
+implementation specific and the YANG model shall describe the format and units of this metadata
+field in the metadata stack.
 
 # INT Headers
 
@@ -752,12 +761,12 @@ hop-by-hop INT header must fit in a single Geneve option.
 In this section, we define the format for INT hop-by-hop metadata headers,
 and the metadata itself.
 
-INT Metadata Header and Metadata Stack:
+INT Metadata Header and Metadata Stack (Version = 1):
 `
     0                   1                   2                   3
-    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5     6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-   |  Ver  |Rep|C|E|M|     Reserved      | Hop ML  |RemainingHopCnt|
+   |Ver = 1|Rep|C|E|M|     Reserved      | Hop ML  |RemainingHopCnt|
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |      Instruction Bitmap       |            Reserved           |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
@@ -821,7 +830,7 @@ The original packet must have C bit set to 0.
       switch(es) set the M bit based on knowledge of the network topology
       and "Switch ID, Ingress port ID, Egress port ID" tuples in the INT
       metadata stack.
-  - R: Reserved bits.
+  - R (10b): Reserved bits.
   - Hop ML (5b): Per-hop Metadata Length, the length of metadata in 4-Byte words
     to be inserted at each INT hop.
     - While the largest value of Per-hop Metadata Length is 31, an INT-capable
@@ -854,6 +863,7 @@ each bit corresponds to a specific standard metadata as specified in Section 3.
   - bit5: Egress timestamp
   - bit6: Level 2 Ingress Port ID + Egress Port ID (4 bytes each)
   - bit7: Egress port Tx utilization
+  - bit8: Buffer ID (8 bits) + Buffer Occupancy (24 bits)
   - bit15: Checksum Complement
   - The remaining bits are reserved.
   Each instruction requests 4 bytes of metadata to be inserted at each hop,
@@ -1219,6 +1229,10 @@ header int_egress_port_tx_util_t {
     bit<32> egress_port_tx_util;
 }
 
+header int_b_occupancy_t {
+    bit<32> q_occupancy;
+}
+
 /* standard ethernet/ip/tcp headers */
 header ethernet_t {
     bit<48> dstAddr;
@@ -1279,6 +1293,7 @@ struct headers {
     int_egress_tstamp_t         int_egress_tstamp;
     int_level2_port_ids_t       int_level2_port_ids;
     int_egress_port_tx_util_t   int_egress_port_tx_util;
+    int_b_occupancy_t		int_b_occupancy;
 }
 
 struct empty_metadata_t {
@@ -1610,6 +1625,11 @@ control EgressDeparserImpl(packet_out packet,
             ck.add({hdr.int_egress_port_tx_util.egress_port_tx_util});
         }
 
+        if (hdr.int_b_occupancy.isValid()) {
+            ck.add({
+                    hdr.int_b_occupancy.b_occupancy
+                });
+        }
         if (hdr.tcp.isValid()) {
             ck.add({
                 hdr.tcp.srcPort,
@@ -1656,6 +1676,7 @@ control EgressDeparserImpl(packet_out packet,
         packet.emit(hdr.int_egress_tstamp);
         packet.emit(hdr.int_level2_port_ids);
         packet.emit(hdr.int_egress_port_tx_util);
+        packet.emit(hdr.int_b_occupancy);
     }
 }
 
@@ -2021,6 +2042,23 @@ specific.
 * Queue drop count
   - Total # of packets dropped from the queue
 
+
+The buffer occupancy INT packet observes in the device while being forwarded. Use case is when buffer is
+shared between multiple queue.
+
+* Buffer id
+  - The id of the buffer the device used to serve the INT packet.
+* Instantaneous buffer occupancy
+  - The instantaneous value (in bytes, or cells) of the buffer occupancy the INT
+packet has observed in the device while being forwarded.  The units used need
+not be consistent across an INT domain, but care must be taken to ensure that
+there is a known, consistent mapping of {device, buffer} values to their
+respective unit {bytes, cells}.
+* Average buffer occupancy
+  - The average value (in bytes or cells) of the buffer occupancy 
+the INT packet was observed. The calculation mechanism of this value is device
+specific.
+
 ## Miscellaneous
 
 * Checksum Complement