diff --git a/doc/OCS/SAI-Proposal-OCS.md b/doc/OCS/SAI-Proposal-OCS.md new file mode 100755 index 000000000..9425bb5ea --- /dev/null +++ b/doc/OCS/SAI-Proposal-OCS.md @@ -0,0 +1,307 @@ +SAI Optical Circuit Switch API Proposal +===================== + +Title | SAI Optical Circuit Switch API Proposal +------------|---------------------- +Authors | Coherent +Status | Draft +Type | Standards track +Created | 11/20/2025 +SAI-Version | ? +------------------------------- + +# 1. Scope + +This document defines the draft technical specifications for the API in Open Compute Project Switch Abstraction Interface (SAI) used to support the configurations of OCS port and OCS cross connect in the OCS device, as well as the retrieval of OCS operational status data from OCS device. + +# 2. Overview +As AI clusters reach massive proportions, Optical Circuit Switching (OCS) is becoming essential. It slashes energy overhead, reduces network complexity, and paves the way for revolutionary data center designs and applications. OCS device can have varying capacities from different hardware or module, defined as "number of A side ports" × "number of B side ports" (e.g., 64×64, 320×320, etc.). OCS cross-connect is direct optical transmission channel between different optical links, it is provisioned between port on one side (e.g. A side) and port on the other side (e.g. B side). + +Main functions of the OCS SAI definitions include: +* Support creation and remove of OCS cross-connects, including both individual switching and simultaneous switching with multiple connections. +* Support OCS ports operation, including the ability to set a state to any specified group of ports. +* Support the retrieval of current operational status on OCS port. +* Support the retrieval of hardware-specific OCS module data, such as port physical mapping information and factory insertion loss values etc. + +# 3. OCS Port +## 3.1 OCS Port Discovery and Creation +* The capacity of OCS device (number of A side ports and number of B side ports) and corresponding default port configurations are defined in OCS device specific template/profile, example as below: +```cpp +# name state +OCS_PORT|1A normal +OCS_PORT|1B normal +OCS_PORT|2A normal +OCS_PORT|2B normal +OCS_PORT|3A normal +OCS_PORT|3B normal +OCS_PORT|4A normal +OCS_PORT|4B normal +OCS_PORT|5A normal +OCS_PORT|5B normal +OCS_PORT|6A normal +OCS_PORT|6B normal +OCS_PORT|7A normal +OCS_PORT|7B normal +OCS_PORT|8A normal +OCS_PORT|8B normal +... +``` +* OCS ports are created by upstream application using SAI API by parsing OCS device capability specific template/profile. +* After creation, OCS port is not deletable. +## 3.2 OCS Port Configuration +* The key configurable parameter is the override state (normal or force-blocked, etc.). +* Override state configuration can be changed regardless wether there's OCS cross-connect on the port. +## 3.3 OCS Port Operational Status +The OCS port operational status relies on the override state and the presence of an OCS cross-connect configuration on the port. + +![OCS Port Operational Status](images/port_status.png) +# 4. OCS Cross-Connects +OCS cross-connects are dynamically created and removed via SAI APIs. +## 4.1. Object Relationships +* The SAI object IDs of OCS ports serve as the SAI attributes for both the ingress and egress ports in OCS cross-connect SAI object. +* OCS ports are referenced to OCS cross-connect by their SAI object IDs in cross-connect attributes. +## 4.2. Cross-Connect Configuration +* To have fast switching performance, SAI bulk create/remove APIs are used for management of OCS cross-connect configurations. +* OCS cross-connect can not be provisioned between two A side ports or two B side ports. +* One OCS port can only involved in one OCS cross-connect; when switching existing OCS cross-connect, e.g. switch from 1A-1B to 1A-2B, the upstream application need to use SAI API to remove 1A-1B and then create 1A-2B. +# 5. OCS Cross-Connects Factory Data +OCS cross-connect factory data are read-only information about insertion loss measurements of all possible cross-connects. +* Factory data are measured during the manufacturing calibration phase. +* The measurement is for every possible optical path (cross-connect) with an optical spectrum (central frequency) in specific environment (temperature). + +# 6. OCS SAI Object and Attributes +| SAI Object | SAI Attributes | SAI Data Type | +| ---- | ---- | ---- | +|SAI_OBJECT_TYPE_OCS_CROSS_CONNECT | SAI_OCS_CROSS_CONNECT_ATTR_A_SIDE_PORT_ID | sai_object_id_t +| | SAI_OCS_CROSS_CONNECT_ATTR_B_SIDE_PORT_ID | sai_object_id_t +| SAI_OBJECT_TYPE_OCS_PORT | SAI_OCS_PORT_ATTR_NAME | sai_u8_list_t +| | SAI_OCS_PORT_ATTR_OVERRIDE_STATE | sai_ocs_port_override_state_t +| | SAI_OCS_PORT_ATTR_OPER_STATUS | sai_ocs_port_status_t +| | SAI_OCS_PORT_ATTR_PHYSICAL_MAPPING | sai_u8_list_t +SAI_OBJECT_TYPE_OCS_CROSS_CONNECT_FACTORY_DATA | SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_A_SIDE_PORT_NAME | sai_u8_list_t +| | SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_B_SIDE_PORT_NAME | sai_u8_list_t +| | SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_FREQUENCY_THZ | sai_s32_list_t +| | SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_MEASURED_TEMPERATURE | sai_s32_list_t +| | SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_INSERTION_LOSS_DB | sai_s32_list_t +| | SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_INSERTION_LOSS_ACCURACY_DB | sai_s32_list_t + +# 7. OCS SAI APIs +```cpp +** + * @brief OCS methods table retrieved with sai_api_query() + */ +typedef struct _sai_ocs_api_t +{ + sai_create_ocs_port_fn create_ocs_port; + sai_remove_ocs_port_fn remove_ocs_port; + sai_set_ocs_port_attribute_fn set_ocs_port_attribute; + sai_get_ocs_port_attribute_fn get_ocs_port_attribute; + sai_bulk_object_create_fn create_ocs_ports; + sai_bulk_object_remove_fn remove_ocs_ports; + sai_bulk_object_set_attribute_fn set_ocs_ports_attribute; + sai_bulk_object_get_attribute_fn get_ocs_ports_attribute; + sai_create_ocs_cross_connect_fn create_ocs_cross_connect; + sai_remove_ocs_cross_connect_fn remove_ocs_cross_connect; + sai_set_ocs_cross_connect_attribute_fn set_ocs_cross_connect_attribute; + sai_get_ocs_cross_connect_attribute_fn get_ocs_cross_connect_attribute; + sai_bulk_object_create_fn create_ocs_cross_connects; + sai_bulk_object_remove_fn remove_ocs_cross_connects; + sai_bulk_object_set_attribute_fn set_ocs_cross_connects_attribute; + sai_bulk_object_get_attribute_fn get_ocs_cross_connects_attribute; + sai_create_ocs_cross_connect_factory_data_fn create_ocs_cross_connect_factory_data; + sai_remove_ocs_cross_connect_factory_data_fn remove_ocs_cross_connect_factory_data; + sai_set_ocs_cross_connect_factory_data_attribute_fn set_ocs_cross_connect_factory_data_attribute; + sai_get_ocs_cross_connect_factory_data_attribute_fn get_ocs_cross_connect_factory_data_attribute; + sai_bulk_object_create_fn create_ocs_cross_connect_factory_datas; + sai_bulk_object_remove_fn remove_ocs_cross_connect_factory_datas; + sai_bulk_object_set_attribute_fn set_ocs_cross_connect_factory_datas_attribute; + sai_bulk_object_get_attribute_fn get_ocs_cross_connect_factory_datas_attribute; + +} sai_ocs_api_t; +``` + +# 8. OCS SAI API Usage Examples +## 8.1. Usage Example: Create OCS Ports +The following example demonstrates how to create OCS ports by specifying port name and port override state. Note: after OCS ports are created, the returned SAI object IDs will be buffered (_port_key_to_saiobjid_map in this example) and they will be used for following-up set/get operations on OCS ports. +```cpp + vector keys = {"1A", "1B", "2A", "2B", "3A", "3B"}; + + vector> attr_data_list; + vector attr_count_list; + vector attr_ptr_list; + + for (auto& key : keys) + { + sai_attribute_t attr; + vector attrs; + + attr.id = SAI_OCS_PORT_ATTR_NAME; + attr.value.u8list.count = (uint32_t)key.size(); + attr.value.u8list.list = (uint8_t*)const_cast(key.data()); + attrs.push_back(attr); + + attr.id = SAI_OCS_PORT_ATTR_OVERRIDE_STATE; + attr.value.u32 = (uint32_t)SAI_OCS_PORT_OVERRIDE_STATE_NORMAL; + attrs.push_back(attr); + + attr_data_list.push_back(attrs); + attr_count_list.push_back(static_cast(attr_data_list.back().size())); + attr_ptr_list.push_back(attr_data_list.back().data()); + } + + auto cnt = keys.size(); + vector oid_list(cnt, SAI_NULL_OBJECT_ID); + vector status_list(cnt, SAI_STATUS_SUCCESS); + + auto status = sai_ocs_api->create_ocs_ports( + gSwitchId, (int32_t)cnt, attr_count_list.data(), attr_ptr_list.data(), + SAI_BULK_OP_ERROR_MODE_STOP_ON_ERROR, + oid_list.data(), status_list.data() + ); + + if (SAI_STATUS_SUCCESS == status) + { + for (size_t i = 0; i < cnt; ++i) + { + _port_key_to_saiobjid_map[keys[i]] = oid_list[i]; + } + } +``` + +## 8.2. Usage Example: Change OCS Port Configuration +Following is example about how to set override status of OCS port 1A to force-blocked. +```cpp +string port_id = "1A"; +auto it = _port_key_to_saiobjid_map.find(port_id); + +if (it != _port_key_to_saiobjid_map.end()) +{ + sai_attribute_t attr; + attr.id = SAI_OCS_PORT_ATTR_OVERRIDE_STATE; + attr.value.u32 = (uint32_t)SAI_OCS_PORT_OVERRIDE_STATE_FORCE_BLOCKED; + + auto status = sai_ocs_api->set_ocs_port_attribute(it->second, &attr); +} +``` +## 8.3. Usage Example: Get an OCS Port Operational Status +Following is an example of how to get operational status of OCS port 1A +```cpp +string port = "1A"; +auto it = _port_key_to_saiobjid_map.find(port); + +if (_port_key_to_saiobjid_map.end() != it) +{ + sai_attribute_t attr; + sai_status_t status; + attr.id = SAI_OCS_PORT_ATTR_OPER_STATUS; + + status = sai_ocs_api->get_ocs_port_attribute(it->second, 1, &attr); +} +``` +## 8.4. Usage Example: Get All OCS Port Operational Status +Following is an example of how to get operational status of all OCS ports +```cpp +vector oid_list; +vector port_keys; + +for (auto& p : _port_key_to_saiobjid_map) +{ + port_keys.push_back(p.first); + oid_list.push_back(p.second); +} + +auto portNum = oid_list.size(); + +std::vector attrs(portNum); +vector attr_count_list(portNum, 1); +vector attr_ptr_list(portNum); + +for (size_t i = 0; i < (uint32_t)portNum; i++) +{ + attrs[i].id = SAI_OCS_PORT_ATTR_OPER_STATUS; + attr_ptr_list[i] = &attrs[i]; +} + +vector status_list(portNum, SAI_STATUS_SUCCESS); + +auto status = sai_ocs_api->get_ocs_ports_attribute( + (int32_t)portNum, + oid_list.data(), + attr_count_list.data(), + attr_ptr_list.data(), + SAI_BULK_OP_ERROR_MODE_STOP_ON_ERROR, + status_list.data() +); +``` +## 8.5. Usage Example: Create OCS Cross-Connects +The following example demonstrates how to create multiple OCS cross-connects: 1A-1B, 2A-2B, 3A-2B and 4A-4B. Bulk creation API is used to have fast OCS cross-connect switching performance. Note: the returned SAI object IDs need to be buffered and they will be used for remove operations. +```cpp + vector> attr_data_list; + vector attr_count_list; + vector attr_ptr_list; + + vector > conns = {make_pair("1A", "1B"), make_pair("2A", "2B"), make_pair("3A", "3B"), make_pair("4A", "4B")}; + + for (auto& conn : conns) + { + sai_attribute_t attr; + vector attrs; + + auto it_a = _port_key_to_saiobjid_map.find(conn.first); + + if (it_a == _port_key_to_saiobjid_map.end()) + { + continue; + } + + attr.id = SAI_OCS_CROSS_CONNECT_ATTR_A_SIDE_PORT_ID; + attr.value.oid = it_a->second; + attrs.push_back(attr); + + auto it_b = _port_key_to_saiobjid_map.find(conn.second); + + if (it_b == _port_key_to_saiobjid_map.end()) + { + continue; + } + + attr.id = SAI_OCS_CROSS_CONNECT_ATTR_B_SIDE_PORT_ID; + attr.value.oid = it_b->second; + attrs.push_back(attr); + + attr_data_list.push_back(attrs); + attr_count_list.push_back(static_cast(attr_data_list.back().size())); + attr_ptr_list.push_back(attr_data_list.back().data()); + } + + auto conn_num = attr_data_list.size(); + vector oid_list(conn_num, SAI_NULL_OBJECT_ID); + vector status_list(conn_num, SAI_STATUS_SUCCESS); + + auto status = sai_ocs_api->create_ocs_cross_connects( + gSwitchId, (int32_t)conn_num, attr_count_list.data(), attr_ptr_list.data(), + SAI_BULK_OP_ERROR_MODE_STOP_ON_ERROR, + oid_list.data(), status_list.data() + ); +``` +## 8.6. Usage Example: Delete OCS Cross-Connects +The following example demonstrates how to remove multiple OCS cross-connects. +```cpp +vector keys = {"1A-1B", "2A-2B"}; +vector oid_list; +vector status_list(keys.size(), SAI_STATUS_SUCCESS); + +for (auto& key : keys) +{ + auto oid = getFromCrsKeyToSaiObjIdMap(key); + + if (0 == oid) continue; + + oid_list.emplace_back(oid); +} + +auto status = sai_ocs_api->remove_ocs_cross_connects((int32_t)oid_list.size(), + oid_list.data(), + SAI_BULK_OP_ERROR_MODE_STOP_ON_ERROR, + status_list.data()); +``` \ No newline at end of file diff --git a/doc/OCS/images/port_status.png b/doc/OCS/images/port_status.png new file mode 100755 index 000000000..b470c2aa3 Binary files /dev/null and b/doc/OCS/images/port_status.png differ diff --git a/experimental/saiexperimentalocs.h b/experimental/saiexperimentalocs.h new file mode 100644 index 000000000..724dde8c5 --- /dev/null +++ b/experimental/saiexperimentalocs.h @@ -0,0 +1,471 @@ +/** + * Copyright (c) 2014 Microsoft Open Technologies, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. You may obtain + * a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + * + * THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR + * CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT + * LIMITATION ANY IMPLIED WARRANTIES OR CONDITIONS OF TITLE, FITNESS + * FOR A PARTICULAR PURPOSE, MERCHANTABILITY OR NON-INFRINGEMENT. + * + * See the Apache Version 2.0 License for specific language governing + * permissions and limitations under the License. + * + * Microsoft would like to thank the following companies for their review and + * assistance with these files: Intel Corporation, Mellanox Technologies Ltd, + * Dell Products, L.P., Facebook, Inc., Marvell International Ltd. + * + * @file saiexperimentalocs.h + * + * @brief This module defines SAI OCS + * + * @warning This module is a SAI experimental module + */ + +#if !defined (__SAIEXPERIMENTALOCS_H_) +#define __SAIEXPERIMENTALOCS_H_ + +#include + +/** + * @defgroup SAIEXPERIMENTALOCS SAI - Experimental: OCS specific API definitions + * + * @{ + */ + +/** + * @brief List of OCS cross connect attributes + */ +typedef enum _sai_ocs_cross_connect_attr_t +{ + /** + * @brief Start of attributes + */ + SAI_OCS_CROSS_CONNECT_ATTR_START, + + /** + * @brief A side port + * + * @type sai_object_id_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + * @objects SAI_OBJECT_TYPE_OCS_PORT + */ + SAI_OCS_CROSS_CONNECT_ATTR_A_SIDE_PORT_ID = SAI_OCS_CROSS_CONNECT_ATTR_START, + + /** + * @brief B side port + * + * @type sai_object_id_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + * @objects SAI_OBJECT_TYPE_OCS_PORT + */ + SAI_OCS_CROSS_CONNECT_ATTR_B_SIDE_PORT_ID, + + /** + * @brief End of attributes + */ + SAI_OCS_CROSS_CONNECT_ATTR_END, + + /** Custom range base value */ + SAI_OCS_CROSS_CONNECT_ATTR_CUSTOM_RANGE_START = 0x10000000, + + /** End of custom range base */ + SAI_OCS_CROSS_CONNECT_ATTR_CUSTOM_RANGE_END, + +} sai_ocs_cross_connect_attr_t; + +/** + * @brief Create cross connect entry. + * + * @param[out] ocs_cross_connect_id OCS cross connect id + * @param[in] switch_id Switch id + * @param[in] attr_count Number of attributes + * @param[in] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_create_ocs_cross_connect_fn)( + _Out_ sai_object_id_t *ocs_cross_connect_id, + _In_ sai_object_id_t switch_id, + _In_ uint32_t attr_count, + _In_ const sai_attribute_t *attr_list); + +/** + * @brief Remove cross connect entry + * + * @param[in] ocs_cross_connect_id OCS cross connect Id + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_remove_ocs_cross_connect_fn)( + _In_ sai_object_id_t ocs_cross_connect_id); + +/** + * @brief Set cross connect entry attribute + * + * @param[in] ocs_cross_connect_id OCS cross connect id + * @param[in] attr Attribute + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_set_ocs_cross_connect_attribute_fn)( + _In_ sai_object_id_t ocs_cross_connect_id, + _In_ const sai_attribute_t *attr); + +/** + * @brief Get OCS cross connect entry attribute + * + * @param[in] ocs_cross_connect_id OCS cross connect id + * @param[in] attr_count Number of attributes + * @param[inout] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_get_ocs_cross_connect_attribute_fn)( + _In_ sai_object_id_t ocs_cross_connect_id, + _In_ uint32_t attr_count, + _Inout_ sai_attribute_t *attr_list); + +/** + * @brief Attribute data for OCS port override state parameter + */ +typedef enum _sai_ocs_port_override_state_t +{ + /** + * @brief First element that the beam hits is powered off, for testing + */ + SAI_OCS_PORT_OVERRIDE_STATE_POWERED_OFF, + + /** + * @brief Default, state to be determined by presence of cross-connect + */ + SAI_OCS_PORT_OVERRIDE_STATE_NORMAL, + + /** + * @brief Regardless of cross-connect presence state, blocks the port + */ + SAI_OCS_PORT_OVERRIDE_STATE_FORCE_BLOCKED + +} sai_ocs_port_override_state_t; + +/** + * @brief Attribute data for OCS port status parameter + */ +typedef enum _sai_ocs_port_status_t +{ + /** + * @brief Default status for any port which is with no configuration + */ + SAI_OCS_PORT_STATUS_BLOCKED, + + /** + * @brief Insertion loss is >0.5dB of target + */ + SAI_OCS_PORT_STATUS_TUNING, + + /** + * @brief Insertion loss is within 0.5dB of target + */ + SAI_OCS_PORT_STATUS_TUNED, + + /** + * @brief If there is a hardware failure + */ + SAI_OCS_PORT_STATUS_FAILED +} sai_ocs_port_status_t; + +/** + * @brief List of OCS port attributes + */ +typedef enum _sai_ocs_port_attr_t +{ + /** + * @brief Start of device port attributes + */ + SAI_OCS_PORT_ATTR_START, + + /** + * @brief Unique identifier for a port + * + * @type sai_u8_list_t + * @flags MANDATORY_ON_CREATE | CREATE_ONLY + */ + SAI_OCS_PORT_ATTR_NAME = SAI_OCS_PORT_ATTR_START, + + /** + * @brief Overrides the status imposed by the programmed cross-connects + * + * @type sai_ocs_port_override_state_t + * @flags CREATE_AND_SET + * @default SAI_OCS_PORT_OVERRIDE_STATE_NORMAL + */ + SAI_OCS_PORT_ATTR_OVERRIDE_STATE, + + /** + * @brief Operational status of the port + * + * @type sai_ocs_port_status_t + * @flags READ_ONLY + */ + SAI_OCS_PORT_ATTR_OPER_STATUS, + + /** + * @brief Mapping between face plate port and OCS physical element + * + * @type sai_u8_list_t + * @flags READ_ONLY + */ + SAI_OCS_PORT_ATTR_PHYSICAL_MAPPING, + + /** + * @brief End of attributes + */ + SAI_OCS_PORT_ATTR_END, +} sai_ocs_port_attr_t; + +/** + * @brief Defines the operational status of the OCS port + */ +typedef struct _sai_ocs_port_status_notification_t +{ + /** + * @brief OCS Port id. + * + * @objects SAI_OBJECT_TYPE_OCS_PORT + */ + sai_object_id_t port_id; + + /** OCS port operational status */ + sai_ocs_port_status_t port_state; +} sai_ocs_port_status_notification_t; + +/** + * @brief Create port entry. + * + * @param[out] ocs_port_id OCS port id + * @param[in] switch_id Switch id + * @param[in] attr_count Number of attributes + * @param[in] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_create_ocs_port_fn)( + _Out_ sai_object_id_t *ocs_port_id, + _In_ sai_object_id_t switch_id, + _In_ uint32_t attr_count, + _In_ const sai_attribute_t *attr_list); + +/** + * @brief Remove port entry + * + * @param[in] ocs_port_id OCS port Id + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_remove_ocs_port_fn)( + _In_ sai_object_id_t ocs_port_id); + +/** + * @brief Set port entry attribute + * + * @param[in] ocs_port_id OCS port id + * @param[in] attr Attribute + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_set_ocs_port_attribute_fn)( + _In_ sai_object_id_t ocs_port_id, + _In_ const sai_attribute_t *attr); + +/** + * @brief Get OCS port entry attribute + * + * @param[in] ocs_port_id OCS port id + * @param[in] attr_count Number of attributes + * @param[inout] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_get_ocs_port_attribute_fn)( + _In_ sai_object_id_t ocs_port_id, + _In_ uint32_t attr_count, + _Inout_ sai_attribute_t *attr_list); + +/** + * @brief OCS port state change notification + * + * Passed as a parameter into sai_initialize_switch() + * + * @count data[count] + * + * @param[in] count Number of notifications + * @param[in] data Array of port operational status + */ +typedef void (*sai_ocs_port_state_change_notification_fn)( + _In_ uint32_t count, + _In_ const sai_ocs_port_status_notification_t *data); + +/** + * @brief List of OCS cross connect factory data attributes. Inventory data for all possible cross-connects, + * factory insertion loss measurements + */ +typedef enum _sai_ocs_cross_connect_factory_data_attr_t +{ + /** + * @brief Start of attributes + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_START, + + /** + * @brief Name of A side port in a cross connection + * + * @type sai_u8_list_t + * @flags READ_ONLY + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_A_SIDE_PORT_NAME = SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_START, + + /** + * @brief Name of B side port in a cross connection. + * + * @type sai_u8_list_t + * @flags READ_ONLY + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_B_SIDE_PORT_NAME, + + /** + * @brief Center frequency at which insertion loss is measured, e.g., 229.1 (O-band) 193.5, use int32 for representation of decimal value + * + * List of center frequency values. Use int32 for representation of decimal value with 3 fraction digits + * + * @type sai_s32_list_t + * @flags READ_ONLY + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_FREQUENCY_THZ, + + /** + * @brief Internal temperature sensor that correlates with the ambient temperature at which + * the insertion loss is measured in Celsius, e.g., 25.00 + * + * List of temperatures. Use int32 for representation of decimal value with 2 fraction digits + * + * @type sai_s32_list_t + * @flags READ_ONLY + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_MEASURED_TEMPERATURE, + + /** + * @brief Factory insertion loss in dB, e.g. 1.23 + * + * List of insertion loss values. Use int32 for representation of decimal value with 2 fraction digits + * + * @type sai_s32_list_t + * @flags READ_ONLY + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_INSERTION_LOSS_DB, + + /** + * @brief Factory insertion loss in dB, e.g. 1.23 + * + * List of insertion loss accuracy values. Use int32 for representation of decimal value with 2 fraction digits + * + * @type sai_s32_list_t + * @flags READ_ONLY + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_INSERTION_LOSS_ACCURACY_DB, + + /** + * @brief End of attributes + */ + SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_END, +} sai_ocs_cross_connect_factory_data_attr_t; + +/** + * @brief Create OCS cross connect factory data entry. + * + * @param[out] ocs_cross_connect_factory_data_id OCS cross connect factory data id + * @param[in] switch_id Switch id + * @param[in] attr_count Number of attributes + * @param[in] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_create_ocs_cross_connect_factory_data_fn)( + _Out_ sai_object_id_t *ocs_cross_connect_factory_data_id, + _In_ sai_object_id_t switch_id, + _In_ uint32_t attr_count, + _In_ const sai_attribute_t *attr_list); + +/** + * @brief Remove OCS cross connect factory data entry + * + * @param[in] ocs_cross_connect_factory_data_id OCS cross connect Id + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_remove_ocs_cross_connect_factory_data_fn)( + _In_ sai_object_id_t ocs_cross_connect_factory_data_id); + +/** + * @brief Set OCS cross connect factory data entry attribute + * + * @param[in] ocs_cross_connect_factory_data_id OCS cross connect id + * @param[in] attr Attribute + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_set_ocs_cross_connect_factory_data_attribute_fn)( + _In_ sai_object_id_t ocs_cross_connect_factory_data_id, + _In_ const sai_attribute_t *attr); + +/** + * @brief Get OCS cross connect factory data attribute + * + * @param[in] ocs_cross_connect_factory_data_id OCS cross connect id + * @param[in] attr_count Number of attributes + * @param[inout] attr_list Array of attributes + * + * @return #SAI_STATUS_SUCCESS on success, failure status code on error + */ +typedef sai_status_t (*sai_get_ocs_cross_connect_factory_data_attribute_fn)( + _In_ sai_object_id_t ocs_cross_connect_factory_data_id, + _In_ uint32_t attr_count, + _Inout_ sai_attribute_t *attr_list); + +/** + * @brief OCS methods table retrieved with sai_api_query() + */ +typedef struct _sai_ocs_api_t +{ + sai_create_ocs_port_fn create_ocs_port; + sai_remove_ocs_port_fn remove_ocs_port; + sai_set_ocs_port_attribute_fn set_ocs_port_attribute; + sai_get_ocs_port_attribute_fn get_ocs_port_attribute; + sai_bulk_object_create_fn create_ocs_ports; + sai_bulk_object_remove_fn remove_ocs_ports; + sai_bulk_object_set_attribute_fn set_ocs_ports_attribute; + sai_bulk_object_get_attribute_fn get_ocs_ports_attribute; + sai_create_ocs_cross_connect_fn create_ocs_cross_connect; + sai_remove_ocs_cross_connect_fn remove_ocs_cross_connect; + sai_set_ocs_cross_connect_attribute_fn set_ocs_cross_connect_attribute; + sai_get_ocs_cross_connect_attribute_fn get_ocs_cross_connect_attribute; + sai_bulk_object_create_fn create_ocs_cross_connects; + sai_bulk_object_remove_fn remove_ocs_cross_connects; + sai_bulk_object_set_attribute_fn set_ocs_cross_connects_attribute; + sai_bulk_object_get_attribute_fn get_ocs_cross_connects_attribute; + sai_create_ocs_cross_connect_factory_data_fn create_ocs_cross_connect_factory_data; + sai_remove_ocs_cross_connect_factory_data_fn remove_ocs_cross_connect_factory_data; + sai_set_ocs_cross_connect_factory_data_attribute_fn set_ocs_cross_connect_factory_data_attribute; + sai_get_ocs_cross_connect_factory_data_attribute_fn get_ocs_cross_connect_factory_data_attribute; + sai_bulk_object_create_fn create_ocs_cross_connect_factory_datas; + sai_bulk_object_remove_fn remove_ocs_cross_connect_factory_datas; + sai_bulk_object_set_attribute_fn set_ocs_cross_connect_factory_datas_attribute; + sai_bulk_object_get_attribute_fn get_ocs_cross_connect_factory_datas_attribute; + +} sai_ocs_api_t; + +/** + * @} + */ +#endif /** __SAIEXPERIMENTALOCS_H_ */ diff --git a/experimental/saiextensions.h b/experimental/saiextensions.h index f43ee480a..190f0970b 100644 --- a/experimental/saiextensions.h +++ b/experimental/saiextensions.h @@ -51,6 +51,7 @@ #include "saiexperimentaldashdirectionlookup.h" #include "saiexperimentaldashacl.h" #include "saiexperimentalbmtor.h" +#include "saiexperimentalocs.h" /** * @brief Extensions to SAI APIs @@ -95,6 +96,8 @@ typedef enum _sai_api_extensions_t SAI_API_DASH_TRUSTED_VNI, + SAI_API_OCS, + /* Add new experimental APIs above this line */ SAI_API_EXTENSIONS_RANGE_END diff --git a/experimental/saitypesextensions.h b/experimental/saitypesextensions.h index 09ede1f56..2a5e23d52 100644 --- a/experimental/saitypesextensions.h +++ b/experimental/saitypesextensions.h @@ -100,6 +100,12 @@ typedef enum _sai_object_type_extensions_t SAI_OBJECT_TYPE_ENI_TRUSTED_VNI_ENTRY, + SAI_OBJECT_TYPE_OCS_CROSS_CONNECT, + + SAI_OBJECT_TYPE_OCS_PORT, + + SAI_OBJECT_TYPE_OCS_CROSS_CONNECT_FACTORY_DATA, + /* Add new experimental object types above this line */ SAI_OBJECT_TYPE_EXTENSIONS_RANGE_END diff --git a/inc/saiobject.h b/inc/saiobject.h index 84dd67018..875669f33 100644 --- a/inc/saiobject.h +++ b/inc/saiobject.h @@ -55,6 +55,7 @@ #include #include #include +#include /** * @defgroup SAIOBJECT SAI - Object API definitions. diff --git a/inc/saiswitch.h b/inc/saiswitch.h index d90b10800..abb39d53e 100644 --- a/inc/saiswitch.h +++ b/inc/saiswitch.h @@ -3373,6 +3373,17 @@ typedef enum _sai_switch_attr_t */ SAI_SWITCH_ATTR_MACSEC_POST_STATUS_NOTIFY, + /** + * @brief Set Switch OCS port state change event notification callback function passed to the adapter. + * + * Use sai_ocs_port_state_change_notification_fn as notification function. + * + * @type sai_pointer_t sai_ocs_port_state_change_notification_fn + * @flags CREATE_AND_SET + * @default NULL + */ + SAI_SWITCH_ATTR_OCS_PORT_STATE_CHANGE_NOTIFY, + /** * @brief Callback for completion status of all the IPSEC ports serviced by this IPSEC engine * diff --git a/meta/acronyms.txt b/meta/acronyms.txt index c960e4ced..a54969691 100644 --- a/meta/acronyms.txt +++ b/meta/acronyms.txt @@ -109,6 +109,7 @@ NTPCLIENT - Network Time Protocol Client NTPSERVER - Network Time Protocol Server NVGRE - Network Virtualization using Generic Routing Encapsulation OAM - Operations Administration and Maintenance +OCS - Optical Circuit Switch OUI - Organizationally Unique Identifier P4RT - Programming Protocol-independent Packet Processors Runtime PAM4 - Pulse Amplitude Modulation 4-level