diff --git a/doc/mgmt/YANG_Action_Support_HLD.md b/doc/mgmt/YANG_Action_Support_HLD.md new file mode 100644 index 00000000000..54c7515f675 --- /dev/null +++ b/doc/mgmt/YANG_Action_Support_HLD.md @@ -0,0 +1,385 @@ +# YANG 1.1 Action Support in SONiC Management Framework + +## High Level Design Document + +#### Rev 0.1 + +## Table of Contents + +- [Revision](#revision) +- [About this Manual](#about-this-manual) +- [Scope](#scope) +- [Definition/Abbreviation](#definitionabbreviation) +- [1 Feature Overview](#1-feature-overview) + - [1.1 RPC vs Action](#11-rpc-vs-action) + - [1.2 Design Overview](#12-design-overview) +- [2 Design](#2-design) + - [2.1 Request Flow](#21-request-flow) + - [2.2 YANG Model Changes](#22-yang-model-changes) + - [2.3 Annotation and Callpoint Registration](#23-annotation-and-callpoint-registration) + - [2.4 Callback Function Types](#24-callback-function-types) + - [2.5 REST Framework Changes](#25-rest-framework-changes) + - [2.6 TransLib Changes](#26-translib-changes) + - [2.7 OpenAPI Generator Changes](#27-openapi-generator-changes) + - [2.8 Go Handler Template Changes](#28-go-handler-template-changes) + - [2.9 Sonic YANG Generator Changes](#29-sonic-yang-generator-changes) + - [2.10 CLI Generator Changes](#210-cli-generator-changes) +- [3 What is NOT Changed](#3-what-is-not-changed) +- [4 Notes](#4-notes) + +## Revision + +| Rev | Date | Author | Change Description | +|:---:|:----------:|:----------:|:-------------------| +| 0.1 | 2026-04-23 | Jichen Dou | Initial version | + +## About this Manual + +This document describes the design for supporting YANG 1.1 `action` statements (RFC 7950 §7.15) with correct RESTCONF invocation (RFC 8040 §3.6) in the SONiC Management Framework. Changes span YANG models, translib, the REST server, OpenAPI/code generators, and the CLI generator. + +## Scope + +This document covers the end-to-end design for introducing `action` support: how actions differ from RPCs at the YANG and RESTCONF layers, the new `ActionCallpoint` type and its registration, and all framework components that required modification. + +## Definition/Abbreviation + +| Term | Description | +|------|-------------| +| HLD | High Level Design | +| RPC | Remote Procedure Call (YANG top-level, RFC 7950 §7.14) | +| Action | YANG 1.1 operation defined inside a data node (RFC 7950 §7.15) | +| RESTCONF | REST-like protocol for YANG-modeled data (RFC 8040) | +| translib | SONiC Management Framework translation library | +| OCM | Optical Channel Monitor — an OTN network element that measures per-channel optical power across a wavelength spectrum. Used in this document as the concrete example of a list-scoped action. | + +--- + +## 1 Feature Overview + +### 1.1 RPC vs Action + +YANG 1.1 (RFC 7950) introduces the `action` statement as a way to define operations that are *scoped to a specific data instance* rather than to the module as a whole. The table below summarises the key differences: + +| Aspect | RPC (RFC 7950 §7.14) | Action (RFC 7950 §7.15) | +|--------|----------------------|------------------------| +| Defined at | Module top level | Inside a `container` or `list` node | +| RESTCONF path | `POST /restconf/operations/` | `POST /restconf/data//` | +| Instance context | None — global scope | The parent list/container instance (keys in URI) | +| Annotation extension | `sonic-ext:rpc-callback` | `sonic-ext:action-callback` | +| Go callback type | `RpcCallpoint` (2 params) | `ActionCallpoint` (3 params, includes `vars`) | + +### 1.2 Design Overview + +The OCM raw-data retrieval use case illustrates the motivation: the existing top-level `get-ocm-raw` RPC had no way to identify *which* channel-monitor instance to query without embedding the name in the input payload. Converting it to an `action` defined inside the `channel-monitor` list lets the instance key come directly from the URI, keeping the payload minimal. + +**YANG definition (new module `sonic-oc-action-ext`):** + +```yang +augment "/oc-chan-monitor:channel-monitors/oc-chan-monitor:channel-monitor" { + action get-ocm-raw { + output { + leaf length { type uint32; } + leaf data { type binary; } + uses action-response-status; + } + } +} +``` + +**RESTCONF invocation:** +``` +POST /restconf/data/openconfig-channel-monitor:channel-monitors/channel-monitor=OCM0-0/sonic-oc-act-ext:get-ocm-raw +{"sonic-oc-act-ext:input": {}} +``` + +The channel-monitor key `OCM0-0` is part of the URI, not the payload. + +--- + +## 2 Design + +### 2.1 Request Flow + +``` +Client POST /restconf/data// + | + v +[1] Generated Go handler (controllers-api.j2) + rc.IsAction = true + | + v +[2] server.Process(w, r) + | + v +[3] parseMethod() → isOperationsRequest() + detects rc.IsAction == true → args.method = "ACTION" + | + v +[4] trimRestconfPrefix() strips "/restconf/data" + translib path: /openconfig-channel-monitor:channel-monitors/channel-monitor=OCM0-0/sonic-oc-act-ext:get-ocm-raw + | + v +[5] invokeTranslib() case "ACTION" → translib.Action(req) + | + v +[6] CommonApp.processAction() + transformer.CallRpcMethod(path, pathInfo.Vars, body, dbs) + registered callback act_get_ocm_raw_cb + | + v +[7] 200 OK with output JSON (or 204 No Content if action has no output) +``` + +### 2.2 YANG Model Changes + +**`src/sonic-mgmt-common`** + +| File | Change | +|------|--------| +| `models/yang/sonic-oc-action-ext.yang` | **New file.** YANG 1.1 module hosting OTN actions via `augment`. Contains the `get-ocm-raw` action inside `channel-monitor`, plus the shared `action-status` typedef and `action-response-status` grouping. | +| `models/yang/openconfig-channel-monitor.yang` | Upgraded to `yang-version "1.1"`. Removed top-level `get-ocm-raw` RPC (now replaced by the action). | +| `models/yang/annotations/sonic-extensions.yang` | Added `action-callback` extension (see §2.3). | +| `models/yang/annotations/openconfig-channel-monitor-annot.yang` | Upgraded to `yang-version "1.1"`. Replaced RPC deviation with action deviation using `sonic-ext:action-callback`. | +| `config/transformer/models_list` | Added `sonic-oc-action-ext.yang`. | + +Any YANG module or annotation file that references an `action` node **must** declare `yang-version "1.1"` — this is a hard requirement of the YANG specification. + +### 2.3 Annotation and Callpoint Registration + +A new YANG extension `action-callback` is added to `sonic-extensions.yang`, mirroring the existing `rpc-callback`: + +```yang +// sonic-extensions.yang + +extension rpc-callback { + argument "callback"; + description "RPC callback to be invoked for action"; +} + +extension action-callback { + argument "callback"; + description "Action callback to be invoked for action within list or container"; +} +``` + +The annotation file wires a specific action path to its Go callback: + +```yang +// openconfig-channel-monitor-annot.yang + +deviation "/oc-chan-monitor:channel-monitors/oc-chan-monitor:channel-monitor/sonic-oc-act-ext:get-ocm-raw" { + deviate add { + sonic-ext:action-callback "act_get_ocm_raw_cb"; + } +} +``` + +The callback is registered at init time with the same `XlateFuncBind` call used for RPC callbacks: + +```go +// xfmr_otn_openconfig.go +func init() { + XlateFuncBind("act_get_ocm_raw_cb", act_get_ocm_raw_cb) +} +``` + +### 2.4 Callback Function Types + +`xfmr_interface.go` defines two callpoint signatures: + +```go +// RpcCallpoint — top-level RPC; no URI instance context needed. +type RpcCallpoint func(body []byte, dbs [db.MaxDB]*db.DB) ([]byte, error) + +// ActionCallpoint — YANG 1.1 action (or RPC needing URI path context). +// vars carries list keys extracted from URI predicates, +// e.g. {"name": "OCM0-0"} for channel-monitor=OCM0-0. +type ActionCallpoint func(vars map[string]string, body []byte, dbs [db.MaxDB]*db.DB) ([]byte, error) +``` + +| | `RpcCallpoint` | `ActionCallpoint` | +|---|---|---| +| Signature | `func(body, dbs)` | `func(vars, body, dbs)` | +| `vars` param | None | List keys from URI predicates | +| Use case | Top-level `rpc` | `action` inside list/container | +| YANG annotation | `sonic-ext:rpc-callback` | `sonic-ext:action-callback` | +| RESTCONF path | `POST /restconf/operations/…` | `POST /restconf/data/…` | + +**`CallRpcMethod` auto-dispatch** (`xlate.go`) selects the calling convention by inspecting the registered function's parameter count at runtime — no type tag is required at registration: + +```go +// xlate.go — CallRpcMethod +if fn, ok := XlateFuncs[rpcFunc]; ok && fn.Type().NumIn() == 3 { + // ActionCallpoint: 3 params → (vars, body, dbs) + data, err = XlateFuncCall(rpcFunc, vars, body, dbs) +} else { + // RpcCallpoint: 2 params → (body, dbs) + data, err = XlateFuncCall(rpcFunc, body, dbs) +} +``` + +**Example — RPC callback** (global, no instance context): + +```go +// annotation: sonic-ext:rpc-callback "rpc_showtech_cb" +var rpc_showtech_cb RpcCallpoint = func(body []byte, dbs [db.MaxDB]*db.DB) ([]byte, error) { + // body is the JSON input payload; no instance key needed + ... +} +``` + +**Example — Action callback** (needs to know which instance to act on): + +```go +// annotation: sonic-ext:action-callback "act_get_ocm_raw_cb" +var act_get_ocm_raw_cb ActionCallpoint = func(vars map[string]string, body []byte, dbs [db.MaxDB]*db.DB) ([]byte, error) { + port := vars["name"] // channel-monitor list key from the URI + if port == "" { + return nil, tlerr.New("missing channel-monitor name in URI") + } + // use port to address the correct OCM instance + ... +} +``` + +### 2.5 REST Framework Changes + +**`src/sonic-mgmt-framework`** + +#### `rest/server/context.go` + +`RequestContext` gains an `IsAction` boolean flag: + +```go +// IsAction indicates this is a YANG 1.1 action request (RFC 7950 Section 7.15). +// Actions use POST on data paths rather than the /restconf/operations/ prefix used by RPCs. +IsAction bool +``` + +#### `rest/server/handler.go` + +`isOperationsRequest()` now recognises action requests in addition to the `/restconf/operations/` prefix check: + +```go +func isOperationsRequest(r *http.Request) bool { + k := strings.Index(r.URL.Path, restconfOperPathPrefix) + if k >= 0 { + return true // classic RPC path prefix + } + cv := r.Context().Value(requestContextKey) + if cv != nil { + if rc, ok := cv.(*RequestContext); ok && rc.IsAction { + return true // action flag set by generated handler + } + } + return false +} +``` + +When `isOperationsRequest()` returns `true` for a `POST`, `parseMethod` sets `args.method = "ACTION"`. The `invokeTranslib` switch then calls `translib.Action()` and returns HTTP 200 with the response payload: + +```go +case "ACTION": + req := translib.ActionRequest{ + Path: args.path, + Payload: args.data, + ClientVersion: args.version, + } + res, err1 := translib.Action(req) + if err1 == nil { + status = 200 + content = res.Payload + } else { + err = err1 + } +``` + +### 2.6 TransLib Changes + +**`src/sonic-mgmt-common`** + +#### `translib/translib.go` + +`ActionRequest` / `ActionResponse` structs define the action invocation interface (analogous to the existing `RpcRequest` / `RpcResponse`). `Action()` calls `translateAction()` then `processAction()`. + +#### `translib/common_app.go` + +`processAction()` passes `pathInfo.Vars` (the URI list-key map) to `CallRpcMethod` so the callback receives instance context: + +```go +func (app *CommonApp) processAction(dbs [db.MaxDB]*db.DB) (ActionResponse, error) { + var resp ActionResponse + var err error + + resp.Payload, err = transformer.CallRpcMethod( + app.pathInfo.Path, app.pathInfo.Vars, app.body, dbs) + + return resp, err +} +``` + +The `pathInfo.Vars` field is populated during path parsing and contains the decoded list predicates, e.g. `{"name": "OCM0-0"}` for `channel-monitor=OCM0-0`. + +### 2.7 OpenAPI Generator Changes + +**`src/sonic-mgmt-framework/tools/pyang/pyang_plugins/openapi.py`** + +- `walk_child()` routes `action` keyword to a new `handle_action()` instead of `handle_rpc()`. +- `handle_action()` generates the path under `/restconf/data` (not `/restconf/operations`), sets `x-action: true` on the generated OpenAPI entry, generates path parameters for all parent list keys (e.g. `{name}`), and attaches the output schema to the `200 OK` response. +- `build_payload()` skips `action` nodes to avoid duplicating them as data fields. +- `verb_responses["action"]` is defined as `{200: with content, 204, 404, 403}`. + +### 2.8 Go Handler Template Changes + +**`src/sonic-mgmt-framework/tools/codegen/go-server/templates-yang/controllers-api.j2`** + +For routes marked `x-action`, the template reads the output schema from `responses["200"]` (not `responses["204"]` as for RPCs) and sets `rc.IsAction = true` so the REST server routes the request as an action: + +```go +// Generated handler for an x-action route +func ActionGetOcmRaw(w http.ResponseWriter, r *http.Request) { + rc, r := server.GetContext(r) + rc.IsAction = true + server.Process(w, r) +} +``` + +The `rc.IsAction = true` line is the only generated difference from a plain data-POST handler. + +### 2.9 Sonic YANG Generator Changes + +**`platform/otn-kvm/sonic-yanggen/sonic_yanggen.py`** + +- Parses `sonic-ext:action-callback` deviations alongside `rpc-callback`. +- `_find_actions_in_subtree()`: recursive libyang traversal to locate `ACTION` nodes. +- `gen_container()`: emits list-level actions **inside the `_LIST` container** using `_find_actions_in_subtree()`. +- Sets `yang-version "1.1"` in the generated Sonic YANG when actions are present. +- `gen_actions()` + `_walk_actions()`: emits remaining container-level actions. +- `_emit_rpc_or_action(node, keyword)`: unified emitter for both `rpc` and `action`. + +### 2.10 CLI Generator Changes + +**`src/sonic-utilities/sonic_cli_gen/yang_parser.py`** + +- Added `on_action()`: parses an `action` node into `{name, description, input, output, has_input, has_output}`. +- Added `get_actions()`: retrieves `action` elements from a YANG entity and maps through `on_action()`. Called from both `on_table_container()` (container-level) and `on_object_entity()` (list-level). +- `has_actions` flag replaced with `has_rpc_or_action` (checks both top-level `rpcs` and per-table/object `actions`). + +**`src/sonic-utilities/templates/sonic-cli-gen/config.py.j2`** + +- Replaced `gen_cfg_rpc` / `gen_cfg_action` macros with a unified `gen_cfg_operation` + `gen_cfg_run` pair. RPCs and actions share a single `run` subgroup per table/object. +- `gen_cfg_operation` behaviour depends on the presence of list keys: non-empty keys (list-level action) turn list keys into positional arguments and input fields into `--options`; empty keys (RPC or container-level action) turn all input into `--options`. + +--- + +## 3 What is NOT Changed + +- **RPC handling** — existing top-level RPCs continue to use `/restconf/operations/`. The RPC path in the REST server and translib is untouched. +- **transformer core** — `CallRpcMethod()` already accepted a `vars` argument; only `common_app.go` was updated to forward `pathInfo.Vars` into it. + +--- + +## 4 Notes + +- Any YANG module or annotation file referencing an `action` node must declare `yang-version "1.1"`. +- Per RFC 8040 §4.4.2: if an action has no `output` section the server MUST return `204 No Content`; if output is present the server returns `200 OK` with the payload. diff --git a/doc/ocs/images/control-flow.png b/doc/ocs/images/control-flow.png new file mode 100644 index 00000000000..4207dc6376a Binary files /dev/null and b/doc/ocs/images/control-flow.png differ diff --git a/doc/ocs/images/linecard-syncd.png b/doc/ocs/images/linecard-syncd.png new file mode 100644 index 00000000000..764140a15f4 Binary files /dev/null and b/doc/ocs/images/linecard-syncd.png differ diff --git a/doc/ocs/images/object-orchagent.png b/doc/ocs/images/object-orchagent.png new file mode 100644 index 00000000000..59f8ec5330f Binary files /dev/null and b/doc/ocs/images/object-orchagent.png differ diff --git a/doc/ocs/images/ocs-ai.png b/doc/ocs/images/ocs-ai.png new file mode 100644 index 00000000000..8520273b31b Binary files /dev/null and b/doc/ocs/images/ocs-ai.png differ diff --git a/doc/ocs/images/ocs-dci.png b/doc/ocs/images/ocs-dci.png new file mode 100644 index 00000000000..1df314333fa Binary files /dev/null and b/doc/ocs/images/ocs-dci.png differ diff --git a/doc/ocs/images/ocs-deployment.png b/doc/ocs/images/ocs-deployment.png new file mode 100644 index 00000000000..fec32222fea Binary files /dev/null and b/doc/ocs/images/ocs-deployment.png differ diff --git a/doc/ocs/images/ocs-extensions.png b/doc/ocs/images/ocs-extensions.png new file mode 100644 index 00000000000..10ff8bef6f9 Binary files /dev/null and b/doc/ocs/images/ocs-extensions.png differ diff --git a/doc/ocs/images/ocs-sai-extension.png b/doc/ocs/images/ocs-sai-extension.png new file mode 100644 index 00000000000..8cfba57939a Binary files /dev/null and b/doc/ocs/images/ocs-sai-extension.png differ diff --git a/doc/ocs/images/ocs-syncd.png b/doc/ocs/images/ocs-syncd.png new file mode 100644 index 00000000000..618a3bf6d29 Binary files /dev/null and b/doc/ocs/images/ocs-syncd.png differ diff --git a/doc/ocs/images/openconfig-cli.png b/doc/ocs/images/openconfig-cli.png new file mode 100644 index 00000000000..d681c8b5cf2 Binary files /dev/null and b/doc/ocs/images/openconfig-cli.png differ diff --git a/doc/ocs/images/redis-pluggin-script.png b/doc/ocs/images/redis-pluggin-script.png new file mode 100644 index 00000000000..a3233e16b3c Binary files /dev/null and b/doc/ocs/images/redis-pluggin-script.png differ diff --git a/doc/ocs/sonic-ocs-hld.md b/doc/ocs/sonic-ocs-hld.md new file mode 100644 index 00000000000..78195471740 --- /dev/null +++ b/doc/ocs/sonic-ocs-hld.md @@ -0,0 +1,779 @@ +# SONiC-OCS HLD + +This document comply to [SONiC HLD Template](https://github.com/sonic-net/SONiC/blob/master/doc/hld_template.md). It will be evolved in parallel with the on-going prototyping, an OCS device as kvm virtual machine. + +- Here is the the implementation of [OCS kvm](https://github.com/sonic-molex/sonic-buildimage/tree/ocs). +- The compile and running instruction for OCS kvm is described in the [README.md](https://github.com/sonic-molex/sonic-buildimage/blob/ocs/platform/ocs-kvm/README.md) here. + +## Table of Contents + +- [SONiC-OCS HLD](#sonic-ocs-hld) + - [Table of Contents](#table-of-contents) + - [1 Revision](#1-revision) + - [2 Scope](#2-scope) + - [3 Definitions/Abbreviations](#3-definitionsabbreviations) + - [Table 1: Abbreviations](#table-1-abbreviations) + - [4 Overview](#4-overview) + - [5 Requirements](#5-requirements) + - [5.1 Functional requirements](#51-functional-requirements) + - [5.2 Scaling requirements](#52-scaling-requirements) + - [5.3 Alarm](#53-alarm) + - [5.4 PM Counter](#54-pm-counter) + - [5.5 Telemetry](#55-telemetry) + - [6 Architecture Design](#6-architecture-design) + - [6.1 Design Principles](#61-design-principles) + - [6.2 SONiC Extension Points for OCS Support](#62-sonic-extension-points-for-ocs-support) + - [7 High-Level/Module Design](#7-high-levelmodule-design) + - [7.1 OCS Device Metadata](#71-ocs-device-metadata) + - [7.2 SWSS Extension for OCS Optical Traffic](#72-swss-extension-for-ocs-optical-traffic) + - [7.2.1 SWSS Config Manager](#721-swss-config-manager) + - [7.2.2 SWSS orchagent](#722-swss-orchagent) + - [OrchDaemon for OCS](#orchdaemon-for-ocs) + - [Generic orchagent Class](#generic-orchagent-class) + - [7.3 OCS State and PM Statistics Support](#73-ocs-state-and-pm-statistics-support) + - [7.3.1 SONiC SWSS Redis plug-in script](#731-sonic-swss-redis-plug-in-script) + - [7.3.2 State DB and PM counter update](#732-state-db-and-pm-counter-update) + - [7.3.3 Device specific lua script example](#733-device-specific-lua-script-example) + - [7.4 SyncD Extension](#74-syncd-extension) + - [7.5 PMON](#75-pmon) + - [7.5.1 PMON Base Class](#751-pmon-base-class) + - [7.5.2 Device specific platform config and driver](#752--device-specific-platform-config-and-driver) + - [7.5.3 Linecard Hot-pluggable](#753-linecard-hot-pluggable) + - [7.5.4 Firmware Upgrade](#754-firmware-upgrade) + - [7.6 SONiC host containers](#76-sonic-host-containers) + - [8. SAI API](#8-sai-api) + - [8.1 SAI Experimental Extension Mechanism](#81-sai-experimental-extension-mechanism) + - [8.2 OCS Extension To SAI](#82-ocs-extension-to-sai) + - [9. Configuration and management](#9-configuration-and-management) + - [9.1. Manifest (if the feature is an Application Extension)](#91-manifest-if-the-feature-is-an-application-extension) + - [9.2. CLI/YANG model Enhancements](#92-cliyang-model-enhancements) + - [9.2.1 OCS SONiC Yang Model](#921-ocs-sonic-yang-model) + - [9.2.2 CLI](#922-cli) + - [9.2.3 REST API](#923-rest-api) + - [9.3. Config DB Enhancements](#93-config-db-enhancements) + - [9.4 Reuse Exsiting Features](#94-reuse-exsiting-features) + - [9.4.1 Management and Loopback Interface](#941-management-and-loopback-interface) + - [9.4.2 TACACS+ AAA](#942-tacacs-aaa) + - [9.4.3 Syslog](#943-syslog) + - [9.4.4 NTP](#944-ntp) + - [9.4.5 Telemetry and gNMI](#945-telemetry-and-gnmi) + - [9.4.6 SONiC Management Framework](#946-sonic-management-framework) + - [9.4.7 SONiC upgrade](#947-sonic-upgrade) + - [10. Warmboot and Fastboot Design Impact](#10-warmboot-and-fastboot-design-impact) + - [11. Memory Consumption](#11-memory-consumption) + - [12. Restrictions/Limitations](#12-restrictionslimitations) + - [13. Testing Requirements/Design (**TBD**)](#13-testing-requirementsdesign--tbd) + - [13.1. Unit Test cases](#131-unit-test-cases) + - [13.2. System Test cases](#132-system-test-cases) + - [14. Open/Action items - if any](#14-openaction-items---if-any) + +## 1 Revision + +| Rev | Date | Author | Change Description | +| :---: | :--------: | :-----------------: | :---------------------------------------- | +| 0.1 | 06/30/2025 | Jimmy Jin, Lu Mao | Initial version, Some portion is derived from [sonic-otn-wp](https://github.com/sonic-otn/SONiC-OTN)| + +## 2 Scope + +This document describes the architecture and high level design for extending SONiC to support Optical Circuit Switch (OCS) device. + +## 3 Definitions/Abbreviations + +### Table 1: Abbreviations + +| | | +| ----- | --------------------------------------------------- | +|OCS | Optical circuit switch | +|NOS | Network operating system | +|SA | Service affect | +|NSA | Non service affect | +|PM | Performance management | +|OTAI | Optical transport abstraction interface | +|DCI | Inter data center connection | + +## 4 Overview + +Optical circuit switch (OCS), also known as an all-optical switch, is a technology that establishes optical connections between fibers, allowing data transmission without the need for electrical switching and conversion (OEO). Here are some advantages of OCS comparing to the electrical switches: + +- Improved Performance: +OCS can offer lower latency and higher throughput. This is because OCS operates at the physical layer, directly switching light signals rather than processing electrical packets. +- Scalability: +OCS can be used to create large-scale, reconfigurable networks without the limitations of traditional electrical switches. +- Reduced Energy Consumption: +OCS consumes less power than EPS, leading to significant energy savings in large data centers. +- Reconfigurable Topologies: +OCS enables the creation of dynamic, logical topologies that can be adapted to changing communication patterns. +- Failure Resilience: +OCS can provide alternative paths for data transmission, improving network resilience. + +As such, OCS can be used a various network use cases. One of the main application of OCS is to connect large number of AI computing nodes to form a AI super computing cluster, as shown in the following diagram [(source):](https://arxiv.org/pdf/2304.01433) + + OCS for AI + +Another OCS use case is to provide low power consumption and low latency inter data center connections (DCI), shown in the following diagram:[(source):](https://www.microsoft.com/en-us/research/publication/beyond-the-mega-data-center-networking-multi-data-center-regions/) + + OCS for DCI + +This document provides high level design of extending SONiC to support OCS device, including yang model, SAI APIs, orchestration agent, syncd, Config and APP DB Schemas and other SONiC changes required to bring up SONiC image on an OCS device. + +## 5 Requirements + +### 5.1 Functional requirements + +At a high level the following should be supported: + +- Bring up SONiC image for DEVICE_METADATA type - `SonicOCS` +- Bring up swss/syncd containers for switch_type - `ocs` +- Able to manage OCS device configured via REST, gRPC client and CLI +- Device Management functions including: + - Configuration - system, OCS port and OCS cross-connect. + - State report - system, OCS port and OCS cross-connect. + - Operations: restart (warm, cold and power-on), SW/FW upgrade + - Telemetry: Data streaming for time sensitive state. + - Alarm notification for system faults. + - PM statistics counters for important performance parameters. + +The OCS deployment and device management in a data center for AI application is illustrated in the following diagram: + + OCS Deployment + +### 5.2 Scaling requirements + +Following are the scaling requirements: [*TBD*] + +| Item | Expected Max value | +| ----------------------------- | ----------------------------- | +| Ports | 2x1024 | +| Cross-connect | 1024 | + +### 5.3 Alarm + +Alarms that listed in the following table should be supported:**[TBD]** + +| Alarm name | Severity | +| ----------------------------- |-----------------------------------| +| Port-failed | SA | +| PUS Failed | NAS | + +### 5.4 PM Counter + +Network equipment performance management counters are metrics that monitor and provide insights into the performance of network devices. They help identify potential issues, bottlenecks, and areas for optimization, enabling network administrators to proactively manage and troubleshoot their infrastructure: + +For each PM parameters, the following statistics should be available for users: + +- 96 (32) buckets of 15-minute counters including min, max and average. +- 7 bucket of 24-hour counters with min, max and average. + +PM parameters that listed in the following table should be supported:**[TBD]** + +| PM name | Data Type | +| ----------------------------- |-----------------------------------| +| Temperature | decimal2 | +| PUS Input Current | decimal2 | +| Fan Speed | int32 | + +### 5.5 Telemetry + +OCS should support telemetry features. Both [dial-in](https://github.com/sonic-net/sonic-telemetry/blob/master/doc/grpc_telemetry.md) and [dial-out](https://github.com/sonic-net/sonic-telemetry/blob/master/doc/dialout.md) modes for telemetry should be supported. + +## 6 Architecture Design + +This section describes the overall changes needed for supporting OCS devices. + +### 6.1 Design Principles + +While SONiC is a packet switch NOS, it's modular design and built-in extensibility infrastructure allow developers to add functionality beyond the packet switching domain. + +The following guideline should be followed while developing SONiC based NOS for OCS. + +- Fully utilize SONiC rich extension mechanism to make the change as seamless as possible so that the OCS support becomes a organic part of the SONiC. + +- Complete reuse SONiC generic system features as is, including NBI (REST, CLI, gNMI), telemetry, user management, syslog notification, SW/FW upgrade, chassis/PSU/LED/FAN/temperature management, etc. + +- Changes for OCS support should be modular and relatively isolated from the packet switching logic with non/minimum impact on existing packet switching functions. + +- For major feature gaps, such as PM, alarm and hot pluggable, enhancement design and implement should be in a generic way, not just for OCS. + +- All changes should be compatible to the upstream SONiC code base and ready to be merged. The final goal is that all OCS vendors should be able to pull the official SONiC code and build SONiC OCS images for their devices. + +### 6.2 SONiC Extension Points for OCS Support + +The following diagram shows the main changes and extension points of SONiC to support OCS device: + + OCS Extension + +1. Add OCS SONiC yang (sonic-ocs.yang) and support REST API and CLI. + +2. Redis DB: Add new CONFIG, STATE and APP tables (ocs-port, cross-connect). + +3. Config Manger: Add Config manager for port and connections. + +4. Chassis Drivers: Add user and kernel drivers for Fan, PSU, LED and temperature sensors, FPGA. + +5. SAI: Extend SAI to support OSC using SAI experimental extension mechanism. + +6. SyncD: SyncD driver supporting extended OSC SAI attributes. + +7. Platform and device: Add OCS as a new sonic platform ocs and new OCS device, supporting configurable port counts (16x16, 64x64 and 512x512 etc..). + +8. ONIE: Create ONIE image for installing SONiC image on OCS devices, support secure boot. + +## 7 High-Level/Module Design + +This section describes changes at SONiC module level to support OCS devices. + +### 7.1 OCS Device Metadata + +In DEVICE meta data table, a new type, `SonicOCS`, and new switch_type, `ocs`, are added: + +``` JSON +"DEVICE_METADATA": { + "localhost": { + "type": "SonicOCS", + "switch_type": "ocs", + } +} +``` + +see [code here](https://github.com/sonic-molex/sonic-buildimage/blob/ocs/device/molex/x86_64-ocs-kvm_x86_64-r0/ocs-metadata.json). + +### 7.2 SWSS Extension for OCS Optical Traffic + +Two SONiC build-in containers, swss and syncd, are at the core for providing data path control and monitoring, as shown in the following diagram: + +swss and syncd + +#### 7.2.1 SWSS Config Manager + +In SWSS container, a new config manager daemon, [`ocsmgrd`](https://github.com/sonic-molex/sonic-swss/blob/ocs/cfgmgr/ocsmgrd.cpp), is created to subscribe the changes in OCS tables in config DB. When config change is notified, OCS config manager update the corresponding tables in APP DB. + +[**TBD**] How the failure is handled, if the config change does not pass the business logic validation? SONiC configuration is managed asynchronously, i.e., the config will be accepted and stored in config DB, even the low level/HW processing fails. + +#### 7.2.2 SWSS orchagent + +Orchagent is extended with a [separate folder](https://github.com/sonic-molex/sonic-swss/tree/ocs/orchagent/ocs) to support OCS devices. + +##### OrchDaemon for OCS + +Currently, SONiC support two types of Orch Daemon based on `switchType`, orchDaemon or fabricOrchDaemon. A new type of orchDaemon, OcsOrchDamon is added to support OCS devices. At run time, switchType == `ocs` is use to determine if [ocsOrchDaemon](https://github.com/sonic-molex/sonic-swss/blob/ocs/orchagent/ocs/ocsorchdaemon.cpp) should be created. please see code [code here](https://github.com/sonic-molex/sonic-swss/blob/ocs/orchagent/main.cpp). + +``` c++ + if(switchType == "ocs") + { + create orchDaemon = make_shared; + } + else if (switchType != "fabric") + { + orchDaemon = make_shared(); + } + else + { + orchDaemon = make_shared(); + } +``` + +Creating new type of OrchDamon isolates OCS support from the existing logic, resulting in no impact on existing packet features. + +##### Generic orchagent Class + +A generic superclass, [`objectorch`](https://github.com/sonic-molex/sonic-swss/blob/ocs/orchagent/ocs/objectorch.cpp), is defined to support all operations (CRUD) the Flexcounter DB. + +Instead of hard code all SAI object attributes in a static map table (current SONiC design pattern), the orchagent corresponding to each SAI object can re-use the generic methods in `objectorch` for State and Flexcounter DB access. Shown as in the following diagram, where the SAI attribute to string map are built generically by reading the SAI metadata. + +object-orchagent + +This effectively removed many redundant code and eliminated human error from hard code. + +### 7.3 OCS State and PM Statistics Support + +This section describes how to support OCS state update in STATE DB and PM statistics Counters. + +Current SONiC does not support traditional telecom performance management (PM) historical counters. + +- 96 (32) buckets of 15-minute counters including min, max and average. +- 7 bucket of 24-hour counters with min, max and average. + +(OTN syncd added historical data by modifying the syncd code base. This causes a code base diverge from the upstream code.) + +Also, attributes specified in the state container of sonic-ocs.yang need to be updated continuously, so that NBI (CLI/REST API) can read the OCS status from State DB directly. + +#### 7.3.1 SONiC SWSS Redis plug-in script + +SWSS utilizes Lua scripts for certain operations, particularly within its Producer/Consumer Table framework. These scripts help in atomically writing and reading messages to and from Redis databases. +Examples of Lua scripts within the SWSS can be found in the sonic-swss repository. One notable example is [pfc_restore.](https://github.com/sonic-net/sonic-swss/blob/master/orchagent/pfc_restore.lua), which uses Redis commands to handle PFC (Priority Flow Control) restoration. + +#### 7.3.2 State DB and PM counter update + +It is proposed to use SWSS lua script to support State DB update and PM statistic counters with the following benefits: + +- Use existing counter DB as is. SONiC counter DB is designed for storing raw data from the hardware. Syncd updates the counters specified in the Flex-counter DB. Both State and PM counters can be built form the tables in counter DB +- Use SWSS orchagent existing mechanism to install lua scrips, which are similar to stored procedure in traditional database systems.These scripts are running inside of redis container and can be invoked whenever the counter DB is updated. +- These lua scripts can be device specific, i.e., each device vendor can write customized scripts and include as part of the device data. This provides the maximum flexibility and make status update and PM complete generic. + +The following diagram shows the work flow of redis plug-in script in SONiC. + +Redis script + +- First orchagent install the script as hashed SHA. +- When syncd add the counter attribute, it also add the plug-in SHA. +- When vendor SAI updates the counters, it also send request to redis DB to run the script. + +The main advantage of this approach: + +- No SONiC code need to be written for PM support +- Scripts is plugged in at device level, providing flexibility for each vendor to customize the behavior. + +#### 7.3.3 Device specific lua script example + +Here is the flex-counter DB and counter DB after script is installed for update the state DB. [example](https://github.com/sonic-molex/sonic-buildimage/tree/ocs/device/molex/x86_64-ocs-kvm_x86_64-r0) + +Note currently, some vendor specific lua scripts are put into in the SWSS [orchagent](https://github.com/sonic-net/sonic-swss/blob/master/orchagent), which is not ideal. They could be included as part of device config, as above example. + +### 7.4 SyncD Extension + +In the syncd container, SONiC starts the syncd service at startup, which loads the SAI component (driver) present in the system. This component is provided by various vendors, who implement the SAI interfaces based on their hardware platforms, allowing SONiC to use a unified upper-layer logic to control various hardware platforms. Syncd is responsible for communicating with the Redis database, loading SAI implementation, and interacting with it to handle ASIC initialization, configuration, status reporting, and so on. + +For OCS device, Syncd behaviors exactly same. But instead of managing the ASIC, each vendor will implement SAI OCS extension APIs to control and monitor the OCS HW, MEMS or LCoS mirror array. Notification handlers are also registered to handle events from the HW. OCS can be supported by extending the logic to processing new SAI APIs for OCS objects. +Instead of modified code in existing file [FlexCounter](https://github.com/sonic-net/sonic-sairedis/blob/master/syncd/FlexCounter.cpp), a new file `FlexCounterExt.cpp` is created for OCS support to isolate the code maintenance. See [code here](https://github.com/sonic-molex/sonic-sairedis/blob/ocs/syncd/FlexCounterExt.cpp). + +Since OSC support is added at [end of logic in existing flexcounter logic](https://github.com/sonic-molex/sonic-sairedis/commit/1694bc7a251d172f24bedc40a22e1390f99c602d#diff-6b568ec42486b69121856646d4bc61b4a9083d12227a5420a1b3b1da93ef24fb), the new OCS code will not have any impact on existing switch functionalities. + +Redis script + +### 7.5 PMON + +SONiC pmon (platform monitor) manages generic hardware, which is independent from the functionality of the device providing. pmon infrastructure is implemented in two repositories, [sonic-platform-common](https://github.com/sonic-net/sonic-platform-common) and [sonic-platform-daemon](https://github.com/sonic-net/sonic-platform-daemons) described in [this doc](https://github.com/sonic-net/SONiC/blob/master/doc/platform_api/new_platform_api.md). And Vendor platform module resides under ``sonic-buildimage/platform`` folder for each device type. + +#### 7.5.1 PMON Base Class + +Python classes are implemented to model the generic hardware structure and operations on the hardware. Here is the example of a typical device structure in python classes: + +- Chassis + - System EEPROM info + - Reboot cause + - Environment sensors + - Front panel/status LEDs + - Power supply unit[0 .. p-1] + - Fan[0 .. f-1] + - Module[0 .. m-1] (Line card, supervisor card, etc.) + - Environment sensors + - Front-panel/status LEDs + - SFP cage[0 .. s-1] + - Components[0 .. n-1] (CPLD, FPGA, MCU, ASIC etc.) + - name + - description + - firmware + +#### 7.5.2 Device specific platform config and driver + +The JSON file [code here](https://github.com/sonic-molex/sonic-buildimage/blob/ocs/device/molex/x86_64-ocs-kvm_x86_64-r0/platform.json) is to define the OCS device HW hierarchy described above. This config file is device specific for a particular OCS device. + +An example of driver of PMON is [implemented here](https://github.com/sonic-molex/sonic-buildimage/tree/ocs/platform/ocs-kvm/sonic-platform-modules-ocs-kvm/ocs-v). + +#### 7.5.3 Linecard Hot-pluggable + +Currently, SONiC support two chassis types: + +- Pizza box without pluggable supervisor/control card and line cards +- Multi-Asic, in which each line cards running an independent SONiC + +An OCS device may not fit either of the above architecture. A typical OCS device contains multiple driver cards which controls the OCS port array angles. When a driver card is removed or inserted, orchagent should be notified so that all affected ports and connections should not be removed from the syncd monitoring thread. The port and connection status also should be updated in the state DB. + +Line Card syncd + +As shown in the above diagram, a new line card monitoring daemon is added to PMON container for line card operation status monitoring. + +Line card un-plug/failed: + +- PMON detect a line card is removed. It change status of a line card from online to `empty/fault`. The linecardsyncd should update all the ports that is affected by this line card by changing the port admin state (port-config-override-state) in APP DB to `powered-off (offline??)`. +- Orchagent (ocsportorch) will be triggered to remove responding SAI port objects and associated flexcounter entries. +- Syncd will stop monitoring the removed resource (port and connections). Ports and connection in the State DB should be updated as well. + +Line card insert: + +- PMON detects a line card is back to online (LC communication is OK). It changes status of a line card changed to online. line card daemon should update APP DB for all the ports that is affected by this line card by restoring the port admin state from Config DB to State DB. +- If the port admin state is `normal`, Orchagent (ocsportorch) will be triggered to create responding SAI port objects and associated flexcounter entries. +- Syncd will start monitoring the resource (port and connections). Ports and connection in the State DB should be updated as well. + +#### 7.5.4 Firmware Upgrade + +SONiC provide a generic mechanism to install/upgrade firmware, [fwutil.md](https://github.com/sonic-net/SONiC/blob/master/doc/fwutil/fwutil.md). + +OCS vendor need to implement the python component APIs defined in the base class [`component_base.py`](https://github.com/sonic-net/sonic-platform-common/blob/master/sonic_platform_base/component_base.py): + +### 7.6 SONiC host containers + +The following containers shall be enabled for SONiC and part of the image. Switch specific containers shall be disabled for the image built for the OCS devices. Need to change the SONiC build [rule/config](https://github.com/sonic-net/sonic-buildimage/blob/master/rules/config) accordingly. + +| Container/Feature Name | Is Enabled? | +| ---------------------- | ----------- | +| SNMP | Yes | +| Telemetry | Yes | +| LLDP | No | +| Syncd | Yes | +| Swss | Yes | +| Database | Yes | +| BGP | Yes | +| Teamd | No | +| Pmon | Yes | +| Nat | No | +| Sflow | No | +| DHCP Relay | No | +| Radv | No | +| Macsec | No | +| Resttapi | Yes | +| gNMI | Yes | + +## 8. SAI API + +This section covers the changes made or new API added in SAI API for implementing this feature. + +### 8.1 SAI Experimental Extension Mechanism + +While SAI API supporting core packet switching features, it also has some build-in extension mechanisms that allows developers to add new object and APIs. Here is the [SAI experimental extension design](https://github.com/opencomputeproject/SAI/blob/master/doc/SAI-Extensions.md). SAI extension mechanism provides: + +- Add new attributes, ex., add new attributes in saiswitchextensions.h. +- Add new API types in saiextension.h. +- Add new object types in saitypesextensions.h. +- Can not modify existing SAI. +- Add new attributes, ex., add new attributes in for the new APIs. + +[DASH](https://github.com/sonic-net/DASH) project recently added new API and objects into SAI experimental extension to support DASH hosts. [Referred here](https://github.com/opencomputeproject/SAI/tree/master/experimental). + +### 8.2 OCS Extension To SAI + +Before OCS SAI object/APIs becomes part of the mainstream SAI (SAI/inc), it is preferred to add OCS SAI object and API as the SAI experimental folder (SAI/experimental), to isolate churns between OCS SAI and main SAI. + + SAI Extension + +1. First add new OCS port and connection API types in `saiextension.h`. Note that OCS is used as part of the prefix for OCS devices. + +```#ifndef __SAIEXTENSIONS_H_ +#define __SAIEXTENSIONS_H_ + +#include + +/* OCS extension */ +#include "saiexperimentalocscrossconnect.h" +#include "saiexperimentalocsport.h" + +typedef enum _sai_api_extensions_t +{ + SAI_API_EXTENSIONS_RANGE_START = SAI_API_MAX, + + .... + + 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_ */ +``` + +2. Then add new SAI object types in `saitypesextensions.h` + +``` +#ifndef __SAITYPESEXTENSIONS_H_ +#define __SAITYPESEXTENSIONS_H_ + +#include + +/** + * @brief SAI object type extensions + * + * @flags free + */ +typedef enum _sai_object_type_extensions_t +{ + SAI_OBJECT_TYPE_EXTENSIONS_RANGE_START = SAI_OBJECT_TYPE_EXTENSIONS_RANGE_BASE, + + .... + + 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; + +``` + +3. The new attributes for OCS SAI API are defined in two new separate head files for modulization. + + `saiexperimentalcsport.h` ([code](https://github.com/sonic-molex/SAI/blob/ocs/experimental/saiexperimentalocsport.h)) and `saiexperimentalocscrossconnect.h` ([code](https://github.com/sonic-molex/SAI/blob/ocs/experimental/saiexperimentalocscrossconnect.h)). + +## 9. Configuration and management + +This section have sub-sections for all types of configuration and management related design. Sub-sections for "CLI" and "Config DB" are given below. Sub-sections related to data models (YANG, REST, gNMI, etc.,) is included as well. + +### 9.1. Manifest (if the feature is an Application Extension) + +N/A + +### 9.2. CLI/YANG model Enhancements + +This sub-section covers the addition/deletion/modification of CLI changes and YANG model changes needed for the feature in detail. + +#### 9.2.1 OCS SONiC Yang Model + +The following are the schema changes. The NorthBound APIs shall be defined as sonic-yang in compliance to [yang-guideline](https://github.com/Azure/SONiC/blob/master/doc/mgmt/SONiC_YANG_Model_Guidelines.md). + +The sonic-ocs.yang in tree format is shown as: + +``` +module: sonic-ocs + +--rw sonic-ocs + +--rw OCS_PORT + | +--rw OCS_PORT_LIST* [simplex_port_id] + | +--rw simplex_port_id simplex_port_name + | +--rw label? string + | +--rw config_status? port_config_override_status + +--rw OCS_CROSS_CONNECT + | +--rw OCS_CROSS_CONNECT_LIST* [cross_connect_id] + | +--rw cross_connect_id cross_connect_name + | +--rw a_side? simplex_port_name + | +--rw b_side? simplex_port_name + +--ro OCS_PORT_TABLE + | +--ro OCS_PORT_LIST* [simplex_port_id] + | +--ro simplex_port_id simplex_port_name + | +--ro connector_type? string + | +--ro connector_pin? string + | +--ro target_simplex_port_id? simplex_port_name + | +--ro oper_status? port_oper_status + +--ro OCS_CROSS_CONNECT_TABLE + | +--ro OCS_CROSS_CONNECT_LIST* [cross_connect_id] + | +--ro cross_connect_id cross_connect_name + | +--ro status? cross_connect_status + | +--ro physical_path* string + +--ro OCS_FACTORY_INSERTION_LOSS_TABLE + +--ro OCS_FACTORY_INSERTION_LOSS_LIST* [cross_connect_id frequency_THz temperature_C] + +--ro cross_connect_id cross_connect_name + +--ro temperature_C decimal64 + +--ro frequency_THz decimal64 + +--ro loss_dB? decimal64 + +--ro accuracy_dB? decimal64 +``` + +Reference Yang model for OCS is [here](https://github.com/sonic-molex/sonic-mgmt-common/blob/ocs/models/yang/sonic/sonic-ocs.yang). + +#### 9.2.2 CLI + +Most sonic CLI is implemented in sonic-utility based on [python click library](https://click.palletsprojects.com/en/8.1.x/). These CLI are supported in [sonic-utilities.](https://github.com/sonic-net/sonic-utilities). It is preferred that OCS CLI adopt auto-generation, instead of hard code python, for better maintainance and regularity. + +Automatically generates click based Python CLI code from SONiC yang, using [SONiC CLI auto-generation tool](https://github.com/sonic-net/SONiC/blob/master/doc/cli_auto_generation/cli_auto_generation.md). + +- Add [sonic-ocs.yang](https://github.com/sonic-molex/sonic-buildimage/blob/ocs/src/sonic-yang-models/yang-models/sonic-ocs.yang) into the sonic yang directory +- Generate OCS CLi at run time + +``` bash +admin@sonic: sonic-cli-gen generate config sonic-ocs +admin@sonic: sonic-cli-gen generate show sonic-ocs +``` + +The CLIs can also removed: + +```bash +admin@sonic: sonic-cli-gen remove config sonic-ocs +admin@sonic: sonic-cli-gen remove show sonic-ocs +``` + +The following OCS commands will be added after CLI is generated: + +``` bash + - show ocs-port //config + - show ocs-cross-connect //config + - show ocs-port-table //state + - show ocs-cross-connect-table //state + - config ocs-port 1B --config-status [force-blocked | normal | powered-off] + - config ocs-cross-connect add|delete|update conn-id [sideA sideB] +``` + +***Further Improvement*** + +In order to have better modulization for OCS support. OCS CLI can also be implemented as a SONiC compatible Docker image, based on [SONiC application extension mechanism](https://github.com/sonic-net/SONiC/tree/master/doc/sonic-application-extension). + +As a result, it can be built stand alone, then installed on a SONiC system at run time. Or it can be built into a sonic image at build time using [sonic-buildimage](https://github.com/sonic-net/sonic-buildimage). + +Another advantage of this approach can support auto generate CLI based on Openconfig yang and its annotation. See openconfig (standard) yang model support in SONiC (). + + CLI openconfig + +Stand alone application also provide a way of including other manual written CLIs. +For design and implementation, please see [here](https://github.com/sonic-molex/sonic-app-cli). + +#### 9.2.3 REST API + +SONiC management framework infrastructure's Translib converts the data models exposed to the management clients into the Redis ABNF schema format. See HLD [here](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/Management%20Framework.md). + +Therefore, after sonic-ocs.yang is add into `sonic-mgmt-common` yang mode [directory](https://github.com/sonic-molex/sonic-mgmt-common/blob/ocs/models/yang/sonic), REST API is supported automatically.S + +There is another SONiC module [sonic-restapi](https://github.com/sonic-net/sonic-restapi) implement REST API based on sonic yang model or Redis DB schema. However, SONiC Management Framework seems more generic, as it is capable to support standard (openconfig) yang model as well. + +### 9.3. Config DB Enhancements + +New config and state DB tables are introduced to support OCS device. Config DB and state DB schema are strictly mapped from sonic-ocs.yang: + +``` +CONFIG_DB +========= +OCS_PORT +;/sonic-ocs:sonic-ocs/OCS_PORT/OCS_PORT_LIST +;revision "2024-11-21" {reference "0.1.0"} +key = OCS_PORT|simplex_port-id ; string: 1A, 64B +;field = value +label = STRING ; +status = STRING ; yang enum: admin status + +OCS_CROSS_CONNECT +;/sonic-ocs:sonic-ocs/OCS_CROSS_CONNECT/OCS_CROSS_CONNECT_LIST +;revision "2024-11-21" {reference "0.1.0"} +key = OCS_CROSS_CONNECT|cross-connect-id ; string: 3A-3B +;field = value +a_side = STRING ; port-name +b_side = STRING ; port-name + +STATE_DB: +========= +OCS_PORT +;/sonic-ocs:sonic-ocs/OCS_PORT/OCS_PORT_LIST +;revision "2024-11-21" {reference "0.1.0"} +key = OCS_PORT|simplex_port-id ; string: 1A, 64B +;field = value +connect_type = STRING ; Duplex LC. MPO/MTP etc. +connect-pin = STRING ; position of the fiber strand in the connector, e.g., 2. +target_simplex_port_id = STRING ; Target port from cross-connect config +status = STRING ; yang enum oper status + +OCS_CROSS_CONNECT +;/sonic-ocs:sonic-ocs/OCS_CROSS_CONNECT/OCS_CROSS_CONNECT_LIST +;revision "2024-11-21" {reference "0.1.0"} +key = OCS_CROSS_CONNECT|cross-connect-id ; string: 3A-3B +;field = value +status = STRING ; enum, oper status +physical_path = STRING ; leaf list sequence of element in the physical path + +OCS_FACTORY_INSERTION_LOSS +;/sonic-ocs:sonic-ocs/OCS_FACTORY_INSERTION_LOSS/OCS_FACTORY_INSERTION_LOSS_LIST +;revision "2024-11-21" {reference "0.1.0"} +key = OCS_CROSS_CONNECT|cross-connect-id|temperature_C|frequency_THz ; string: 3 dimensions key +;field = value +loss_dB = decimal64 ; fraction digital 2: factory IL in dB +actual_dB = decimal64 ; fraction digital 2: measured IL in dB +``` + +The new DB tables are added in [`schema.h`](https://github.com/sonic-molex/sonic-swss-common/blob/ocs/common/schema.h) in `sonic-swss-comm`. Potentially, Tables for OCS can be defined in a separate file. (**TBD**). + +``` +//Config DB +#define CFG_OCS_CROSS_CONNECT_TABLE_NAME "OCS_CROSS_CONNECT" +#define CFG_OCS_PORT_TABLE_NAME "OCS_PORT" + +//App DB +#define APP_OCS_CROSS_CONNECT_TABLE_NAME "OCS_CROSS_CONNECT" +#define APP_OCS_PORT_TABLE_NAME "OCS_PORT" + +//State DB +#define STATE_OCS_CROSS_CONNECT_TABLE_NAME "OCS_CROSS_CONNECT_TABLE" +#define STATE_OCS_PORT_TABLE_NAME "OCS_PORT_TABLE" + +//Flexible Counter DB +#define OCS_PORT_COUNTER_STATS_LIST "OCS_PORT_COUNTER_STATS_LIST" +#define OCS_PORT_ATTRS_PLUGIN_FIELD "OCS_PORT_ATTRS_PLUGIN_FIELD" +#define OCS_CROSS_CONNECT_COUNTER_STATS_LIST "OCS_CROSS_CONNECT_COUNTER_STATS_LIST" +#define OCS_CROSS_CONNECT_STATS_PLUGIN_FIELD "OCS_CROSS_CONNECT_STATS_PLUGIN_FIELD" +#define OCS_CROSS_CONNECT_COUNTER_ATTRS_LIST "OCS_CROSS_CONNECT_COUNTER_ATTRS_LIST" +#define OCS_CROSS_CONNECT_ATTRS_PLUGIN_FIELD "OCS_CROSS_CONNECT_ATTRS_PLUGIN_FIELD + +``` + +### 9.4 Reuse Exsiting Features + +SONiC is a mature NOS, whihc provided most system management features. These features can be used for OCS device as is without any changes + +#### 9.4.1 Management and Loopback Interface + +OCS device will supports at least one DCN interface for device management (NBI). + +There are few alternate ways by which a static IP address can be configured for the management interface. + +- Use Click CLI: + +``` +admin@OCS001:~$ config interface ip add eth0 +``` + +- Use config_db.json and configure the MGMT_INTERFACE key with the appropriate values. See the config of management interface [here](https://github.com/sonic-net/SONiC/wiki/Configuration#management-interface). + +- The same method can be used to configure the Loopback interface address. + - /sbin/ifconfig lo Linux command shall be used. OR, + - Add the key LOOPBACK_INTERFACE and value in config_db.json and load it. + +Additionally, the management interfaces should suppport L3 routing protocol, OSPF and BGP. + +#### 9.4.2 TACACS+ AAA + + Please see [here](https://github.com/sonic-net/SONiC/blob/master/doc/aaa/TACACS%2B%20Authentication.md). + +#### 9.4.3 Syslog + +Please see [here](https://github.com/sonic-net/SONiC/blob/master/doc/syslog/syslog-design.md). + +#### 9.4.4 NTP + +Please see [here](https://github.com/sonic-net/SONiC/blob/master/doc/ntp/ntp-design.md). + +#### 9.4.5 Telemetry and gNMI + +[`sonic-telemetry'](https://github.com/sonic-net/sonic-telemetry) module seems obsoleted? + +gNMI set/get/telemetry now is supported by [gNMI Server](https://github.com/sonic-net/sonic-gnmi), Design doc [here](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/gnmi/SONiC_GNMI_Server_Interface_Design). + +#### 9.4.6 SONiC Management Framework + +[SONiC Management Framework](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/Management%20Framework.md) is design and implemented for support all NBI interfaces: + +1. Develper can write CLI (xml, actioner and render) based on [klish framework](https://src.libcode.org/pkun/klish/src/master). Please see [CLI section](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/Management%20Framework.md#3121-cli). +2. Its `Translib` converts the data models exposed to the management clients into the Redis ABNF schema format. Please see [this section](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/Management%20Framework.md#3224-REST-server). For example, after sonic-ocs.yang is add into sonic-mgmt-common yang mode [directory](https://github.com/sonic-molex/sonic-mgmt-common/blob/ocs/models/yang/sonic), REST API is supported automatically. +3. It also support gNMI set/get/telemetry as well. Please see [this section](https://github.com/sonic-net/SONiC/blob/master/doc/mgmt/Management%20Framework.md#3123-gnmi). + +In summary, SONiC management framework covers all the BNIs supported by other sonic modules. Which one should we use(***TBD***)? + +#### 9.4.7 SONiC upgrade + +Please see [here](https://github.com/sonic-net/SONiC/wiki/SONiC-to-SONiC-update). + +## 10. Warmboot and Fastboot Design Impact + +OCS support does not depends on or affect current SONiC warmboot and fastboot. Warm reboot should be a non-service-affect (NSA) operations?? + +## 11. Memory Consumption + +In a OCS device, most package features are not enabled in SWSS (configMgr and Orchagent). So the memeory consumption is less than a package switch. + +## 12. Restrictions/Limitations + +N/A + +## 13. Testing Requirements/Design (**TBD**) + +Explain what kind of unit testing, system testing, regression testing, warmboot/fastboot testing, etc., +Ensure that the existing warmboot/fastboot requirements are met. For example, if the current warmboot feature expects maximum of 1 second or zero second data disruption, the same should be met even after the new feature/enhancement is implemented. Explain the same here. +Example sub-sections for unit test cases and system test cases are given below. + +### 13.1. Unit Test cases + +### 13.2. System Test cases + +## 14. Open/Action items - if any + +NOTE: All the sections and sub-sections given above are mandatory in the design document. Users can add additional sections/sub-sections if required.