diff --git a/doc/TWAMP/SONiC-TWAMP-Ligth-HLD.md b/doc/TWAMP/SONiC-TWAMP-Ligth-HLD.md index 5c71a441ae..3227ab27c1 100644 --- a/doc/TWAMP/SONiC-TWAMP-Ligth-HLD.md +++ b/doc/TWAMP/SONiC-TWAMP-Ligth-HLD.md @@ -1,130 +1,214 @@ -# SONiC TWAMP Light # -# High Level Design Document # -### Rev 0.1 +# TWAMP Light HLD # + +## Table of Contents + + - [Definitions/Abbreviation](#definitionsabbreviation) + + - [Revision](#Revision) + - [Scope](#Scope) + - [Definition/Abbreviation](#Definition_Abbreviation) + - [1. Overview](#1-Overview) + - [2. Requirements](#2-Requirements) + - [2.1 Functional requirements](#2_1-Functional_requirements) + - [2.2 Configuration and Management Requirements](#2_2-Configuration_and_Management_Requirements) + - [2.3 Scalability and Default Values](#2_3-Scalability_and_Default_Values) + - [2.3.1 Scalability](#2_3_1-Scalability) + - [2.3.2 Default Values](#2_3_2-Default_Values) + - [2.4 Warm Restart requirements](#2_4-Warm_Restart_requirements) + - [3. Architecture Design](#3-Architecture_Design) + - [4. High-Level Design](#4-High_Level_Design) + - [4.1 DB Changes](#4_1-DB_Changes) + - [4.1.1 CONFIG DB](#4_2_1-CONFIG_DB) + - [4.1.2 STATE DB](#4_2_2-STATE_DB) + - [4.1.3 COUNTER DB](#4_2_3-COUNTER_DB) + - [4.2 Flow Diagrams](#4_2-Flow_Diagrams) + - [4.2.1 Query ASIC capability](#4_2_1-Query_ASIC_capability) + - [4.2.2 Create session](#4_2_2-Create_session) + - [4.2.3 Remove session](#4_2_3-Remove_session) + - [4.2.4 Restart/Stop session](#4_2_4-Restart_Stop_session) + - [4.2.5 Notify Session-Sender event](#4_2_5-Notify_Session_Sender_event) + - [5. SAI API](#5-SAI_API) + - [6. Configuration and management](#6-Configuration_and_management) + - [6.1 Manifest](#6_1-Manifest) + - [6.2 CLI](#6_2-CLI) + - [6.2.1 Configuration commands](#6_2_1-Configuration_commands) + - [6.2.1.1 Session-Sender with packet-count mode](#6_2_1_1-Session_Sender_with_packet_count_mode) + - [6.2.1.2 Session-Sender with continuous mode](#6_2_1_2-Session_Sender_with_continuous_mode) + - [6.2.1.3 Start TWAMP Light Session-Sender](#6_2_1_3-Start_TWAMP_Light_Session_Sender) + - [6.2.1.4 Stop TWAMP Light Session-Sender](#6_2_1_4-Stop_TWAMP_Light_Session_Sender) + - [6.2.1.5 Session-Reflector](#6_2_1_5-Session_Reflector) + - [6.2.1.6 Remove_TWAMP_Light_session](#6_2_1_6-Remove_TWAMP_Light_session) + - [6.2.2 Show commands](#6_2_1-Show_commands) + - [6.2.2.1 Show TWAMP Light session status](#6_2_2_1-Show_TWAMP_Light_session_status) + - [6.2.2.2 Show TWAMP Ligth latency and jitter](#6_2_2_2-Show_TWAMP_Ligth_latency_and_jitter) + - [6.2.2.3 Show TWAMP Ligth packet loss](#6_2_2_3-Show_TWAMP_Light_packet_loss) + - [6.3 YANG](#6_2-YANG) + - [7. Warmboot and Fastboot Design Impact](#7-Warmboot_and_Fastboot_Design_Impact) + - [8. Restrictions_Limitations](#8-Restrictions_Limitations) + - [9. Testing Requirements/Design](#9-Testing_Requirements_Design) + - [9.1 Unit Test cases](#9_1-Unit_Test_cases) + - [9.2.1 CLI](#9_2_1-CLI) + - [9.2.2 Functionality](#9_2_2-Functionality) + - [9.2.3 Scaling](#9_2_3-Scaling) + - [9.2.4 SAI](#9_2_4-SAI) + - [References](#-References) + +## Revision -# Table of Contents +| Rev | Date | Author | Change Description | +| :--: | :--------: | :-----------------------------------: | ------------------ | +| 0.1 | 06/12/2023 | Xiaodong Hu, Shuhua You, Xianghong Gu | Initial version | -[TOC] +## Scope -# List of Tables +This document describes the requirements, architecture, and configuration details of the TWAMP Light feature in SONiC. -###### Table1: Revision ###### +## Definition/Abbreviation -| Rev | Date | Author | Change Description | -| :--: | :--------: | :-----------------------------------: | ------------------ | -| 0.1 | 04/03/2023 | Xiaodong Hu, Shuhua You, Xianghong Gu | Initial version | +| **Definitions/Abbreviation** | Description | +| ---------------------------- | ----------------------------------------- | +| TWAMP | Two-way Active Measurement Protocol | +| TWAMP Light | A light version of TWAMP | +| AR | Augmented Reality | +| IPPM | IP Performance Measurement | +| OAM | Operation, Administration and Maintenance | +| SAI | Switch Abstraction Interface | +| RPM | Real-Time Performance Monitor | +| RTT | Round-Trip Time | +| VRF | Virtual Routing and Forwarding | + +## 1 Overview -# About this Manual +With the rapid development of network application technologies, latency and packet loss-sensitive such as audio, video and AR services impose higher requirements on network performance. In this requirement scenario, service providers need a mechanism that provides real-time information about the quality and latency of network paths for helping them to monitor and maintain the quality of their networks. -This document provides general information about the TWAMP Light feature implementation in SONiC. +Some vendors use proprietary features such as RPM to measure IP network performance, so it is not universally supported by devices. In this interoperability environment, service providers need an effective, simple, and universal OAM performance measurement mechanism for performance measurement of the network. -# Scope +There are some standard measurement tools such as Ping and Traceroute. Ping is a tool used to test connectivity and measure RTT, and Traceroute is a tool used to identify the path that packets take between two hosts, but TWAMP Light serves different purposes from them. TWAMP Light measures the quality and latency of the network path in both directions, providing a more accurate view of the network performance. -This document describes the high level design of TWAMP Light feature. +TWAMP Light defined by the IP Performance Measurement (IPPM) working group, is a standard performance measurement protocol applied to IP networks as described in RFC5357. It provides a unified measurement model and unified test packet format for interoperability among devices of different vendors. TWAMP Light uses the client-server model. It generates and maintains the performance measurement data only on the client. As an IP link detection technology, It can monitor network quality, including latency, jitter, and packet loss. So it is easy to deploy and use. -# Definition/Abbreviation +![TWAMP Light role](./images/TWAMP_Light_role.png) -###### Table 2: Abbreviations +TWAMP Light does not require a control connection to set up and manage the measurement sessions. Instead, it uses a simple message exchange process between two endpoints to initiate and terminate the measurements. In hence, the roles of Control-Client, Server and Session-Sender are implemented in one host referred to as the controller, and the role of Session-Reflector is implemented in another host referred to as the responder as described in RFC5357. TWAMP Light is a Two-way measurement witch is common in IP networks, primarily because synchronization between local and remote clocks is unnecessary for round-trip delay, and measurement support at the remote end may be limited to a simple echo function. -| **Definitions/Abbreviation** | Description | -| ---------------------------- | ----------------------------------- | -| TWAMP | Two-way Active Measurement Protocol | -| TWAMP Light | A light version of TWAMP | +To calculate the latency, jitter, and packet loss rate of network, the following steps are typically followed: -# 1. Requirements Overview +- Session-Sender as the active endpoint of the TWAMP Light sends a Test-request packet with a tx timestamp marked as t0. +- Session-Reflector receives the Test-request packet and captures a rx timestamp as t1. +- Prior to the transmission of the Test-response packet, Session-Reflector captures a tx timestamp as t2. +- Session-Reflector encodes t1 and t2 into the Test-response packet, then sends it out. +- Session-Sender receives the Test-response packet and captures a rx timestamp as t3. -## 1.1 Functional requirements +The algorithm is: + +- Latency = (t3-t0) – (t2-t1) +- Jitter = | Latency1 – Latency0 | +- Packet loss rate = (txPkt – rxPkt) / txPkt + +## 2 Requirements + +### 2.1 Functional requirements At a high level the following should be supported: -- TWAMP Light sender offload to HW -- TWAMP Light reflector offload to HW -- TWAMP Light sender and reflector for SW is not planned for first phase -- Support sender collect statistics +Phase #1 -## 1.2 Configuration and Management Requirements +- RFC5357 TWAMP Light should be followed +- Should be able to perform the role of TWAMP Light Session-Sender: -- Support CLI configuration commands as mentioned in section 3.5.2 -- Support show commands as mentioned in section 3.5.3 + - Support on-demand measurement based on specific number of packets + - Support proactive measurement + - Support to start and stop sending TWAMP-Test packets +- Should be able to perform the role of TWAMP Light Control-Client: -## 1.3 Scalability and Default Values + - Maintain the performance measurement data including latency, jitter and packet loss +- Should be able to perform the role of TWAMP Light Session-Reflector: -As a phase #1 scalability requirement, the proposed support is up to hardware capability + - Support to reflect TWAMP-Test packets to sender +- Should be able to configure TWAMP-Test packets fileds: Source IP, L4 Source Port, Destination IP, L4 Destination Port, DSCP, TTL, timestamp format, padding -| Attribute | Value | -| -------------------------------------- | ----- | -| TWAMP_SESSION_DEFAULT_TC | 0 | -| TWAMP_SESSION_DEFAULT_TTL | 255 | -| TWAMP_SESSION_DEFAULT_TIMESTAMP_FORMAT | NTP | +Later phases: + + - Support the authenticated and encrypted modes + - Support overlay network measurement + - Support an approach of measurement based on pure software + +### 2.2 Configuration and Management Requirements -## 1.4 Warm Restart requirements +- Support CLI configuration commands +- Support show commands -No special handling for Warm restart support. +### 2.3 Scalability and Default Values -# 2. Functionality +#### 2.3.1 Scalability -## 2.1 Functional Description +The maximum number of sessions is due to hardware capability in hardware mode. -Described in RFC5357. +The maximum number of sessions is not limited in software mode. -Two-Way Active Measurement Protocol (TWAMP) Light is a light version of TWAMP. TWAMP Light measures the round-trip performance of an IP network by using simplified control protocol to establish test sessions. +#### 2.3.2 Default Values -TWAMP Light allows a router to send detection packets to itself and the control modules in the TWAMP Light structure can be deployed in a centralized manner. This reduces requirements on the reflector and facilitates reflector deployment. +Below table shows the default values for TWAMP Test-packets. -TWAMP Light is an IP link detection technology. It can monitor network quality, including delay, jitter, and packet loss, and is easy to deploy and use. +| Attribute | Value | +| -------------------------------------- | ----- | +| TWAMP_SESSION_DEFAULT_DSCP | 0 | +| TWAMP_SESSION_DEFAULT_TTL | 255 | +| TWAMP_SESSION_DEFAULT_TIMESTAMP_FORMAT | NTP | -# 3. Modules Design +### 2.4 Warm Restart requirements -## 3.1 Overview +At this time warm restart capability is no factored into the design. This shall be revisited as a later phase enhancement. -![image-20230303163216880](./images/TWAMP_Light_architecture.png) +## 3 Architecture Design -## 3.2 DB Changes +It is delighted to introduce two approaches of measurement which implement TWAMP Light. One is based on ASIC and the other is based on pure software. In orchagent initialization phase, it can query the TWAMP Light capability from ASIC to choose one approach to deploy TWAMP Light. -This section describes the changes made to different DBs for supporting the TWAMP-Light. +![TWAMP Light architecture](./images/TWAMP_Light_architecture.png) -### 3.2.1 CONFIG DB +Architecture considers both software and hardware solutions, with the main difference is the generation, transmission, and calculation of test packets based on hardware or software. In case of the chip supports TWAMP Light feature, the hardware solution provides more precise measurement results. If not, the software solution can be chosen for TWAMP Light. -Following config DB schemas are defined for supporting this feature. +* TWAMP Light architecture using the hardware solution. A process twamporch is newly added in the hardware solution. Twamporch subscribes to TWAMP_LIGHT_TABLE and creates a session that includes properties such as IP, UDP PORT and offloads to ASIC. The ASIC generates the test packets, independently calculates the measurement data, and reports it to the up layer system. -#### TWAMP_SESSION_TABLE +* TWAMP Light architecture using the software solution. A TWAMP container is newly added. The container includes twampd which subscribes to TWAMP_LIGHT_TABLE and creates a session that includes properties such as IP, UDP PORT. Twampd runs two threads, one generates TWAMP-test packets and sends them out by Linux socket, the other receives TWAMP-test packets from Linux socket. For Session-Sender, twampd is required to calculate the latency, jitter and packet loss rate based on the measurement data such as timestamp, transmitting and receiving packets count and so on. For Session-Reflector, twampd reflects the TWAMP-test packet with timestamp. + +## 4 High-Level Design + +### 4.1 DB Changes + +#### 4.1.1 CONFIG DB ``` -;Stores TWAMP-Light sender or reflector session configuration +;Stores TWAMP Light sender or reflector session configuration ;Status: work in progress key = TWAMP_SESSION|session_name ; session_name is ; unique session identifier ; field = value -mode = "LIGHT" ; TWAMP-Light mode -role = SENDER/REFLECTOR ; TWAMP-Light role is sender or reflector +mode = "LIGHT" ; TWAMP Light mode +role = SENDER/REFLECTOR ; TWAMP Light role is sender or reflector +vrf = ; vrf name src_ip = ; sender ip address dst_ip = ; reflector ip address -udp_src_port = ; sender udp port -udp_dst_port = ; reflector udp port -receive_ports = ifName ; reveive TEST-Response packet port name -packet_count = ; TEST-Request packet count (10 to 30000, DEF:100) -duration = ; duration in secs (60 to 300 sec, DEF:60) -regular = ; regular in mins (10 to 30 mins, DEF:30) -period = ; period in msecs ([10,100,1000] ms, DEF:100) -timeout = ; timeout in secs (1 to 10 sec, DEF:5 sec) +udp_src_port = ; sender udp port +udp_dst_port = ; reflector udp port +packet_count = ; TEST-Request packet count +monitor_time = ; continuous in mins (0 indicates forever) +tx_interval = ; transmit TEST-Request in msecs ([10,100,1000], DEF:100) +timeout = ; timeout in secs (1 to 10, DEF:5) +statistics_interval = ; calculate in millisecond (DEF:0) test_session_enable = ENABLE/DISABLE ; session is enabled or disabled dscp = ; TEST-Request packet DSCP (0 to 63, DEF:0) -packet_padding_size = ; TEST-Request packet padding length (32 to 1454, DEF:108) +ttl = ; TEST-Request packet TTL (DEF:255) +packet_padding_size = ; TEST-Request packet padding length (32 to 1454, DEF:108) ``` -### 3.2.2 APP DB - -NA - -### 3.2.3 STATE DB - -#### TWAMP_SESSION_TABLE +#### 4.1.2 STATE DB ``` -;Stores TWAMP-Light state table +;Stores TWAMP Light state table ;Status: work in progress key = TWAMP_SESSION_TABLE|session_name ; mirror_session_name is ; unique session @@ -132,20 +216,17 @@ key = TWAMP_SESSION_TABLE|session_name ; mirror_session_name ; field = value status = ACTIVE/INACTIVE ; session test status -route_prefix = ; route to reflector ip address prefix -test_ports = ifname ; transmits test packet port -encap_type = "IP" ; test packet forward in IP network ``` -### 3.3.4 COUNTERS DB +#### 4.1.3 COUNTER DB -The following new counters are applicable per session based on the support in the hardware. +The following new counters are applicable per session. ``` COUNTERS_TWAMP_SESSION_NAME_MAP session_name : -COUNTERS:oid:session_name_oid +COUNTERS:oid:session_name_oid:index SAI_TWAMP_SESSION_STAT_RX_PACKETS : SAI_TWAMP_SESSION_STAT_RX_BYTE : SAI_TWAMP_SESSION_STAT_TX_PACKETS : @@ -162,147 +243,428 @@ COUNTERS:oid:session_name_oid SAI_TWAMP_SESSION_STAT_DURATION_TS : ``` -## 3.3 Switch State Service Design +### 4.2 Flow Diagrams -## 3.4 SAI +Below diagram shows the flow for hardware solution. -TWAMP Light SAI interface APIs are already defined and is available at below location - +#### 4.2.1 Query ASIC capability + +Below diagram shows the flow for switchporch queries ASIC capability. + +![query hw capability flow diagram](./images/TWAMP_Light_query_hw_capability.png) + +#### 4.2.2 Create session + +Below diagram shows the flow of creating Session-Sender or Session-Reflector. + +![create session flow diagram](./images/TWAMP_Light_create_session.png) + +#### 4.2.3 Remove session + +Below diagram shows the flow of removing Session-Sender or Session-Reflector. + +![remove session flow diagram](./images/TWAMP_Light_remove_session.png) + +#### 4.2.4 Start/Stop session + +Below diagram shows the flow of starting or stopping Session-Sender. -https://github.com/opencomputeproject/SAI/blob/master/inc/saitwamp.h (#1786) +![set session state flow diagram](./images/TWAMP_Light_set_session_state.png) +#### 4.2.5 Notify Session-Sender event + +Below diagram shows the flow of notifying the session running state and measurement data. + +![nofiy session event flow diagram](./images/TWAMP_Light_nofiy_session_event.png) + +## 5 SAI API + +Following SAI API changes are proposed to program the modes to get the ASIC capability: + +**File: saitswitch.h** + + /** + * @brief Attribute Id in sai_set_switch_attribute() and + * sai_get_switch_attribute() calls. + */ + typedef enum _sai_switch_attr_t + { + . + . + /** + * @brief Set TWAMP session event notification callback function passed to the adapter. + * + * Use sai_twamp_session_event_notification_fn as notification function. + * + * @type sai_pointer_t sai_twamp_session_event_notification_fn + * @flags CREATE_AND_SET + * @default NULL + */ + SAI_SWITCH_ATTR_TWAMP_SESSION_EVENT_NOTIFY, + + /** + * @brief Max number of Two-Way Active Measurement Protocol session supports + * + * @type sai_uint32_t + * @flags READ_ONLY + */ + SAI_SWITCH_ATTR_MAX_TWAMP_SESSION, + . + . + } sai_switch_attr_t; Max number of TWAMP Light sessions(SAI_SWITCH_ATTR_MAX_TWAMP_SESSION) are defined in below SAI spec - -https://github.com/opencomputeproject/SAI/blob/master/inc/saiswitch.h (#1786) +https://github.com/opencomputeproject/SAI/pull/1786 + +**File: saitwamp.h** + + /** + * @brief SAI attributes for Two-Way Active Measurement Protocol session + */ + typedef enum _sai_twamp_session_attr_t + { + . + . + /** + * @brief Two-Way Active Measurement Protocol session role of sender or receiver. + * + * @type sai_twamp_session_role_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_SESSION_ROLE, + + /** + * @brief UDP Source port + * + * @type sai_uint32_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_UDP_SRC_PORT, + + /** + * @brief UDP Destination port + * + * @type sai_uint32_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_UDP_DST_PORT, + + /** + * @brief Local source IP address + * + * @type sai_ip_address_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_SRC_IP, + + /** + * @brief Remote Destination IP address + * + * @type sai_ip_address_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_DST_IP, + + /** + * @brief DSCP of Traffic Class + * + * @type sai_uint8_t + * @flags CREATE_ONLY + * @default 0 + */ + SAI_TWAMP_SESSION_ATTR_DSCP, + + /** + * @brief IP header TTL + * + * @type sai_uint8_t + * @flags CREATE_ONLY + * @default 255 + * @validonly SAI_TWAMP_SESSION_ATTR_SESSION_ROLE == SAI_TWAMP_SESSION_ROLE_SENDER + */ + SAI_TWAMP_SESSION_ATTR_TTL, + + /** + * @brief Virtual Private Network virtual router + * + * @type sai_object_id_t + * @flags CREATE_ONLY + * @objects SAI_OBJECT_TYPE_VIRTUAL_ROUTER + * @allownull true + * @default SAI_NULL_OBJECT_ID + * @validonly SAI_TWAMP_SESSION_ATTR_HW_LOOKUP_VALID == true + */ + SAI_TWAMP_SESSION_ATTR_VPN_VIRTUAL_ROUTER, + + /** + * @brief Encapsulation type + * + * @type sai_twamp_encapsulation_type_t + * @flags CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_TWAMP_ENCAPSULATION_TYPE, + + /** + * @brief To enable Two-Way Active Measurement Protocol session transmit packet + * + * @type bool + * @flags CREATE_AND_SET + * @default false + * @validonly SAI_TWAMP_SESSION_ATTR_SESSION_ROLE == SAI_TWAMP_SESSION_ROLE_SENDER + */ + SAI_TWAMP_SESSION_ATTR_SESSION_ENABLE_TRANSMIT, + + /** + * @brief Hardware lookup valid + * + * @type bool + * @flags CREATE_ONLY + * @default true + */ + SAI_TWAMP_SESSION_ATTR_HW_LOOKUP_VALID, + + /** + * @brief Two-Way Active Measurement Protocol test packet tx interval + * + * @type sai_uint32_t + * @flags CREATE_ONLY + * @condition SAI_TWAMP_SESSION_ATTR_SESSION_ROLE == SAI_TWAMP_SESSION_ROLE_SENDER + */ + SAI_TWAMP_SESSION_ATTR_TX_INTERVAL, + + /** + * @brief Two-Way Active Measurement Protocol packet tx mode: CONTINUOUS, PACKET_COUNT + * + * Valid when SAI_TWAMP_SESSION_ATTR_SESSION_ROLE == SAI_TWAMP_SESSION_ROLE_SENDER + * + * @type sai_twamp_pkt_tx_mode_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_TWAMP_PKT_TX_MODE, + + /** + * @brief Two-Way Active Measurement Protocol test packet tx count, configuring by Two-Way Active Measurement Protocol send packet count of Tx + * + * @type sai_uint32_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + * @condition SAI_TWAMP_SESSION_ATTR_SESSION_ROLE == SAI_TWAMP_SESSION_ROLE_SENDER and SAI_TWAMP_SESSION_ATTR_TWAMP_PKT_TX_MODE == SAI_TWAMP_PKT_TX_MODE_PACKET_NUM + */ + SAI_TWAMP_SESSION_ATTR_TX_PKT_CNT, + + /** + * @brief Two-Way Active Measurement Protocol test packet tx period + * if tx period equal 0, sender will continue to generate packet and send them. + * + * @type sai_uint32_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + * @condition SAI_TWAMP_SESSION_ATTR_SESSION_ROLE == SAI_TWAMP_SESSION_ROLE_SENDER and SAI_TWAMP_SESSION_ATTR_TWAMP_PKT_TX_MODE == SAI_TWAMP_PKT_TX_MODE_PERIOD + */ + SAI_TWAMP_SESSION_ATTR_TX_PKT_PERIOD, + + /** + * @brief Two-Way Active Measurement Protocol mode: light mode and full mode + * + * @type sai_twamp_mode_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_TWAMP_SESSION_ATTR_TWAMP_MODE, + + /** + * @brief The format of timestamp in test packet. + * + * @type sai_twamp_timestamp_format_t + * @flags CREATE_ONLY + * @default sai_twamp_timestamp_format_t + */ + SAI_TWAMP_SESSION_ATTR_TIMESTAMP_FORMAT, + . + . + } sai_twamp_session_attr_t; + + /** + * @brief Two-Way Active Measurement Protocol Session counter IDs in sai_get_twamp_session_stats() call + */ + typedef enum _sai_twamp_session_stats_t + { + /** Rx packet stat count */ + SAI_TWAMP_SESSION_STATS_RX_PACKETS, + + /** Rx byte stat count */ + SAI_TWAMP_SESSION_STATS_RX_BYTE, + + /** Tx packet stat count */ + SAI_TWAMP_SESSION_STATS_TX_PACKETS, + + /** Tx byte stat count */ + SAI_TWAMP_SESSION_STATS_TX_BYTE, + + /** Packet Drop stat count */ + SAI_TWAMP_SESSION_STATS_DROP_PACKETS, + + /** Packet max latency */ + SAI_TWAMP_SESSION_STATS_MAX_LATENCY, + + /** Packet min latency */ + SAI_TWAMP_SESSION_STATS_MIN_LATENCY, + + /** Packet avg latency */ + SAI_TWAMP_SESSION_STATS_AVG_LATENCY, + + /** Packet max value */ + SAI_TWAMP_SESSION_STATS_MAX_JITTER, + + /** Packet min value */ + SAI_TWAMP_SESSION_STATS_MIN_JITTER, + + /** Packet avg value */ + SAI_TWAMP_SESSION_STATS_AVG_JITTER, + + /** Session first timestamp */ + SAI_TWAMP_SESSION_STATS_FIRST_TS, + + /** Session last timestamp */ + SAI_TWAMP_SESSION_STATS_LAST_TS, + } sai_twamp_session_stats_t; + + /** + * @brief Two-Way Active Measurement Protocol method table retrieved with sai_api_query() + */ + typedef struct _sai_twamp_api_t + { + sai_create_twamp_session_fn create_twamp_session; + sai_remove_twamp_session_fn remove_twamp_session; + sai_set_twamp_session_attribute_fn set_twamp_session_attribute; + sai_get_twamp_session_attribute_fn get_twamp_session_attribute; + sai_get_twamp_session_stats_fn get_twamp_session_stats; + sai_get_twamp_session_stats_ext_fn get_twamp_session_stats_ext; + sai_clear_twamp_session_stats_fn clear_twamp_session_stats; + + } sai_twamp_api_t; -## 3.5 CLI -### 3.5.1 Data Models +TWAMP Light SAI interface APIs are already defined and is available at below location - -NA +https://github.com/opencomputeproject/SAI/pull/1786 -### 3.5.2 Configuration Commands +## 6 Configuration and management -#### 3.5.2.1 Sender performs one-off packet-count measurement +Following diagram introduces the CLI parameters for the TWAMP Light Session-Sender configuration. -This command allow to create sender session performs one-off packet-count measurement. +![Packet-Count](./images/TWAMP_Light_packet_count.png) -``` -Format: - config twamp-light sender add packet-count +![Continuous with monitor](./images/TWAMP_Light_continuous_monitor.png) -Arguments: - session_name: sender session name. e.g: s1, test_ip1_ip2 - sender_ip_port: sender ip and udp port. e.g: 10.1.1.2:20000 - reflector_ip_port: reflector ip and udp port. e.g: 10.1.1.2:20001 - receive_ports: name of the interface to be configured. e.g: Ethernet0 - period_msecs: sender transmits Test-request packet interval in millisecond. e.g: 10 - timeout_secs: sender receives Test-response packet timeout in second. e.g. 5 - state: test start, can be either "enabled" or "disabled" +![Continuous](./images/TWAMP_Light_continuous.png) -Example: - config twamp-light sender add packet-count s1 10.1.1.2 20.2.2.2 Ethernet28 100 10 10 enabled -``` +### 6.1 Manifest (if the feature is an Application Extension) + +N/A + +### 6.2 CLI -#### 3.5.2.2 Sender performs one-off duration measurement +#### 6.2.1 Configuration commands -This command allow to create sender session performs one-off duration measurement. +New sets of configuration commands are introduced to configure TWAMP Light. + +##### 6.2.1.1 Session-Sender with packet-count mode + +This command is used to create Session-Sender with packet-count mode. ``` Format: - config twamp-light sender add duration + config twamp-light session-sender add packet-count [vrf ] Arguments: - session_name: sender session name. e.g: s1, test_ip1_ip2 + session_name: session sender name. e.g: s1, test_ip1_ip2 + vrf_name: session vrf name. e.g: vrf1 sender_ip_port: sender ip and udp port. e.g: 10.1.1.2:20000 reflector_ip_port: reflector ip and udp port. e.g: 10.1.1.2:20001 - receive_ports: name of the interface to be configured. e.g: Ethernet0 - duration_secs: sender transmits Test-request packet in second. e.g: 10 - period_msecs: sender transmits Test-request packet interval in millisecond. e.g: 10 - timeout_secs: sender receives Test-response packet timeout in second. e.g. 5 - state: test start, can be either "enabled" or "disabled" + packet_count: sender transmits Test-request packet count, e.g: 100 + tx_interval: sender transmits Test-request packet interval in millisecond. e.g: 10 + timeout: sender receives Test-response packet timeout in second. e.g. 5 + statistics_interval: sender calculates measurement statistics in millisecond, e.g: 60 Example: - config twamp-light sender add duration s1 10.1.1.2 20.2.2.2 Ethernet28 60 100 10 enabled + config twamp-light session-sender add packet-count s1 10.1.1.2:20000 20.2.2.2:20001 100 10 60 ``` -#### 3.5.2.3 Sender performs continuous measurement periodically +##### 6.2.1.2 Session-Sender with continuous mode -This command allow to create sender session performs continuous measurement periodically. +This command is used to create Session-Sender with continuous mode. ``` Format: - config twamp-light sender add regular + config twamp-light session-sender add continuous [vrf ] Arguments: session_name: sender session name. e.g: s1, test_ip1_ip2 + vrf_name: session vrf name. e.g: vrf1 sender_ip_port: sender ip and udp port. e.g: 10.1.1.2:20000 reflector_ip_port: reflector ip and udp port. e.g: 10.1.1.2:20001 - receive_ports: name of the interface to be configured. e.g: Ethernet0 - regular_mins: sender transmits Test-request packet in minute. e.g: 10 - packet_count: sender transmits Test-request packet in one round in second. e.g: 10 - period_msecs: sender transmits Test-request packet interval in millisecond. e.g: 10 - timeout_secs: sender receives Test-response packet timeout in second. e.g. 5 - state: test start, can be either "enabled" or "disabled" + monitor_time: sender monitor Test-request packet in minute. e.g: 10 + tx_interval: sender transmits Test-request packet interval in millisecond. e.g: 10 + timeout: sender receives Test-response packet timeout in second. e.g. 5 + statistics_interval: sender calculates measurement statistics in millisecond, e.g: 60 Example: - config twamp-light sender add regular s1 10.1.1.2 192.168.3.2 Ethernet28 10 10 100 10 enabled + config twamp-light session-sender add continuous s1 10.1.1.2:2000 192.168.3.2:20001 10 10 10 60 ``` -#### 3.5.2.4 Start TWAMP Light sender session +##### 6.2.1.3 Start TWAMP Light Session-Sender -This command allow to start the sender session. +This command is used to start the Session-Sender. ``` Format: - config twamp-light sender start + config twamp-light session-sender start Arguments: session_name: session name. e.g: s1 - all: all session + all: all sessions Example: - config twamp-light sender start s1 - config twamp-light sender start all + config twamp-light session-sender start s1 + config twamp-light session-sender start all ``` -#### 3.5.2.5 Stop TWAMP Light sender session +##### 6.2.1.4 Stop TWAMP Light Session-Sender -This command allow to stop the sender session. +This command is used to stop the Session-Sender ``` Format: - config twamp-light sender stop + config twamp-light session-sender stop Arguments: session_name: session name. e.g: s1 - all: all session + all: all sessions Example: - config twamp-light sender stop s1 - config twamp-light sender stop all + config twamp-light session-sender stop s1 + config twamp-light session-sender stop all ``` -#### 3.5.2.6 Reflector replies TWAMP-test packet +##### 6.2.1.5 Session-Reflector -This command allow to create the reflector session. +This command is used to create the Session-Reflector. ``` Format: - config twamp-light reflector add + config twamp-light session-reflector add [vrf ] Arguments: session_name: sender session name. e.g: r1, test_ip1_ip2 + vrf_name: session vrf name. e.g: vrf1 sender_ip_port: sender ip and udp port. e.g: 10.1.1.2:20000 reflector_ip_port: reflector ip and udp port. e.g: 10.1.1.2:20001 - receive_ports: name of the interface to be configured. e.g: Ethernet0 Example: - config twamp-light reflector add r1 10.1.1.2 20.2.2.2 Ethernet4 + config twamp-light reflector add r1 10.1.1.2:20000 20.2.2.2:20001 ``` -#### 3.5.2.7 Remove TWAMP Light session +##### 6.2.1.6 Remove TWAMP Light session -This command allow to remove the session. +This command is used to remove the session. ``` Format: @@ -310,55 +672,57 @@ Format: Arguments: session_name: session name. e.g: s1 - all: all session + all: all sessions Example: config twamp-light remove s1 config twamp-light remove all ``` -### 3.5.3 Show Commands +#### 6.2.2 Show commands -#### 3.5.3.1 Show TWAMP Light session status +New sets of show commands are introduced to display the result of measurement. -This command allow to show the sender and reflector session status. +##### 6.2.2.1 Show TWAMP Light session status + +This command is used to display the Session-Sender and Session-Reflector status. ``` show twamp-light session -Time unit: Regular in minute; Duration in second; Period in millisecond; Timeout in second -TWAMP-Light Sender Sessions -Name Status Sender IP:PORT Reflector IP:PORT Receive Ports Test Ports Type Regular Packet Count Duration Period Timeout Last Start Time Last Stop Time ------- -------- ---------------- ------------------- --------------- ------------ ------------ --------- -------------- ---------- -------- --------- ------------------- ------------------- -sdp34 inactive 30.3.3.2:20000 40.4.4.2:20001 Ethernet12 Ethernet12 Packet-count - 10 - 10 10 2023-02-23 15:23:09 2023-02-23 15:23:10 +TWAMP Light Sender Sessions +Name Status Sender IP:PORT Reflector IP:PORT Type Packet Count Monitor Tx Interval Stats Interval Timeout Last Start Time Last Stop Time +------ -------- ---------------- ------------------- ------------ -------------- ---------- ------------- ---------------- --------- ------------------- ------------------- +sdp34 inactive 30.3.3.2:20000 40.4.4.2:20001 Packet-count 10 - 10 10 10 2023-02-23 15:23:09 2023-02-23 15:23:10 -TWAMP-Light Reflector Sessions -Name Status Sender IP:PORT Reflector IP:PORT Receive Ports Test Ports ------- -------- ---------------- ------------------- --------------- ------------ +TWAMP Light Reflector Sessions +Name Status Sender IP:PORT Reflector IP:PORT +------ -------- ---------------- ------------------- ``` -#### 3.5.3.2 show TWAMP Ligth session delay statistics +##### 6.2.2.2 Show TWAMP Ligth latency and jitter -This command allow to show the sender session delay statistics information. +This command is used to display the latency and jitter. ``` -show twamp-light statistics twoway-delay -Latest two-way delay statistics(nsec): -Name Index Delay(AVG) Jitter(AVG) ------- ------- ------------ ------------- -sdp34 1 20906 134217 - -Total two-way delay statistics(nsec): -Name Delay(AVG) Delay(MIN) Delay(MAX) Jitter(AVG) Jitter(MIN) Jitter(MAX) ------- ------------ ------------ ------------ ------------- ------------- ------------- -sdp34 20906 5 6 134217 3489660 3489660 +show twamp-light statistics twoway-latency +Latest two-way latency statistics(nsec): +Name Index Latency(AVG) Jitter(AVG) +------ ------- -------------- ------------- +sdp34 1 20906 134217 + +Total two-way latency statistics(nsec): +Name Latency(AVG) Latency(MIN) Latency(MAX) Jitter(AVG) Jitter(MIN) Jitter(MAX) +------ -------------- -------------- -------------- ------------- ------------- ------------- +sdp34 20906 5 6 134217 3489660 3489660 ``` -#### 3.5.3.3 show TWAMP Ligth session loss statistics +##### 6.2.2.3 Show TWAMP Ligth packet loss -This command allow to show the sender session loss statistics information. +This command is used to display the packet loss ``` +show twamp-light statistics twoway-loss Latest two-way loss statistics: Index Loss Count Loss Ratio @@ -374,67 +738,249 @@ Name Loss Count(AVG) Loss Count(MIN) Loss Count(MAX) Loss Ratio(AV sdp34 0 0 0 0 0 0 ``` +#### 6.3 YANG + + module sonic-twamp { + + yang-version 1.1; + + namespace "http://github.com/Azure/sonic-twamp"; + prefix stwamp; + + import ietf-inet-types { + prefix inet; + } + + import sonic-vrf { + prefix vrf; + } + + description + "SONiC twamp yang model"; + + revision 2023-06-11 { + description + "Initial revision."; + } + + typedef timestamp_format { + type enumeration { + enum ntp { + description "NTP 64 bit format of a timestamp"; + } + enum ptp { + description "PTPv2 truncated format of a timestamp"; + } + } + description "timestamp format used by Session-Sender or Session-Reflector."; + } + + feature session_sender { + description "This feature relates to the device functions as the TWAMP Session-Sender"; + } + + feature session_reflector { + description "This feature relates to the device functions as the TWAMP Session-Reflector"; + } + + grouping session_parameters { + description "TWAMP session parameters"; + leaf sender_ip { + type inet:ip-address; + mandatory true; + description "Sender IP address"; + } + leaf sender_udp_port { + type inet:port-number { + range "862 | 863 | 1025..65535"; + } + default 862; + mandatory true; + description "Sender UDP port number"; + } + leaf reflector_ip { + type inet:ip-address; + mandatory true; + description "Reflector IP address"; + } + leaf reflector_udp_port { + type inet:port-number { + range "862 | 863 | 1025..65535"; + } + default 863; + description "Reflector UDP port number"; + } + leaf vrf_name { + type union { + type string { + pattern "default"; + } + type leafref { + path "/vrf:sonic-vrf/vrf:VRF/vrf:VRF_LIST/vrf:name"; + } + } + description "VRF name"; + } + } + + container sonic-twamp { + description "Top level container for TWAMP configuration"; + + container TWAMP_SESSION_SENDER { + if-feature session_sender; + description "TWAMP Session-Sender container"; + + list test_session { + key "name"; + unique "sender_ip sender_udp_port reflector_ip reflector_udp_port vrf_name"; + description + "This structure is a container of test session managed objects"; + leaf name { + type string; + description "A unique name for this TWAMP-Test session to be used + for identifying this test session by the + Session-Sender logical entity."; + } + uses session_parameters; + leaf test_session_enable { + type boolean; + default "true"; + description "Whether this TWAMP Test session is enabled"; + } + leaf dscp { + type inet:dscp; + default 0; + description + "DSCP value to be set in the test packet."; + } + leaf ttl { + type inet:ttl; + default 0; + description + "TTL value to be set in the test packet."; + } + leaf packet_timestamp_format { + type timestamp_format; + default ntp; + description "Sender Timestamp format"; + } + leaf packet_padding_size { + type uint16; + default 30; + description + "Size of the Packet Padding. Suggested to run Path MTU + Discovery to avoid packet fragmentation in IPv4 and packet + blackholing in IPv6"; + } + leaf packet_count { + type uint32; + default 1000; + description + "This value determines if the TWAMP-Test session is + bound by number of test packets or not."; + } + leaf tx_interval { + type union { + type uint32 { + range "10 | 100 | 1000 | 30000"; + } + } + units microseconds; + } + leaf statistics_interval { + type uint32; + units millisecond; + default 60; + description + "Interval to calculate performance metric"; + } + leaf monitor_time { + type uint32; + units minutes; + default 0; + description + "The value 0 indicates that the test session SHALL run *forever*"; + } + leaf timeout { + type uint32 { + range "1..10"; + }; + units "seconds"; + default 5; + description + "The timeout value for the Session-Sender to + collect outstanding reflected packets."; + } + } + } + + container TWAMP_SESSION_REFLECTOR { + if-feature session_reflector; + description "TWAMP Session-Reflector container"; + list test_session { + key "name"; + unique "sender_ip sender_udp_port reflector_ip reflector_udp_port vrf_name"; + description + "This structure is a container of test session + managed objects"; + leaf name { + type string; + description "A unique name for this TWAMP-Test session to be used + for identifying this test session by the + Session-Reflector logical entity."; + } + uses session_parameters; + } + } + } + } +## 7 Warmboot and Fastboot Design Impact + +TBD + +## 8 Restrictions/Limitations + +N/A + +## 9 Testing Requirements/Design + +### 9.1 Unit Test cases + +#### 9.1.1 CLI + +1) Verify CLI to create TWAMP Light Session-Sender for packet-count measurement +3) Verify CLI to create TWAMP Light Session-Sender for continuous measurement +4) Verify CLI to create TWAMP Light Session-Reflector +5) Verify CLI to start TWAMP Light Session-Sender +6) Verify CLI to stop TWAMP Light Session-Sender +7) Verify CLI to show TWAMP Light session status +8) Verify CLI to show TWAMP Light Session-Sender statistics + +#### 9.1.2 Functionality +1) Verify TWAMP-test format of the packets are correct +2) Verify TWAMP Light sender performs packet-count measurement +3) Verify TWAMP Light sender performs continuous measurement +4) Verify TWAMP Light sender collects and saves measurement statistics +5) Verify TWAMP Light reflector receives and replies test packets to sender -# 4 Flow Diagrams - -## 4.1 Sender session create - -![image-20230302203200906](./images/TWAMP_Light_create_sender_session.png) - -## 4.2 Reflector session create - -![image-20230302210654109](./images/TWAMP_Light_create_reflector_session.png) - -## 4.3 Sender session collect statistics flow - -![image-20230303165331477](./images/TWAMP_Light_sender_collect_statistics.png) - -## 4.4 Session remove - -![image-20230303140908698](./images/TWAMP_Light_remove_session.png) - -## 4.5 Query HW capability - -![image-20230303135956033](./images/TWAMP_Light_query_hw_capability.png) - -## 4.6 Sender session restart +#### 9.1.3 Scaling -![image-20230303141758674](./images/TWAMP_Light_restart_sender.png) +1) Verify running MAX num TWAMP Light sessions -## 4.7 Sender session stop +#### 9.1.4 SAI -![image-20230303142146721](./images/TWAMP_Light_stop_sender.png) +1) Verify creating TWAMP Light session in SAI +2) Verify setting TWAMP Light session state in SAI +3) Verify removing TWAMP Light session in SAI +4) Verify getting TWAMP Light session in SAI +5) Verify getting TWAMP Light max num session in SAI -# 5 Unit Test +## References -CLI -1) Verify CLI to create TWAMP light sender session for one-off packet-count measurement -2) Verify CLI to create TWAMP light sender session for one-off duration measurement -3) Verify CLI to create TWAMP light sender session for continuous measurement periodically -4) Verify CLI to create TWAMP light reflector session -5) Verify CLI to start TWAMP light sender session -6) Verify CLI to stop TWAMP light sender session -7) Verify CLI to display TWAMP light session status -8) Verify CLI to display TWAMP light sender session statistics +Reference for proposed algorithm: -Functionality -1) Verify TWAMP-test format of the packets are correct -2) Verify TWAMP light sender performs one-off packet-count measurement -3) Verify TWAMP light sender performs one-off duration measurement -4) Verify TWAMP light sender performs continuous measurement periodically -5) Verify TWAMP light sender collects measurement statistics -6) Verify TWAMP light reflector receives and replies test packets to sender - -Scaling -1) Verify running MAX num TWAMP light sessions - -SAI -1) Verify creating TWAMP light session in SAI -2) Verify updating TWAMP light session state in SAI -3) Verify deleting TWAMP light session in SAI -4) Verify geting TWAMP light session in SAI -5) Verify geting TWAMP light max num session in SAI + [RFC5357](https://www.rfc-editor.org/info/rfc5357) diff --git a/doc/TWAMP/images/TWAMP_Light_architecture.png b/doc/TWAMP/images/TWAMP_Light_architecture.png index 4a22c6c329..d472a50db7 100644 Binary files a/doc/TWAMP/images/TWAMP_Light_architecture.png and b/doc/TWAMP/images/TWAMP_Light_architecture.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_continuous.png b/doc/TWAMP/images/TWAMP_Light_continuous.png new file mode 100644 index 0000000000..5dfda0833d Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_continuous.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_continuous_monitor.png b/doc/TWAMP/images/TWAMP_Light_continuous_monitor.png new file mode 100644 index 0000000000..37e2e146e9 Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_continuous_monitor.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_create_reflector_session.png b/doc/TWAMP/images/TWAMP_Light_create_reflector_session.png deleted file mode 100644 index a06f3b7309..0000000000 Binary files a/doc/TWAMP/images/TWAMP_Light_create_reflector_session.png and /dev/null differ diff --git a/doc/TWAMP/images/TWAMP_Light_create_sender_session.png b/doc/TWAMP/images/TWAMP_Light_create_sender_session.png deleted file mode 100644 index 3e63fe8946..0000000000 Binary files a/doc/TWAMP/images/TWAMP_Light_create_sender_session.png and /dev/null differ diff --git a/doc/TWAMP/images/TWAMP_Light_create_session.png b/doc/TWAMP/images/TWAMP_Light_create_session.png new file mode 100644 index 0000000000..1f53720d4d Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_create_session.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_nofiy_session_event.png b/doc/TWAMP/images/TWAMP_Light_nofiy_session_event.png new file mode 100644 index 0000000000..a1b351a15a Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_nofiy_session_event.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_packet_count.png b/doc/TWAMP/images/TWAMP_Light_packet_count.png new file mode 100644 index 0000000000..8f0ff72593 Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_packet_count.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_query_hw_capability.png b/doc/TWAMP/images/TWAMP_Light_query_hw_capability.png index 573e4d9835..c55ad18c5e 100644 Binary files a/doc/TWAMP/images/TWAMP_Light_query_hw_capability.png and b/doc/TWAMP/images/TWAMP_Light_query_hw_capability.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_remove_session.png b/doc/TWAMP/images/TWAMP_Light_remove_session.png index 228d1e29e8..52dba2759e 100644 Binary files a/doc/TWAMP/images/TWAMP_Light_remove_session.png and b/doc/TWAMP/images/TWAMP_Light_remove_session.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_restart_sender.png b/doc/TWAMP/images/TWAMP_Light_restart_sender.png deleted file mode 100644 index bd699e92f0..0000000000 Binary files a/doc/TWAMP/images/TWAMP_Light_restart_sender.png and /dev/null differ diff --git a/doc/TWAMP/images/TWAMP_Light_role.png b/doc/TWAMP/images/TWAMP_Light_role.png new file mode 100644 index 0000000000..8a0f9e729e Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_role.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_sender_collect_statistics.png b/doc/TWAMP/images/TWAMP_Light_sender_collect_statistics.png deleted file mode 100644 index 0b27eb12da..0000000000 Binary files a/doc/TWAMP/images/TWAMP_Light_sender_collect_statistics.png and /dev/null differ diff --git a/doc/TWAMP/images/TWAMP_Light_set_session_state.png b/doc/TWAMP/images/TWAMP_Light_set_session_state.png new file mode 100644 index 0000000000..c16d427f40 Binary files /dev/null and b/doc/TWAMP/images/TWAMP_Light_set_session_state.png differ diff --git a/doc/TWAMP/images/TWAMP_Light_stop_sender.png b/doc/TWAMP/images/TWAMP_Light_stop_sender.png deleted file mode 100644 index 547d431a15..0000000000 Binary files a/doc/TWAMP/images/TWAMP_Light_stop_sender.png and /dev/null differ