add SAI definitions for optical circuit switch

[wni0812]

Add API definitions for Optical Circuit Switch, mainly including:

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

[jjin62]

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]

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,

[jjin62]

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

[jjin62]

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

[jjin62]

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

[jjin62]

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.

[jjin62]

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]

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

[jjin62]

for port name why not using @type char?

[jjin62]

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

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

[jjin62]

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.