Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
Instrumentation - Buffer Statistics Tracking (BST)

Buffer Statistics Tracking (BST) is an instrumentation feature of underlying silicon in ICOS. The main purpose of this feature is to fetch current buffer usage for packets in switch's buffer. It helps in finding reason for packet drop and possibly avoiding any such future congestion.

BST OpEN API

This document provides a brief description of Buffer Statistics Tracking (BST) OpEN APIs. The BST OpEN APIs allow processes outside of the ICOS main process (switchdrvr) access to the underlying silicon's buffer usage statistics and ability to receive events when any particular statistics crosses configured threshold.

Example C Application instru_example

Initialization

In the main function, the sample application initializes the OpEN API RPC service by calling openapiClientRegister() and waits for the RPC service in switchdrvr to start. A Client Handle is returned by openapiClientRegister() which is used while invoking the OpEN APIs. The application then exercises the associated OpEN APIs and logs informational and/or error messages on the console. The example application runs to its completion and exits.

instru_example

instru_example.c is a sample application that demonstrates the use of the BST OpEN APIs. instru_example is started from the command line. The instru_example is quite extensive that it demonstrates all the BST features. The example first reads the ASIC capabilities and prints them. Then it tries to enable BST feature on the platform. If BST cannot be enabled for whatever reason, the test will end. Once BST is successfully enabled, it tries to read the buffer statistics (counter values) of various resources such as IPPG (ingress port priority group) , ESP (egress service pool). The example covers all resources both device, ingress and egress side.

After statistics reading is complete, the example program tries to set thresholds. On successful application of thresholds the program tries to read (retrieve) the applied threshold, to make sure the threshold is applied on the ASIC.

The example program uses sample port, queue numbers. The users must select the ports(and queue numbers) where the traffic is actively flowing, so that some non-zero buffers counters can be observed.

Once all the threshold configuration is verified, then it will register a threshold call back function, to check a threshold breach event. After that it de-registers the threshold call back function, disables BST and exits.

The following is a list and sequence of these tests for the BST sanity tests.

Sample Output (LiNe/LinuxHost platform)

Begin Sanity tests... Testing API – openapiBstAsicCapabilityGet
------------------------------------------------—

Basic ASIC Capabilities
-------------------------------—
Number of ports 104
Number of unicast queues 2960
Number of unicast queues groups 128
Number of multicast queues 1040
Number of service pools 4
Number of common pools 1
Number of CPU queues 8
Number of RQE queues 11
Number of RQE pools 4
Number of priority groups 8


Testing API – openapiPortMappingGet
----------------------------------------—
Ports mapped to this ASIC 0/1, 0/33, 0/34, 0/35, 0/36, 0/2, 0/0, 0/0, 0/0, 0/3, 0/0, 0/0, 0/0, 0/4, 0/0, 0/0, 0/0, 0/5, 0/0, 0/0, 0/0, 0/6, 0/0, 0/0, 0/0, 0/7, 0/0, 0/0, 0/0, 0/8, 0/0, 0/0, 0/0, 0/9, 0/0, 0/0, 0/0, 0/10, 0/0, 0/0, 0/0, 0/11, 0/0, 0/0, 0/0, 0/12, 0/0, 0/0, 0/0, 0/13, 0/14, 0/15, 0/16, 0/97, 0/98, 0/99, 0/100, 0/18, 0/0, 0/0, 0/0, 0/19, 0/0, 0/0, 0/0, 0/20, 0/0, 0/0, 0/0, 0/21, 0/0, 0/0, 0/0, 0/22, 0/0, 0/0, 0/0, 0/23, 0/0, 0/0, 0/0, 0/24, 0/0, 0/0, 0/0, 0/25, 0/0, 0/0, 0/0, 0/26, 0/0, 0/0, 0/0, 0/27, 0/0, 0/0, 0/0, 0/28, 0/0, 0/0, 0/0, 0/29, 0/30, 0/31,


Testing API – openapiLagTranslateToNotation
------------------------------------------—
Lag string for lag number=0 is 3/6

Testing API – openapiBstConfigSet
---------------------------------—
BST configuration for current and peak successful
BST configuration to enable and disable successful


Testing API – openapiBstDeviceDataGet
------------------------------------—
Device buffer count = 42431


Testing API – openapiBstIspDataGet
---------------------------------—
Ingress service pool buffer count = 42431


Testing API – openapiBstIppgDataGet
------------------------------------—
Ingress Port priority group, port = 1


Priority group UM Share count UM Headroom count
-------------- -------------- -----------------
0 0 0
1 0 0
2 0 0
3 0 0
4 0 0
5 0 0
6 18424 0
7 0 0



Ingress Port priority group, port = 2


Priority group UM Share count UM Headroom count
-------------- -------------- -----------------
0 0 0
1 0 0
2 0 0
3 0 0
4 0 0
5 0 0
6 0 0
7 0 0



Ingress Port priority group, port = 3


Priority group UM Share count UM Headroom count
-------------- -------------- -----------------
0 0 0
1 0 0
2 0 0
3 0 0
4 0 0
5 0 0
6 9767 0
7 0 0





Testing API – openapiBstIpspDataGet
------------------------------------—
Ingress Port service pool, port = 1
Unicast Multicast shared buffer = 0


Ingress Port service pool, port = 2
Unicast Multicast shared buffer = 9767




Testing API – openapiBstEpspDataGet
---------------------------------—
Egress Port service pool buffer counts, port = 1
Unicast shared = 0
Unicast Multicast shared = 0
Multicast shared = 0
Multicast shared queue entries = 0

Egress Port service pool buffer counts, port = 2
Unicast shared = 0
Unicast Multicast shared = 0
Multicast shared = 0
Multicast shared queue entries = 0

Egress Port service pool buffer counts, port = 2
Unicast shared = 0
Unicast Multicast shared = 0
Multicast shared = 0
Multicast shared queue entries = 0



Testing API – openapiBstEspDataGet
---------------------------------—
Buffer counts of Egress service poool
Unicast Multicast shared = 131071
Multicast shared = 131071
Multicast shared queue entries = 0


Testing API – openapiBstEucqDataGet
---------------------------------—
Egress unicast queue = 440 associated port = 56 buffer count = 14710

Egress unicast queue = 441 associated port = 56 buffer count = 11845



Testing API – openapiBstEmcqDataGet
---------------------------------—
Egress multicast queue = 15 associated port = 2 buffer count = 0 queue entries = 0

Egress multicast queue = 22 associated port = 3 buffer count = 0 queue entries = 0

Testing API – openapiBstCpuqDataGet
---------------------------------—
CPU queue = 2 cpu buffer count = 0 cpu queue entries = 0

CPU queue = 4 cpu buffer count = 0 cpu queue entries = 0



Testing API – openapiBstRqeqDataGet
---------------------------------—
RQE queue = 8 rqe buffer count = 0 rqe queue entries = 0

RQE queue = 5 rqe buffer count = 0 rqe queue entries = 0



Testing the thresholds of various resorces
---------------------------------------—

Testing API – openapiBstDeviceThresholdSet
Device threshold configuration succeeded.


Testing API – openapiBstIppgThresholdSet
Ingress port priority group threshold configuration failed.


Testing API – openapiBstIpspThresholdSet
Ingress per port service pool threshold configuration failed.


Testing API – openapiBstIspThresholdSet
Ingress service pool threshold configuration succeeded.


Testing API – openapiBstEpspThresholdSet
Egress per port service pool threshold configuration failed.


Testing API – openapiBstEspThresholdSet
Egress service pool threshold configuration failed.


Testing API – openapiBstEucqThresholdSet
Egress unicast queue threshold configuration failed.


Testing API – openapiBstEucqgThresholdSet


Testing API – openapiBstEmcqThresholdSet
Egress multicast queue threshold configuration succeeded.


Testing API – openapiBstCpuqThresholdSet
Egress multicast queue threshold configuration succeeded.


Testing API – openapiBstRqeqThresholdSet
Egress RQE queue threshold configuration succeeded.


Reading of entire snapshot of all buffers succeeded
Clearing of thresholds succeeded
Clearing of statistics succeeded
Waiting for 30 seconds for threshold to trigger

Complete.

Example Python Application instru_example

In addition to instru_example.c, a python implementation has also been provided for demonstration purposes. This python instru_example.py script essentially duplicates some of the instru_example.c implementation.