add SAI definitions for optical circuit switch #2229

wni0812 · 2025-12-05T03:09:02Z

Add API definitions for Optical Circuit Switch, mainly including:

Creation and remove of OCS cross-connects, including both individual switching and simultaneous switching with multiple connections.
OCS ports operation, including the ability to set a state to any specified group of ports.
Retrieval of current operational status on OCS port.
Retrieval of hardware-specific OCS module data, such as port physical mapping information and factory insertion loss values etc.

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

jjin62 · 2025-12-19T04:12:00Z

Need to add new SAI objects and types for OCS in SAI extension header files. Without the following change, the SAI OCS object/api will not be processed by parser to generating meta data.

saiextensions.h

/* OCS extension */
#include "saiexperimentalocs.h"

...
   SAI_API_DASH_APPLIANCE,

   SAI_API_OCS_CROSS_CONNECT,

   SAI_API_OCS_PORT,

    /* Add new experimental APIs above this line */

   SAI_API_EXTENSIONS_RANGE_END

} sai_api_extensions_t;

#endif /* __SAIEXTENSIONS_H_ */

saitypesextensions.h‎

    SAI_OBJECT_TYPE_DASH_APPLIANCE,

    SAI_OBJECT_TYPE_OCS_CROSS_CONNECT,

    SAI_OBJECT_TYPE_OCS_PORT,

    /* Add new experimental object types above this line */

    SAI_OBJECT_TYPE_EXTENSIONS_RANGE_END

} sai_object_type_extensions_t

jjin62 · 2025-12-19T04:17:53Z

experimental/saiexperimentalocs.h

+     * @objects SAI_OBJECT_TYPE_OCS_PORT
+     */
+    SAI_OCS_CROSS_CONNECT_ATTR_B_SIDE_PORT_ID,
+


should we add operational status so user know if a connection is up or down, without looking at the corresponding port status?

/** * @brief Cross connect operation status * * @type sai_ocs_cross_connect_oper_status_t * @flags READ_ONLY */ SAI_OCS_CROSS_CONNECT_ATTR_OPER_STATUS,

For SAI layer as the physical information, cross-connect is more about configuration and the configurational result success/failure. For upper layer, like swss, if necessary, it can use port status and other alarm information to have a logic result about cross-connect operational status.

jjin62 · 2025-12-19T04:20:56Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief Default status for any port which is with no configuration
+     */
+    SAI_OCS_PORT_STATUS_BLOCKED,


This default value (SAI_OCS_PORT_STATUS_BLOCKED) conflicts to the default of override_state_t, SAI_OCS_PORT_OVERRIDE_STATE_NORMAL??

SAI_OCS_PORT_STATUS_BLOCKED is a value of OCS port operational status while SAI_OCS_PORT_OVERRIDE_STATE_NORMAL is a value of OCS port configuration. When OCS port is created, the default override state configuration is SAI_OCS_PORT_OVERRIDE_STATE_NORMAL. OCS port operational status is updated by OCS driver/SDK, dynamically based on rules (by checking port override state configuration and OCS cross-connect on the port)..

SAI_OCS_PORT_STATUS_BLOCKED is a value of OCS port operational status while SAI_OCS_PORT_OVERRIDE_STATE_NORMAL is a value of OCS port configuration. When OCS port is created, the default override state configuration is SAI_OCS_PORT_OVERRIDE_STATE_NORMAL. OCS port operational status is updated by OCS driver/SDK, dynamically based on rules (by checking port override state configuration and OCS cross-connect on the port)..

got it.

jjin62 · 2025-12-19T04:24:16Z

experimental/saiexperimentalocs.h

+     * @brief Overrides the status imposed by the programmed cross-connects
+     *
+     * @type sai_ocs_port_override_state_t
+     * @flags CREATE_AND_SET


In latest SAI version, for CREATE_AND_SET attributors, it is required to have default value flag:
@default SAI_OCS_PORT_OVERRIDE_STATE_NORMAL
Otherwise parser and compile will be error-out. All CREATE_AND_SET attributes need to add @default

Agreed, updated the code.

jjin62 · 2025-12-19T04:35:35Z

experimental/saiexperimentalocs.h

+    SAI_OCS_PORT_OVERRIDE_STATE_POWERED_OFF,
+
+    /**
+     * @brief Default, state to be determined by presence of cross-connect


how is port state NORMAL is determined connection present or not?

The OCS port override state is a configurable attribute of OCS port. it is defined as CREATE_AND_SET. It can be configured independently, no matter whether cross-connect exists on the port.

understood. But the description seems not accurate.

jjin62 · 2025-12-19T19:02:02Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief Start of attributes
+     */
+    SAI_OCS_CROSS_CONNECT_ATTR_START,


All new acronyms (non-English words), such as OCS need to be add the in the meta dictionary meta/aspell.en.pws. compile will fail without this.

Agreed, updated the code. Thanks

jjin62 · 2025-12-19T19:17:12Z

experimental/saiexperimentalocs.h

+     * List of center frequency values. Use int32 for representation of decimal value with 3 fraction digits
+     *
+     * @type sai_s32_list_t
+     * @flags READ_ONLY


To convert sai_s32_list_t -> decimal, how does the application code (ex. SWSS) know that it should have 3 decimal digits, without hard code to SAI_OCS_CROSS_CONNECT_FACTORY_DATA_ATTR_FREQUENCY_THZ? For decimal -> sai_s32_list_t, how do we validate that the decimal string is 3 precision digits in redis/NBI?

The decimal precision info should be part of the meta data, so the conversion can done generically. One way is to use sai_s32_t and add a new tag @precision n and so the application can retrieve the number of decimal digits from meta data. The proposal to introduce a new type sai_double_t is dropped due to NAN issue.

Same comments for all decimal representation below.

jjin62 · 2025-12-19T22:31:15Z

experimental/saiexperimentalocs.h

+     * @brief End of attributes
+     */
+    SAI_OCS_CROSS_CONNECT_ATTR_END,
+


Add custom rang for vendor extension (see DASH SAI). same for port attributes.

/** 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

Yes, the custom range can be defined for vendor specific extensions, updated the code.

jjin62 · 2025-12-19T22:34:49Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief Unique identifier for a port
+     *
+     * @type sai_u8_list_t


for port name why not using @type char?

In SAI attribute value, char data is defined as: char chardata[32], to support port name with length > 32, sai_u8_list_t is used instead.

32 should be long enough for a port name? char is much easy to use than u8_list.

jjin62 · 2025-12-20T00:31:44Z

experimental/saiexperimentalocs.h

+ *
+ * @brief   This module defines SAI OCS
+ */
+


please add the following to compatible with SAI extension common practice:

* * @warning This module is a SAI experimental module. */

Done, thanks

jjin62 · 2025-12-20T00:53:37Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief A side port
+     *
+     * @type sai_object_id_t


Not sure why you don't use port name (a string) in the port attributes? sai_object_id is auto-generated when SAI object is created. Do you want to enforce creating cross-connect after creating ports? This would need extra logic in SWSS? In any case, I think port name A and B are useful info.

Using SAI object id as type is for reference of OCS ports in OCS cross-connect, it can also enforce that OCS cross-connect must be provisioned between existing OCS ports. OCS ports can be created by swss based device specific on template/profile.

This is certain valid design choice. However, In config DB cross-connect uses port name. so we need logic (SWSS) to find our the port's sai_object_id. As sai_object_id is dynamically generated at run time, so it is different on each restart. This make debug a little hard.

Understood the point, yes, using this proposal, SONiC SWSS can maintain the association between port sai_object_id and port name. Port name is defined as a SAI OCS port attribute. so in ASIC DB port name can be read via port's port sai_object_id. In OCS vendor SAI lib, association of port sai_object_id and port name can also be maintained (during the processing of SAI creating OCS ports.

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

mdemerchant

I think this proposal needs discussion with more OCS vendors to make sure it is not too technology specific. It would be very useful to have a discussion within the OCP OCS sub-project since a large number of vendors are participating.

mdemerchant · 2026-01-05T21:54:06Z

doc/OCS/SAI-Proposal-OCS.md

+* 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.


This requirement restricts OCS technology choices. While most OCS devices available today are limited to A to B connections, not all devices have this limitation. If using bidi optics the ability to connect true any to any port seems like it would be quite valuable, ideally the SAI API should be generalized to support that functionality.

A and B in the YANG model (and SAI) should denote the two endpoints of cross-connect, they do not necessarily need to be on the A or B sides (think of it as a-end and z-end). Agreed that this line in the documentation isn’t accurate, and the YANG model is meant to support cross-connects like ‘1A-2A' or ‘1-5’ too if the hardware supports it. Feasible cross-connects is platform/hardware dependent can be provided as part of YANG model device capabilities.
SAI definition on cross-connect and ports as A point to B point are string type. It is quite flexible to use any port to any port without limitation, like 1A-2A etc. The description is not accurate in the markdown.
Updated the markdown.

mdemerchant · 2026-01-05T21:56:41Z

doc/OCS/SAI-Proposal-OCS.md

+## 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. 


The described behavior seems like it would be performance limiting if you are trying to make bulk changes. You would first have to bulk delete existing cross connects, then bulk create the new desired cross connects which requires two operations. If the behavior is that the switching engine simply replaces the existing connection if you re-use a port then it would be able to do it in one operation.

The logic under SAI from vendor can also implement one bulk operation for cross connects change to OCS module or hardware, instead of deletion and then creation.
In current SAI specification, the supported operations/bulk operations on SAI objects are get, set, create, remove. Different operations are not allowed to be mixed in one bulk API call. Remove is needed to delete SAI related objects from logic view, instead of operations to module or hardware. The description is not accurate in the markdown.
Updated the markdown.

mdemerchant · 2026-01-05T21:59:32Z

doc/OCS/SAI-Proposal-OCS.md

+# 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).


There is no definition given to standardize what data is actually present, only the format of how the data is presented. Is it useful without some standard expectation of what measurements are actually made? What if one vendor decides to measure in O Band and one in C Band. Or one vendor makes a single wavelength measurement and one decides to measure at ten different wavelengths on each path?

The intention here is to provide a model for presenting this data in a generic way that matches the physics of loss measurement, not to enforce completeness of test coverage. Perhaps we can remove the “all/every” cross-connect terminology in this description and replace it with factory beginning-of-life measurements that serve as a baseline reference that users can compare with. The model includes measurement conditions like laser source frequency band or temperature to support various test conditions.
Updated the markdown.

mdemerchant · 2026-01-05T22:11:31Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief First element that the beam hits is powered off, for testing
+     */
+    SAI_OCS_PORT_OVERRIDE_STATE_POWERED_OFF,


I don't think POWERED_OFF is a good choice of state name. It implies specific OCS technology. Wouldn't something more generic like DISABLED be better? It seems the only operational impact of the port being in this state is that you just can't use it to create a cross connection.
What is the actual use case for wanting this state anyway as distinct from the FORCE_BLOCKED state? What this will do optically seems undefined and will vary from device to device.

Agreed that POWERED_OFF state is causing more ambiguity in implementation. Considering that this state was meant for optical DVT testing, we can remove it from the YANG model. Regarding NORMAL/FORCE_BLOCKED vs ENABLED/DISABLED, the NORMAL/FORCE_BLOCKED follows the actual optical behavior more explicitly. For example, it is fair to assume a user considers NORMAL as the default state but in ENABLED/DISABLED it is less clear what the default would be and whether this is a logic default state of a port or actual optical blocking state. POWERED_OFF can be removed but keeping the NORMAL/FORCE_BLOCKED states.
POWERED_OFF can be removed from SAI definition header file. If in the future any new technical solution, like pluggable transceiver with laser, then, new enum values for different operations can be added.
Updated the definition of this header file.

mdemerchant · 2026-01-05T22:16:11Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief Insertion loss is within 0.5dB of target
+     */
+    SAI_OCS_PORT_STATUS_TUNED,


Defining this as loss within 0.5dB of target seems like a strange definition and potentially complex to implement for vendors. Why not just define it as when the device has finished switching? For devices that don't have on-going control loops this is simple and for devices that do have on-going control loops they can implement their own threshold of when it's close enough to guarantee their optical performance specs.

Agreed that we can change the description. This 0.5dB was meant as general guidance on what finished switching.
Updated the description of this header file.

mdemerchant · 2026-01-05T22:21:46Z

experimental/saiexperimentalocs.h

+    /**
+     * @brief If there is a hardware failure
+     */
+    SAI_OCS_PORT_STATUS_FAILED


Is this state intended only to represent a permanent HW failure or simply some kind of failure to set up the last requested connection for this port? What about failure mechanisms where a particular cross connect path connect be achieved but other paths using the port still work fine? The object definition ties failures to ports but not all failure mechanisms are port related, depending on the OCS technology.

I think representing failures in a technology agnostic way needs something considerably more sophisticated in order to convey useful information to the upper layer SW.

This is not a configuration or permanent failure flag. It is meant as a status in the port tuning state machine, for example, when software fails to apply a beam steering state to the DACs due to some communication issue. It is up to the vendor to determine what constitutes a failure in port tuning. Note that the “failed” status is not an all-inclusive status but only used at times that the software knows of a certain failure in tuning.
Permanent failure assignments (for either individual ports or cross-connects) are not modeled in the YANG model currently, those could instead be tracked in an off-box database that control plane has access to.
Updated the description of this header file.

mdemerchant · 2026-01-05T22:27:31Z

experimental/saiexperimentalocs.h

+     * @type sai_u8_list_t
+     * @flags READ_ONLY
+     */
+    SAI_OCS_PORT_ATTR_PHYSICAL_MAPPING,


Need to add something to the markdown file or comments here documenting what this attribute actually is. It doesn't seem to be in the port creation example in the markdown file either.

This is the “internal port” mapping to faceplate port.
Updated the description of this header file.

mdemerchant · 2026-01-05T22:41:31Z

experimental/saiexperimentalocs.h

+ * @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


Are there examples of comparable data structures used for other types of switches in SAI? Maybe I'm misunderstanding the proposed flow but it seems like the SAI implementation wouldn't actually do anything with this data, not even read it from hardware. Some higher level platform specific SW would have to read it from device storage and parse it, then pass it into SAI to create all the objects at initialization. Then later higher level management SW can get the data via those SAI objects. I can see it makes that second access device independent but it just seems kind of an odd implementation. It seems very different from how general device inventory information is handled.

Agree that factory data is read-only. Similar as other devices, ASIC specific data can be queried via SAI interface. If some OCS devices do not support it, SAI definition is there and it is optional. As SAI definition rule, it requires that create, remove, set, get APIs need be defined there, even APIs are not used. Otherwise, the compiling will fail. To ensure that the upper applications are not allowed to create/set/remove the read-only data, vendors can implement these APIs with directly returning ERROR or NOT_IMPLEMENTED.

mdemerchant · 2026-01-05T22:44:26Z

experimental/saiexperimentalocs.h

+/**
+ * @brief OCS methods table retrieved with sai_api_query()
+ */
+typedef struct _sai_ocs_api_t


I understand that SAI has singular and bulk operations because historically it started with singular and added bulk later. But if the OCS is a greenfield application is it necessary/useful to include the singular operations?

Based on current understanding, SAI definition rule requires both singular and bulk APIs to be there, even APIs are not used, like other existing SAI saifdb.h or saiport.h. Otherwise, the compile will fail (e.g. in SONiC sairedis build). So, SAI definition need have both singular and bulk APIs, though current implement only uses bulk API. Vendors can implement bulk API for functions and implement singular API with returning ERROR or NOT_IMPLEMENTED.

… PORT override state configuration Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

swapnaNann · 2026-01-20T03:07:57Z

experimental/saiexperimentalocs.h

+    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;


For bulk operations, what execution modes are supported for OCS? Example shows STOP_ON_ERROR. Will additional modes such as IGNORE_ON_ERROR, ROLLBACK_ON_ERROR or ATOMIC be supported when setting up cross-connects?

Two error modes (STOP_ON_ERROR and IGNORE_ERROR) are defined:
`typedef enum _sai_bulk_op_error_mode_t
{
/**
* @brief Bulk operation error handling mode where operation stops on the first failed creation
*
* Rest of objects will use SAI_STATUS_NON_EXECUTED return status value.
*/
SAI_BULK_OP_ERROR_MODE_STOP_ON_ERROR,

/** * @brief Bulk operation error handling mode where operation ignores the failures and continues to create other objects */ SAI_BULK_OP_ERROR_MODE_IGNORE_ERROR,

} sai_bulk_op_error_mode_t;`

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

wni0812 closed this Dec 9, 2025

wni0812 force-pushed the master branch from 8cc2302 to 58d95ce Compare December 9, 2025 09:12

add SAI definitions for optical circuit switch

055c628

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

wni0812 reopened this Dec 9, 2025

tjchadaga added the reviewed PR is discussed in SAI Meeting label Dec 12, 2025

jjin62 reviewed Dec 20, 2025

View reviewed changes

wni0812 added 3 commits December 20, 2025 15:56

Add SAI definitions for optical circuit switch

30c4b4f

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

Add SAI definitions for optical circuit switch

f2cabe0

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

Add SAI definitions for optical circuit switch

035c020

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

mdemerchant reviewed Jan 5, 2026

View reviewed changes

Add attr custom range for CROSS_CONNECT; define default value for ocs…

b9db060

… PORT override state configuration Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

swapnaNann reviewed Jan 20, 2026

View reviewed changes

Update OCS SAI definitions and markdown document based on comments

b546a2b

Signed-off-by: Nathan Ni <nathan.ni@coherent.com>

add SAI definitions for optical circuit switch #2229

Are you sure you want to change the base?

add SAI definitions for optical circuit switch #2229

Conversation

wni0812 commented Dec 5, 2025

Uh oh!

jjin62 commented Dec 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wni0812 Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdemerchant left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

wni0812 Jan 8, 2026 •

edited

Loading

swapnaNann Jan 20, 2026 •

edited

Loading