Add TAM telemetry state machine

Signed-off-by: Ze Gan <[email protected]>

doc/TAM/SAI-Proposal-TAM-stream-telemetry.md

@@ -613,6 +613,37 @@ create_tam_tel_type(&sai_tam_tel_type_obj, switch_id, attr_count, sai_attr_list)
 
 #### Creating TAM telemetry object
 
+``` mermaid
+
+---
+title: TAM Telemetry state machine
+---
+stateDiagram-v2
+    direction LR
+
+    state "Stop TAM Stream" as stop
+    state "Start TAM Stream" as start
+    state "Commit configure" as commit
+    state "Config ready" as ready
+    state join_commit <<join>>
+
+    [*] --> stop: Object create
+    stop --> start: NOS set
+    stop --> join_commit: NOS set
+
+    start --> join_commit: NOS set (The record stream will not stop and original templates will still be used)
+    join_commit --> commit: Vendor start preparing templates based on bounded telemetry types
+    start --> stop: NOS set
+
+    commit --> ready: Vendor set (callback via notification)
+
+    ready --> start: NOS set (New templates will be applied to generate the new record streaming)
+    ready --> stop: NOS set
+
+    stop --> [*]: Object remove
+
+```
+
 Extern TAM telemetry attributes in SAI
 
 ``` c++

inc/saiswitch.h

@@ -3071,17 +3071,44 @@ typedef enum _sai_switch_attr_t
     SAI_SWITCH_ATTR_SELECTIVE_COUNTER_LIST,
 
     /**
-     * @brief Tam telemetry cache count
+     * @brief Tam telemetry buffer size
      *
-     * If the collector isn't ready to receive the report, this value indicates how many
-     * reports that can be cached. 0 means no cache which is the default behavior.
+     * If the collector isn't ready to receive reports, this value indicates how many
+     * bytes of reports that can be cached.
+     * 0 means no cache which is the default behavior.
      * If the cache is full, new incoming data will be dropped.
      *
      * @type sai_uint32_t
      * @flags CREATE_ONLY
      * @default 0
      */
-    SAI_SWITCH_ATTR_TAM_CACHE_COUNT,
+    SAI_SWITCH_ATTR_TAM_BUFFER_SIZE,
+
+    /**
+     * @brief Tam telemetry reporting chunk size
+     *
+     * Defines the maximum number of bytes in a single report.
+     * The total number of bytes in a report should be as close as possible to this value.
+     * We can increase this value to reduce the number of sys calls.
+     * If the type of message is IPFIX, this value should not be less than 65535.
+     * Because we don't expect the IPFIX record to be fragmented.
+     *
+     * @type sai_uint32_t
+     * @flags CREATE_AND_SET
+     * @default 65535
+     */
+    SAI_SWITCH_ATTR_TAM_CHUNK_SIZE,
+
+    /**
+     * @brief Set TAM telemetry state change event notification callback function passed to the adapter.
+     *
+     * Use sai_tam_telemetry_state_change_notification_fn as notification function.
+     *
+     * @type sai_pointer_t sai_tam_telemetry_state_change_notification_fn
+     * @flags CREATE_AND_SET
+     * @default NULL
+     */
+    SAI_SWITCH_ATTR_TAM_TELEMETRY_STATE_CHANGE_NOTIFY,
 
     /**
      * @brief End of attributes

inc/saitam.h

@@ -910,6 +910,20 @@ typedef enum _sai_tam_telemetry_type_t
 
 } sai_tam_telemetry_type_t;
 
+typedef enum _sai_tam_tel_type_mode_t
+{
+    /**
+     * @brief This TAM telemetry type supports to bound multiple counter types
+     */
+    SAI_TAM_TEL_TYPE_MODE_MIXED_TYPE,
+
+    /**
+     * @brief This TAM telemetry type supports to bound only one counter type
+     */
+    SAI_TAM_TEL_TYPE_MODE_SINGLE_TYPE,
+
+} sai_tam_tel_type_mode_t;
+
 /**
  * @brief Telemetry type attributes
  */
@@ -1076,6 +1090,14 @@ typedef enum _sai_tam_tel_type_attr_t
      */
     SAI_TAM_TEL_TYPE_ATTR_COUNTER_SUBSCRIPTION_LIST,
 
+    /**
+     * @brief The mode of TAM telemetry type
+     *
+     * @type sai_tam_tel_type_mode_t
+     * @flags MANDATORY_ON_CREATE | CREATE_ONLY
+     */
+    SAI_TAM_TEL_TYPE_ATTR_MODE,
+
     /**
      * @brief End of Attributes
      */
@@ -1334,16 +1356,6 @@ typedef enum _sai_tam_report_attr_t
      */
     SAI_TAM_REPORT_ATTR_REPORT_INTERVAL_UNIT,
 
-    /**
-     * @brief Query IPFIX template
-     *
-     * Return a list of IPFIX templates
-     *
-     * @type sai_u8_list_t
-     * @flags READ_ONLY
-     */
-    SAI_TAM_REPORT_ATTR_IPFIX_TEMPLATES,
-
     /**
      * @brief End of Attributes
      */
@@ -1437,21 +1449,31 @@ typedef enum _sai_tam_reporting_unit_t
 } sai_tam_reporting_unit_t;
 
 /**
- * @brief TAM reporting type
+ * @brief TAM telemetry state of state machine
  */
-typedef enum _sai_tam_reporting_type_t
+typedef enum _sai_tam_telemetry_state_t
 {
     /**
-     * @brief Report type is time based
+     * @brief Telemetry is stopped
      */
-    SAI_TAM_REPORTING_TYPE_TIME_BASED,
+    SAI_TAM_TELEMETRY_STATE_STOPPED,
 
     /**
-     * @brief Report type is count based
+     * @brief Telemetry is started
      */
-    SAI_TAM_REPORTING_TYPE_COUNT_BASED,
+    SAI_TAM_TELEMETRY_STATE_STARTED,
 
-} sai_tam_reporting_type_t;
+    /**
+     * @brief Telemetry config is committed
+     */
+    SAI_TAM_TELEMETRY_STATE_CONFIG_COMMITTED,
+
+    /**
+     * @brief Telemetry config is ready
+     */
+    SAI_TAM_TELEMETRY_STATE_CONFIG_READY,
+
+} sai_tam_telemetry_state_t;
 
 /**
  * @brief TAM telemetry attributes
@@ -1488,7 +1510,6 @@ typedef enum _sai_tam_telemetry_attr_t
      * @type sai_tam_reporting_unit_t
      * @flags CREATE_AND_SET
      * @default SAI_TAM_REPORTING_UNIT_SEC
-     * @validonly SAI_TAM_TELEMETRY_ATTR_TAM_REPORTING_TYPE == SAI_TAM_REPORTING_TYPE_TIME_BASED
      */
     SAI_TAM_TELEMETRY_ATTR_TAM_REPORTING_UNIT,
 
@@ -1500,31 +1521,35 @@ typedef enum _sai_tam_telemetry_attr_t
      * @type sai_uint32_t
      * @flags CREATE_AND_SET
      * @default 1
-     * @validonly SAI_TAM_TELEMETRY_ATTR_TAM_REPORTING_TYPE == SAI_TAM_REPORTING_TYPE_TIME_BASED
      */
     SAI_TAM_TELEMETRY_ATTR_REPORTING_INTERVAL,
 
     /**
-     * @brief Tam telemetry reporting type
+     * @brief TAM telemetry state
      *
-     * @type sai_tam_reporting_type_t
-     * @flags CREATE_ONLY
-     * @default SAI_TAM_REPORTING_TYPE_TIME_BASED
+     * @type sai_tam_telemetry_state_t
+     * @flags CREATE_AND_SET
+     * @default SAI_TAM_TELEMETRY_STATE_STOPPED
      */
-    SAI_TAM_TELEMETRY_ATTR_TAM_REPORTING_TYPE,
+    SAI_TAM_TELEMETRY_ATTR_STATE,
 
     /**
-     * @brief Tam telemetry reporting bulk count
+     * @brief Current state of TAM telemetry
      *
-     * Defines the count of reporting bulk, which means TAM will report to the collector every time
-     * if the report count reaches the bulk count.
+     * @type sai_tam_telemetry_state_t
+     * @flags READ_ONLY
+     */
+    SAI_TAM_TELEMETRY_ATTR_CURRENT_STATE,
+
+    /**
+     * @brief Query IPFIX template
      *
-     * @type sai_uint32_t
-     * @flags CREATE_AND_SET
-     * @default 1
-     * @validonly SAI_TAM_TELEMETRY_ATTR_TAM_REPORTING_TYPE == SAI_TAM_REPORTING_TYPE_COUNT_BASED
+     * Return a list of IPFIX templates
+     *
+     * @type sai_u8_list_t
+     * @flags READ_ONLY
      */
-    SAI_TAM_TELEMETRY_ATTR_REPORTING_BULK_COUNT,
+    SAI_TAM_TELEMETRY_ATTR_IPFIX_TEMPLATES,
 
     /**
      * @brief End of Attributes
@@ -1539,6 +1564,18 @@ typedef enum _sai_tam_telemetry_attr_t
 
 } sai_tam_telemetry_attr_t;
 
+/**
+ * @brief TAM telemetry state change callback
+ *
+ * @count data[count]
+ *
+ * @param[in] tam_tel_id Create Telemetry Object ID
+ * @param[in] state The state of the telemetry object
+ */
+typedef void (*sai_tam_telemetry_state_change_notification_fn)(
+        _In_ sai_object_id_t tam_tel_id,
+        _In_ sai_tam_telemetry_state_t state);
+
 /**
  * @brief Create and return a telemetry object
  *

meta/aspell.en.pws

@@ -218,3 +218,5 @@ Wildcard
 www
 xconnect
 TWAMP
+config
+sys