Merge branch 'master' into eruan-srv6

doc/crm/Generic_SAI_Extensions_CRM.md

@@ -0,0 +1,70 @@
+# Generic SAI Extension Critical Resource Monitoring (CRM)
+
+## Table of Content
+- [Introduction](#Itroduction)
+- [Scope](#Scope)
+- [Requirements](#Requirements)
+- [Highlevel Design](#Highlevel-Design)
+- [Unit Test Automation](#Unit-Test-Automation)
+
+## Revision
+| Rev  |   Date    |                        Author                        | Change Description                 |
+| :--: | :-------: | :--------------------------------------------------: | :--------------------------------: |
+| 0.1  | 1/17/2023 | Intel                                                |  Initial Revision                  |
+
+## Introduction <a name="Introduction"></a>
+High Level Design for critical resource monitoring (crm) in SONiC for Generic SAI Extension tables.
+
+## Scope <a name="Scope"></a>
+The scope of the design is to publish CRM counts, for Generic SAI Extension tables, into the COUNTERS-DB. Support for existing generic crm configurations that is applicable to all resources, like polling interval, is in the scope of this document. No additional configuration specific to extension tables resource is in the scope.
+
+## Requirements <a name="Requirements"></a>
+- Support reporting of used counts
+- Support reporting of available counts
+- Support default watermark checks
+
+## Highlevel Design <a name="Highlevel-Design"></a>
+New crm resource type enum - CrmResourceType::CRM_EXT_TABLE
+  - Each extension table specific stats are stored in,
+    m_resourcesMap.at(CrmResourceType::CRM_EXT_TABLE).countersMap[EXT_TABLE_STATS:"table-name"]
+
+All existing generic crm configuration, like polling-interval, is applicable to this new crm type.
+
+Currently supported default watermark check for other existing crm resource types is also applicable to every extension table under this new crm type.
+
+
+### API to retrieve available counts
+sai_object_type_get_availability() is an existing SAI API used to query any resource specific availability count. The same API is to be used to query generic SAI extension table resource availability as well. API call is to have following object-type and attributes as parameters,
+
+  - object-type    : SAI_OBJECT_TYPE_GENERIC_PROGRAMMABLE
+  - attribute-id   : SAI_GENERIC_PROGRAMMABLE_ATTR_OBJECT_NAME
+
+respective data-plane implementing this API should return resource count available for the corresponding extension table matching the generic programmable object name
+
+### APIs for used counter book-keeping
+- CrmOrch::incCrmExtTableUsedCounter()
+- CrmOrch::decCrmExtTableUsedCounter()
+
+P4Orch extension table manager is responsible to call APIs when a specific entry for extension table is successfully created or removed.
+
+### Example of CRM counts of extension table o/p in redis
+Example o/p for VIPV4_TABLE with max capacity of 1024
+
+```text
+127.0.0.1:6379[2]> KEYS *EXT_TABLE_STATS*
+ 1) "CRM:EXT_TABLE_STATS:EXT_VIPV4_TABLE"
+
+127.0.0.1:6379[2]> HGETALL "CRM:EXT_TABLE_STATS:EXT_VIPV4_TABLE"
+1) "crm_stats_extension_table_used"
+2) "1"
+3) "crm_stats_extension_table_available"
+4) "1023"
+```
+
+## Unit Test Automation <a name="Unit-Test-Automation"></a>
+P4Orch pytest automation
+- Enhance current viplb generic sai extension test automation to insert validation for crm
+  - after viplb table entry is programmed, get crm used counters
+  - validate used counter has value 1 since 1 viplb entry is programmed
+  - after viplb table entry is removed, get crm used counters
+  - validate used counter has value 0 since there are no more any entries in viplb table

doc/platform/brcm_pdk_pddf.md

@@ -53,6 +53,12 @@
  * [SAI](#sai)
  * [CLI](#cli)
  * [Serviceability and DEBUG](#serviceability-and-debug)
+ * [S3IP Standard Support](#s3ip-standard-support)
+	  * [S3IP PDDF Requirements](#s3ip-pddf-requirements)
+	  * [Implementation Details](#implementation-details)
+		 * [PDDF and S3IP SysFS](#pddf-and-s3ip-sysfs)
+		 * [S3IP SysFS Creation and Mapping](#s3ip-sysfs-creation-and-mapping)
+		 * [Adding S3IP Support for a Platform](#adding-s3ip-support-for-a-platform)
  * [Warm Boot Support](#warm-boot-support)
  * [Unit Test](#unit-test)
 
@@ -70,6 +76,7 @@
 | 0.5 | 10/31/2019  |  Fuzail Khan, Precy Lee     | BMC Support                       |
 | 0.6 | 10/01/2020  |  Fuzail Khan, Precy Lee     | FPGAI2C component support         |
 | 0.7 | 01/05/2023  |  Fuzail Khan, Precy Lee     | FPGAPCIe component support        |
+| 0.8 | 03/17/2023  |  Fuzail Khan, Precy Lee     | S3IP SysFS support        |
 
 # About this Manual
 Platform Driver Development Framework (PDDF) is part of SONiC Platform Development Kit (PDK), which enables rapid development of platform drivers and APIs for SONiC platforms. PDK consists of
@@ -1866,13 +1873,137 @@ root@sonic:/home/admin#
 ### Debug logs
 All the logs can be found under /var/log/pddf.
 
+## 7 S3IP Standard Support
 
-## 7 Warm Boot Support
+S3IP sysfs specification defines a unified interface to access peripheral hardware on devices from different vendors, making it easier for SONiC to support different devices and platforms. The S3IP standard support is now available with PDDF. If the user wants, there is a provision to enable/create S3IP sysfs standards.
+
+### 7.1 S3IP PDDF Requirements
+
+- S3IP sysfs should be generated and could be removed on requirement
+- Though S3IP can be clubbed with PDDF, PDDF should be independent of the S3IP
+- If any attribute which cannot be read should have a value of 'NA' i.e. tools should not fail due to non existance of the attribute
+- S3IP sysfs should be able to work with the existing PDDF common driver sysfs
+- PDDF common driver attributes should be expanded, if required, to cover the left out attributes from S3IP specifications
+
+### 7.2 Implementation Details
+
+The S3IP specifications and framework are defined [here](https://github.com/sonic-net/SONiC/pull/1068). Both vendors and users are required to follow the S3IP spec. The platform vendors need to provide the implementation of the set/get attribute functions for the platforms which use S3IP sysfs framework. The attributes for each component are defined in the specificaitons. This effort is to combine the S3IP spec and PDDF framework. In other words, the platform which are using PDDF would be S3IP compliant too after this support is added.
+
+#### 7.2.1 PDDF and S3IP SysFS
+
+PDDF implements common kernel drivers for various components. These common drivers exposes a fixed set of sysfs attributes as per the HW support and current SONiC API requirements. Complying to S3IP spec requires the mapping of S3IP component attributes to PDDF exposed sysfs attributes and might even require adding new attributes to PDDF common driver code. Hence, S3IP spec sysfs attributes are divided into the following categories.
+
+ - Platform Info Attributes: This includes the fixed information pertaining to the platform in entirity or any component. There is no need of reading this information from the component in run time. Further, these values will not change in the course of System running the SONiC image. Below are few examples of static info attributes.
+
+     - /sys_switch/temp_sensor/number, /sys_switch/vol_sensor/number, /sys_switch/curr_sensor/number etc.
+
+     - /sys_switch/cpld/cpld[n]/alias, /sys_switch/temp_sensor/temp[n]/alias, /sys_switch/temp_sensor/temp[n]/type etc.
+
+   S3IP file system can be created and the information can be directly written from the PDDF JSON files to them. Since this is static information, there is no need of repeatedly updating it.
+
+ - Component Attributes: These are the attributes are to be read from various HW components. These could be dynamically changing information like PSU voltage and temperature, or fixed like PSU serial number or FAN model etc.
+
+     - Some such S3IP sysfs would match the sysfs exposed by the PDDF frameowrk and hence a proper mapping with softlink creation would suffice.
+
+     - Some S3IP sysfs would not match directly with PDDF exposed sysfs. For such attributes, either PDDF common dirvers can be enhanced to provide the exact match or some other method can be used.
+
+     - There are some S3IP attributes which can't and won't be mapped to common PDDF driver attributes because PDDF common code doesn't support these devices e.g. volt_sensors, curr_sensors etc. There are no PDDF common drivers for such devices. However, ODMs might extend the PDDF framework by providing the custom drivers. In such cases, ODMs need to take care of mapping the S3IP attributes to the attributes exposed by the custom drivers.
+
+     - We faced a practical issue for some S3IP attributes e.g. Fan status. S3IP description says
+
+     |Sysfs path|Permissions|Data type|Description|
+     |-|-|-|-|
+     |/sys_switch/fan/fan[n]/status |RO| enum| Fan states are defined as follows:<br>0: not present<br>1: present and normal<br>2: present and abnormal
+
+     - This is a combination of 'presence' and 'running_status' informations of a fan unit. In SONiC we can handle this in the platform APIs but S3IP compels to performs this processing inside the kernel modules. Hence if ODM extends the PDDF driver and provide the kernel implementation of such sysfs, we can create the mapping. Otherwise we will map it to 'NA'.
+
+#### 7.2.2 S3IP SysFS Creation and Mapping
+
+![S3IP Support in PDDF](../../images/platform/s3ip_pddf.jpg "S3IP Support in PDDF")
+
+
+If the S3IP sysfs is required on a PDDF platform, it can be represented using the field "enable_s3ip" in the PDDF JSON file. If this field is not mentioned or has a value "no", then the S3IP sysfs creation is disabled for that platform. The support for S3IP is controlled by a service "pddf-s3ip-init.service". This service is run at the end of PDDF platform initialization service. It is an standalone service which needs to have an 'after' dependency on PDDF platform init service.
+```
+    "PLATFORM":
+    {
+        "num_psus":2,
+        "num_fantrays":4,
+        "num_fans_pertray":2,
+        "num_ports":64,
+        "num_temps": 8,
+        "enable_s3ip": "yes",
+        "pddf_dev_types":
+        {
+            "description":"AS7816-64X - Below is the list of supported PDDF device types (chip names) for various components. If any component uses some other driver, we will create the client using 'echo <de
+            "CPLD":
+            [
+                "i2c_cpld"
+            ],
+            "PSU":
+            [
+                "psu_eeprom",
+                "psu_pmbus"
+            ],
+            "FAN":
+            [
+                "fan_ctrl",
+                "fan_eeprom"
+            ],
+            "PORT_MODULE":
+...
+...
+```
+
+This pddf-s3ip service would create the sysfs as per the standards. It will also take care of linking the appropriate PDDF sysfs with the corrosponding S3IP sysfs.
+
+In case the platform does not support some attributes present in the S3IP spec, 'NA' will be written to the attribute file so that the application does not fail.
+
+Once this is done, users can run their S3IP compliant applicaitons and test scripts on the platform.
+
+#### 7.2.3 Adding S3IP Support for a Platform
+
+For adding support for S3IP on a platform which is already using PDDF for bringup, here are the steps.
+
+- Add "enable_s3ip": "yes" into the pddf-device.json file for that platform
+```
+         "num_fans_pertray":1,
+         "num_ports":54,
+         "num_temps": 3,
++        "enable_s3ip": "yes",
+         "pddf_dev_types":
+         {
+```
+
+- Create a softlink for the 'pddf-s3ip-init.service' inside service folder for that platform.
+
+```
+diff --git a/platform/broadcom/sonic-platform-modules-<odm>/<platform>/service/pddf-s3ip-init.service b/platform/broadcom/sonic-platform-modules-<odm>/<platform>/service/pddf-s3ip-init.service
+new file mode 120000
+index 000000000..f1f7fe768
+--- /dev/null
++++ b/platform/broadcom/sonic-platform-modules-<odm>/<platform>/service/pddf-s3ip-init.service
+@@ -0,0 +1 @@
++../../../../pddf/i2c/service/pddf-s3ip-init.service
+\ No newline at end of file
+
+
+# ls -l platform/broadcom/sonic-platform-modules-<odm>/<platform>/service/pddf*
+total 3
+lrwxrwxrwx 1 fk410167 nwsoftusers  55 May  8 02:02 pddf-platform-init.service -> ../../../../pddf/i2c/service/pddf-platform-init.service
+lrwxrwxrwx 1 fk410167 nwsoftusers  55 May  8 02:02 pddf-s3ip-init.service -> ../../../../pddf/i2c/service/pddf-s3ip-init.service
+#
+
+```
+
+Build the platform and sonic-device-data debian packages and load the build on the respective platform.
+
+
+## 8 Warm Boot Support
 Platform service restart should be supported without having to reboot the device
 
-## 8 Scalability
+## 9 Scalability
 NA
-## 9 Unit Test
+## 10 Unit Test
 Generic unit tests are listed below. These should be extended to all the components where they are applicable.
 1. JSON descriptor file - Schema validation and error detection
 2. Test descriptor file Parsing