SAI Proposal TAM stream telemetry (#2089)

Proposal a new streaming method for telemetry

inc/saiobject.h

@@ -300,6 +300,20 @@ sai_status_t sai_query_stats_capability(
         _In_ sai_object_type_t object_type,
         _Inout_ sai_stat_capability_list_t *stats_capability);
 
+/**
+ * @brief Query statistics capability for statistics bound at object level under the stream telemetry mode
+ *
+ * @param[in] switch_id SAI Switch object id
+ * @param[in] object_type SAI object type
+ * @param[inout] stats_capability List of implemented enum values, the statistics modes (bit mask) supported and minimal polling interval per value
+ *
+ * @return #SAI_STATUS_SUCCESS on success, #SAI_STATUS_BUFFER_OVERFLOW if lists size insufficient, failure status code on error
+ */
+sai_status_t sai_query_stats_st_capability(
+        _In_ sai_object_id_t switch_id,
+        _In_ sai_object_type_t object_type,
+        _Inout_ sai_stat_st_capability_list_t *stats_capability);
+
 /**
  * @brief Bulk objects get statistics.
  *

inc/saiswitch.h

@@ -3084,6 +3084,46 @@ typedef enum _sai_switch_attr_t
      */
     SAI_SWITCH_ATTR_EXTENDED_PORT_STATE_CHANGE_NOTIFY,
 
+    /**
+     * @brief Tam telemetry reporting byte size of chunk under the stream telemetry
+     *
+     * 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_ONLY
+     * @default 65535
+     */
+    SAI_SWITCH_ATTR_TAM_ST_REPORT_CHUNK_SIZE,
+
+    /**
+     * @brief Tam telemetry chunk count under the stream telemetry
+     *
+     * This value indicates how many chunks of reports that can be restored in the buffer.
+     * If the data structure is a ring buffer, the byte size of ring buffer is chunk count * chunk size.
+     * The default value, 0, means that this value was determined by the vendor.
+     * If the buffer is full, new incoming data will be dropped.
+     *
+     * @type sai_uint32_t
+     * @flags CREATE_ONLY
+     * @default 0
+     */
+    SAI_SWITCH_ATTR_TAM_ST_CHUNK_COUNT,
+
+    /**
+     * @brief Set TAM telemetry type config change event notification callback function passed to the adapter.
+     *
+     * Use sai_tam_tel_type_config_change_notification_fn as notification function.
+     *
+     * @type sai_pointer_t sai_tam_tel_type_config_change_notification_fn
+     * @flags CREATE_AND_SET
+     * @default NULL
+     */
+    SAI_SWITCH_ATTR_TAM_TEL_TYPE_CONFIG_CHANGE_NOTIFY,
+
     /**
      * @brief End of attributes
      */

inc/saitam.h

@@ -910,6 +910,51 @@ 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 only one counter type
+     */
+    SAI_TAM_TEL_TYPE_MODE_SINGLE_TYPE,
+
+    /**
+     * @brief This TAM telemetry type supports to bound multiple counter types
+     */
+    SAI_TAM_TEL_TYPE_MODE_MIXED_TYPE,
+
+} sai_tam_tel_type_mode_t;
+
+/**
+ * @brief TAM telemetry type state of state machine
+ */
+typedef enum _sai_tam_tel_type_state_t
+{
+    /**
+     * @brief Telemetry type is stopped
+     *
+     * In this stage, the recording stream should be stopped,
+     * and the configuration should be cleared.
+     */
+    SAI_TAM_TEL_TYPE_STATE_STOP_STREAM,
+
+    /**
+     * @brief Telemetry type is started
+     *
+     * In this stage, the recording stream should be started,
+     * and the latest configuration should be applied.
+     */
+    SAI_TAM_TEL_TYPE_STATE_START_STREAM,
+
+    /**
+     * @brief Telemetry type configuration is prepared,
+     *
+     * We expect the configuration to be generated in the feature,
+     * And notify the user by sai_tam_tel_type_config_change_notification_fn
+     */
+    SAI_TAM_TEL_TYPE_STATE_CREATE_CONFIG,
+
+} sai_tam_tel_type_state_t;
+
 /**
  * @brief Telemetry type attributes
  */
@@ -1076,6 +1121,35 @@ 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 CREATE_ONLY
+     * @default SAI_TAM_TEL_TYPE_MODE_SINGLE_TYPE
+     * @validonly SAI_TAM_TEL_TYPE_ATTR_TAM_TELEMETRY_TYPE == SAI_TAM_TELEMETRY_TYPE_COUNTER_SUBSCRIPTION
+     */
+    SAI_TAM_TEL_TYPE_ATTR_MODE,
+
+    /**
+     * @brief TAM telemetry type state
+     *
+     * @type sai_tam_tel_type_state_t
+     * @flags CREATE_AND_SET
+     * @default SAI_TAM_TEL_TYPE_STATE_STOP_STREAM
+     */
+    SAI_TAM_TEL_TYPE_ATTR_STATE,
+
+    /**
+     * @brief Query IPFIX template
+     * SAI adapter will return error if COUNTER_SUBSCRIPTION_LIST and REPORT_ID is not configured.
+     * Return the IPFIX template for this telemetry type object.
+     *
+     * @type sai_u8_list_t
+     * @flags READ_ONLY
+     */
+    SAI_TAM_TEL_TYPE_ATTR_IPFIX_TEMPLATES,
+
     /**
      * @brief End of Attributes
      */
@@ -1088,6 +1162,14 @@ typedef enum _sai_tam_tel_type_attr_t
     SAI_TAM_TEL_TYPE_ATTR_CUSTOM_RANGE_END
 } sai_tam_tel_type_attr_t;
 
+/**
+ * @brief TAM telemetry state change callback
+ *
+ * @param[in] tam_tel_id Create Telemetry Object ID
+ */
+typedef void (*sai_tam_tel_type_config_change_notification_fn)(
+        _In_ sai_object_id_t tam_tel_id);
+
 /**
  * @brief Create and return a telemetry type object
  *
@@ -2192,13 +2274,23 @@ typedef enum _sai_tam_counter_subscription_attr_t
      * @brief Telemetry label
      *
      * Label to identify this counter in telemetry reports.
+     * If the report type is IPFIX, this label will be used as the element ID in the IPFIX template.
      *
      * @type sai_uint64_t
      * @flags CREATE_ONLY
      * @default 0
      */
     SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_LABEL,
 
+    /**
+     * @brief Setting of read-clear or read-only for statistics read.
+     *
+     * @type sai_stats_mode_t
+     * @flags CREATE_ONLY
+     * @default SAI_STATS_MODE_READ
+     */
+    SAI_TAM_COUNTER_SUBSCRIPTION_ATTR_STATS_MODE,
+
     /**
      * @brief End of Attributes
      */
@@ -2370,6 +2462,8 @@ typedef struct _sai_tam_api_t
     sai_remove_tam_counter_subscription_fn         remove_tam_counter_subscription;
     sai_set_tam_counter_subscription_attribute_fn  set_tam_counter_subscription_attribute;
     sai_get_tam_counter_subscription_attribute_fn  get_tam_counter_subscription_attribute;
+    sai_bulk_object_create_fn                      create_tam_counter_subscriptions;
+    sai_bulk_object_remove_fn                      remove_tam_counter_subscriptions;
 } sai_tam_api_t;
 
 /**

inc/saitypes.h

@@ -1835,6 +1835,32 @@ typedef struct _sai_stat_capability_list_t
 
 } sai_stat_capability_list_t;
 
+/**
+ * @brief Stat capability under the stream telemetry mode
+ */
+typedef struct _sai_stat_st_capability_t
+{
+    /**
+     * @brief Typical stat capability
+     */
+    sai_stat_capability_t capability;
+
+    /**
+     * @brief Minimal polling interval in nanoseconds
+     *
+     * If polling interval is less than this value, it will be unacceptable.
+     */
+    uint64_t minimal_polling_interval;
+
+} sai_stat_st_capability_t;
+
+typedef struct _sai_stat_st_capability_list_t
+{
+    uint32_t count;
+    sai_stat_st_capability_t *list;
+
+} sai_stat_st_capability_list_t;
+
 typedef enum _sai_stats_count_mode_t
 {
     /** Count packet and byte */

meta/aspell.en.pws

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