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 <[email protected]>

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 <[email protected]>

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.

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.

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?

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.

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.

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.

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.

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.

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?

… PORT override state configuration Signed-off-by: Nathan Ni <[email protected]>

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 <[email protected]>

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 <[email protected]>

Add SAI definitions for optical circuit switch

f2cabe0

Signed-off-by: Nathan Ni <[email protected]>

Add SAI definitions for optical circuit switch

035c020

Signed-off-by: Nathan Ni <[email protected]>

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 <[email protected]>

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!

Reviewers

wni0812 Jan 8, 2026 •

edited

Loading