From e2b9f19bbafdcd5711d748db11fe76578e6b77b3 Mon Sep 17 00:00:00 2001 From: Zili Bombach Date: Sun, 19 Apr 2026 21:55:25 +0300 Subject: [PATCH 1/3] label port mapping CLI - HLD Signed-off-by: Zili Bombach --- .../label-ports mapping cli -design.md | 140 ++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 doc/label_port_mapping_cli/label-ports mapping cli -design.md diff --git a/doc/label_port_mapping_cli/label-ports mapping cli -design.md b/doc/label_port_mapping_cli/label-ports mapping cli -design.md new file mode 100644 index 00000000000..70a21d911f3 --- /dev/null +++ b/doc/label_port_mapping_cli/label-ports mapping cli -design.md @@ -0,0 +1,140 @@ +# Label-port to Interfaces/Lanes mapping and status CLI + +## Table of contents + +- [Background](#1-background) +- [Method](#2-method) +- [Requirements (platform.json content)](#3-requirements-platformjson-content) +- [Error Handling](#4-error-handling) +- [Unit Tests](#5-unit-tests) + - [Positive tests](#positive-tests) + - [Negative tests](#negative-tests) + +## 1. Background + +On SONiC systems, the relationship between front-panel label ports, their physical lanes, and the correlated SONiC interface names change by platform and by breakout configuration. With more complex setups, such as CPO and multi-ASIC systems, this mapping becomes even more complicated, which raised the need for a CLI that provides a single, standardized view that shows, for each front-panel label port, how it maps to lanes and SONiC interfaces under the current split mode. + +## 2. Method + +1. Get Label-port → lanes mapping from platform.json. +2. Get the running ports configuration and lane splits from CONFIG_DB. +3. Get ports status from APPL_DB . +4. Create and print a table that shows the current Label-ports → ports mapping (based on the current configuration and platform lanes map). + +Note - for multi-ASIC systems, the output also shows to which ASIC each port belongs to. + +Example output: + +Single-ASIC ( 2 x 4x) + +```text +>> show interfaces label-port status + +Label-port | Lane 1 | Lane 2 | Lane 3 | Lane 4 +-----------|---------------|---------------|---------------|--------------- +1 | Ethernet0(UP) | Ethernet0(UP) | Ethernet0(UP) | Ethernet0(UP) +2 | Ethernet4(UP) | Ethernet4(UP) | Ethernet4(UP) | Ethernet4(UP) +3 | Ethernet8(UP) | Ethernet8(UP) | Ethernet8(UP) | Ethernet8(UP) +... +128 | Ethernet508(UP) | Ethernet508(UP) | Ethernet508(DN) | Ethernet508(UP) +``` + +Single-ASIC ( 4 x 2x) + +```text +>> show interfaces label-port status + +Label-port | Lane 1 | Lane 2 | Lane 3 | Lane 4 +-----------|---------------|---------------|---------------|--------------- +1 | Ethernet0(UP) | Ethernet0(UP) | Ethernet2(UP) | Ethernet2(UP) +2 | Ethernet4(UP) | Ethernet4(UP) | Ethernet6(UP) | Ethernet6(UP) +3 | Ethernet8(UP) | Ethernet8(UP) | Ethernet10(UP) | Ethernet10(UP) +... +128 | Ethernet508(UP) | Ethernet508(UP) | Ethernet510(DN) | Ethernet510(UP) +``` + +Multi-ASIC + +```text +>> show interfaces label-port status + +Label-port | Lane 1 | Lane 2 | Lane 3 | Lane 4 +-----------|---------------------|---------------------|---------------------|--------------------- +1 | Ethernet0/asic0(UP) | Ethernet512/asic1(UP) | Ethernet1024/asic2(UP) | Ethernet1536/asic3(UP) +2 | Ethernet1/asic0(UP) | Ethernet513/asic1(UP) | Ethernet1025/asic2(UP) | Ethernet1537/asic3(UP) +3 | Ethernet2/asic0(UP) | Ethernet514/asic1(UP) | Ethernet1026/asic2(UP) | Ethernet1538/asic3(UP) +... +512 | Ethernet511/asic0(UP) | Ethernet1023/asic1(UP) | Ethernet1535/asic2(DN) | Ethernet2047/asic3(UP) +``` + +## 3. Requirements (platform.json content) + +For all supported platforms, platform.json should be extended with: + +1. label_port_lanes_mapping (object): + a. Key: Label-port identifiers (strings, e.g., "1", "2"). + b. Values: list of lane numbers (strings, e.g., ["1", "2", "3", "4"] ). +2. For multi-ASIC platforms only - number_of_lanes_per_asic (stringified integer) - Used to compute global lane offsets on multi-ASIC systems: global_lane = local_lane + (asic_index × number_of_lanes_per_asic). + +Example: + +platform.json + +```json +// Single-ASIC + +"label_port_lanes_mapping": { + "1": ["0", "1", "2", "3"], + "2": ["4", "5", "6", "7"], + ... + "127": ["504", "505", "506", "507"], + "128": ["508", "509", "510", "511"] +} +``` + +```json +// Multi-ASIC + +"number_of_lanes_per_asic": "512", +"label_port_lanes_mapping": { + "1": ["0", "512", "1024", "1536"], + "2": ["1", "513", "1025", "1537"], + ... + "511": ["510", "1022", "1534", "2046"], + "512": ["511", "1023", "1535", "2047"] +} +``` + +## 4. Error Handling + +- Missing platform JSON: "No platform data found" → abort. + +- Missing Label-port _lanes_mapping: "No Label-port mapping found in platform data" → abort. + +- Missing/invalid number_of_lanes_per_asic on multi-ASIC: clear error → abort. + +- Lane not present in mapping (mismatch): skip that lane placement; continue. + +- Missing oper_status displays as DOWN. + +## 5. Unit Tests + +### Positive tests + +- Basic single-ASIC test: renders correct header and lane placements with ``(UP|DOWN). + +- Basic multi-ASIC test: renders correct header and lane placements with `/`(UP|DOWN). + +- Mixed splits (4/2/1): lane positions reflect split sizes and ordered mapping, counts match fanout. + +### Negative tests + +- Platform JSON read error: returns non-zero exit and shows "No platform data found". + +- Missing Label-port _lanes_mapping: returns non-zero exit and shows "No Label-port mapping found in platform data". + +- Multi-ASIC missing number_of_lanes_per_asic: returns non-zero exit and shows "No number of lanes per ASIC found in platform data". + +- One ASIC down (multi-ASIC): rows for the down ASIC render "-". other ASIC lanes map correctly with namespace suffix. + +- Missing oper_status: port displays as DOWN. From 27d19970e340c586de6f889181627890b98df0de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=AAZili=20Bombach=E2=80=AC=E2=80=8F?= <126357360+zili11720@users.noreply.github.com> Date: Thu, 23 Apr 2026 09:45:52 +0300 Subject: [PATCH 2/3] Update label-ports mapping cli -design.md Signed-off-by: Zili Bombach --- doc/label_port_mapping_cli/label-ports mapping cli -design.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/label_port_mapping_cli/label-ports mapping cli -design.md b/doc/label_port_mapping_cli/label-ports mapping cli -design.md index 70a21d911f3..72f08c28086 100644 --- a/doc/label_port_mapping_cli/label-ports mapping cli -design.md +++ b/doc/label_port_mapping_cli/label-ports mapping cli -design.md @@ -12,7 +12,7 @@ ## 1. Background -On SONiC systems, the relationship between front-panel label ports, their physical lanes, and the correlated SONiC interface names change by platform and by breakout configuration. With more complex setups, such as CPO and multi-ASIC systems, this mapping becomes even more complicated, which raised the need for a CLI that provides a single, standardized view that shows, for each front-panel label port, how it maps to lanes and SONiC interfaces under the current split mode. +On SONiC systems, the relationship between front-panel label ports, their physical lanes, and the correlated SONiC interface names change by platform and by breakout configuration. With more complex setups, such as multi-ASIC systems, this mapping becomes even more complicated, which raised the need for a CLI that provides a single, standardized view that shows, for each front-panel label port, how it maps to lanes and SONiC interfaces under the current split mode. ## 2. Method From 58d46520e2f42a83e086fac07feee84a67c6ee9b Mon Sep 17 00:00:00 2001 From: Zili Bombach Date: Wed, 10 Jun 2026 10:06:52 +0300 Subject: [PATCH 3/3] resolve copilot comments Signed-off-by: Zili Bombach --- .../label-port-mapping-cli-design.md | 191 ++++++++++++++++++ .../label-ports mapping cli -design.md | 140 ------------- 2 files changed, 191 insertions(+), 140 deletions(-) create mode 100644 doc/label_port_mapping_cli/label-port-mapping-cli-design.md delete mode 100644 doc/label_port_mapping_cli/label-ports mapping cli -design.md diff --git a/doc/label_port_mapping_cli/label-port-mapping-cli-design.md b/doc/label_port_mapping_cli/label-port-mapping-cli-design.md new file mode 100644 index 00000000000..893ff660ebe --- /dev/null +++ b/doc/label_port_mapping_cli/label-port-mapping-cli-design.md @@ -0,0 +1,191 @@ +# Label-port to Interfaces/Lanes mapping CLI + +## Table of Content + +- [Revision](#revision) +- [Scope](#scope) +- [Definitions/Abbreviations](#definitionsabbreviations) +- [Overview](#overview) +- [Requirements](#requirements) +- [Architecture Design](#architecture-design) +- [High-Level Design](#high-level-design) +- [SAI API](#sai-api) +- [Configuration and management](#configuration-and-management) + - [Manifest (if the feature is an Application Extension)](#manifest-if-the-feature-is-an-application-extension) + - [CLI/YANG model Enhancements](#cliyang-model-enhancements) + - [Config DB Enhancements](#config-db-enhancements) +- [Warmboot and Fastboot Design Impact](#warmboot-and-fastboot-design-impact) + - [Warmboot and Fastboot Performance Impact](#warmboot-and-fastboot-performance-impact) +- [Memory Consumption](#memory-consumption) +- [Restrictions/Limitations](#restrictionslimitations) +- [Testing Requirements/Design](#testing-requirementsdesign) + - [Unit Test cases](#unit-test-cases) + - [System Test cases](#system-test-cases) +- [Open/Action items - if any](#openaction-items---if-any) + +### Revision + + +| Rev | Date | Author | Change Description | +| --- | ---------- | ------------ | ------------------ | +| 1 | 06/09/2026 | Zili Bombach | Initial version | + + +### Scope + +This document covers the design of the read-only `show interfaces label-port status` CLI, including platform.json mapping requirements and multi-ASIC display behavior. +Config commands are out of scope. + +### Definitions/Abbreviations + +### Overview + +On SONiC systems, the relationship between front-panel label ports, their physical lanes, and the correlated SONiC interface names changes by platform and by breakout configuration. With more complex setups, such as multi-ASIC systems, this mapping becomes even more complicated, which raised the need for a CLI that provides a single, standardized view that shows, for each front-panel label port, how it maps to lanes and SONiC interfaces under the current split mode. + +### Requirements + +- Provide a read-only CLI (`show interfaces label-port status`) that maps each front-panel label port to its lanes, SONiC interfaces, and operational status under the current breakout configuration. +- Support single-ASIC and multi-ASIC platforms. +- Require platform vendors to supply `label_port_lanes_mapping` in platform.json; multi-ASIC platforms also require `number_of_lanes_per_asic` (see [Requirements (platform.json content)](#requirements-platformjson-content)). + +### Architecture Design + +### High-Level Design + +1. Get Label-port → lanes mapping from platform.json. +2. Get the running ports configuration and lane splits from CONFIG_DB. +3. Get port status from APPL_DB. +4. Create and print a table that shows the current label-port → ports mapping (based on the current configuration and platform lanes map). + +Note - for multi-ASIC systems, the output also shows to which ASIC each port belongs to. + +Example output: + +Single-ASIC (2 x 4x) + +```text +>> show interfaces label-port status + +Label Port | Lane 1 | Lane 2 | Lane 3 | Lane 4 +-----------|---------------|---------------|---------------|--------------- +1 | Ethernet0(UP) | Ethernet0(UP) | Ethernet0(UP) | Ethernet0(UP) +2 | Ethernet4(UP) | Ethernet4(UP) | Ethernet4(UP) | Ethernet4(UP) +3 | Ethernet8(UP) | Ethernet8(UP) | Ethernet8(UP) | Ethernet8(UP) +... +128 | Ethernet508(UP) | Ethernet508(UP) | Ethernet508(DOWN) | Ethernet508(UP) +``` + +Single-ASIC (4 x 2x) + +```text +>> show interfaces label-port status + +Label Port | Lane 1 | Lane 2 | Lane 3 | Lane 4 +-----------|---------------|---------------|---------------|--------------- +1 | Ethernet0(UP) | Ethernet0(UP) | Ethernet2(UP) | Ethernet2(UP) +2 | Ethernet4(UP) | Ethernet4(UP) | Ethernet6(UP) | Ethernet6(UP) +3 | Ethernet8(UP) | Ethernet8(UP) | Ethernet10(UP) | Ethernet10(UP) +... +128 | Ethernet508(UP) | Ethernet508(UP) | Ethernet510(DOWN) | Ethernet510(UP) +``` + +Multi-ASIC + +```text +>> show interfaces label-port status + +Label Port | Lane 1 | Lane 2 | Lane 3 | Lane 4 +-----------|---------------------|---------------------|---------------------|--------------------- +1 | Ethernet0|asic0(UP) | Ethernet512|asic1(UP) | Ethernet1024|asic2(UP) | Ethernet1536|asic3(UP) +2 | Ethernet1|asic0(UP) | Ethernet513|asic1(UP) | Ethernet1025|asic2(UP) | Ethernet1537|asic3(UP) +3 | Ethernet2|asic0(UP) | Ethernet514|asic1(UP) | Ethernet1026|asic2(UP) | Ethernet1538|asic3(UP) +... +512 | Ethernet511|asic0(UP) | Ethernet1023|asic1(UP) | Ethernet1535|asic2(DOWN) | Ethernet2047|asic3(UP) +``` + +#### Requirements (platform.json content) + +For all supported platforms, platform.json should be extended with: + +1. label_port_lanes_mapping (object): + a. Key: Label-port identifiers (strings, e.g., "1", "2"). + b. Values: list of lane numbers (strings, e.g., ["0", "1", "2", "3"] ). +2. For multi-ASIC platforms only - number_of_lanes_per_asic - Used to compute global lane offsets on multi-ASIC systems: global_lane = local_lane + (asic_index × number_of_lanes_per_asic). + +Example: + +platform.json + +```json +// Single-ASIC + +"label_port_lanes_mapping": { + "1": ["0", "1", "2", "3"], + "2": ["4", "5", "6", "7"], + ... + "127": ["504", "505", "506", "507"], + "128": ["508", "509", "510", "511"] +} +``` + +```json +// Multi-ASIC + +"number_of_lanes_per_asic": "512", +"label_port_lanes_mapping": { + "1": ["0", "512", "1024", "1536"], + "2": ["1", "513", "1025", "1537"], + ... + "511": ["510", "1022", "1534", "2046"], + "512": ["511", "1023", "1535", "2047"] +} +``` + +#### Error Handling + +- Missing platform JSON: "No platform data found" → abort. +- Missing `label_port_lanes_mapping` in platform.json: "No Label-port mapping found in platform data" → abort. +- Missing/invalid `number_of_lanes_per_asic` on multi-ASIC: "No number of lanes per ASIC found in platform data" → abort. +- Lane not present in mapping (mismatch): skip that lane placement; cell displays `-`; continue. +- Missing oper_status displays as DOWN. + +### SAI API + +### Configuration and management + +#### Manifest (if the feature is an Application Extension) + +#### CLI/YANG model Enhancements + +#### Config DB Enhancements + +### Warmboot and Fastboot Design Impact + +#### Warmboot and Fastboot Performance Impact + +### Memory Consumption + +### Restrictions/Limitations + +### Testing Requirements/Design + +#### Unit Test cases + +##### Positive tests + +- Basic single-ASIC test: renders correct header and lane placements with ``(UP|DOWN). +- Basic multi-ASIC test: renders correct header and lane placements with `|`(UP|DOWN). +- Mixed splits (4/2/1): lane positions reflect split sizes and ordered mapping, counts match fanout. + +##### Negative tests + +- Platform JSON read error: returns non-zero exit and shows "No platform data found". +- Missing `label_port_lanes_mapping` in platform.json: returns non-zero exit and shows "No Label-port mapping found in platform data". +- Multi-ASIC missing number_of_lanes_per_asic: returns non-zero exit and shows "No number of lanes per ASIC found in platform data". +- One ASIC down (multi-ASIC): rows for the down ASIC render "-". other ASIC lanes map correctly with namespace suffix. +- Missing oper_status: port displays as DOWN. + +#### System Test cases + +### Open/Action items - if any + diff --git a/doc/label_port_mapping_cli/label-ports mapping cli -design.md b/doc/label_port_mapping_cli/label-ports mapping cli -design.md deleted file mode 100644 index 72f08c28086..00000000000 --- a/doc/label_port_mapping_cli/label-ports mapping cli -design.md +++ /dev/null @@ -1,140 +0,0 @@ -# Label-port to Interfaces/Lanes mapping and status CLI - -## Table of contents - -- [Background](#1-background) -- [Method](#2-method) -- [Requirements (platform.json content)](#3-requirements-platformjson-content) -- [Error Handling](#4-error-handling) -- [Unit Tests](#5-unit-tests) - - [Positive tests](#positive-tests) - - [Negative tests](#negative-tests) - -## 1. Background - -On SONiC systems, the relationship between front-panel label ports, their physical lanes, and the correlated SONiC interface names change by platform and by breakout configuration. With more complex setups, such as multi-ASIC systems, this mapping becomes even more complicated, which raised the need for a CLI that provides a single, standardized view that shows, for each front-panel label port, how it maps to lanes and SONiC interfaces under the current split mode. - -## 2. Method - -1. Get Label-port → lanes mapping from platform.json. -2. Get the running ports configuration and lane splits from CONFIG_DB. -3. Get ports status from APPL_DB . -4. Create and print a table that shows the current Label-ports → ports mapping (based on the current configuration and platform lanes map). - -Note - for multi-ASIC systems, the output also shows to which ASIC each port belongs to. - -Example output: - -Single-ASIC ( 2 x 4x) - -```text ->> show interfaces label-port status - -Label-port | Lane 1 | Lane 2 | Lane 3 | Lane 4 ------------|---------------|---------------|---------------|--------------- -1 | Ethernet0(UP) | Ethernet0(UP) | Ethernet0(UP) | Ethernet0(UP) -2 | Ethernet4(UP) | Ethernet4(UP) | Ethernet4(UP) | Ethernet4(UP) -3 | Ethernet8(UP) | Ethernet8(UP) | Ethernet8(UP) | Ethernet8(UP) -... -128 | Ethernet508(UP) | Ethernet508(UP) | Ethernet508(DN) | Ethernet508(UP) -``` - -Single-ASIC ( 4 x 2x) - -```text ->> show interfaces label-port status - -Label-port | Lane 1 | Lane 2 | Lane 3 | Lane 4 ------------|---------------|---------------|---------------|--------------- -1 | Ethernet0(UP) | Ethernet0(UP) | Ethernet2(UP) | Ethernet2(UP) -2 | Ethernet4(UP) | Ethernet4(UP) | Ethernet6(UP) | Ethernet6(UP) -3 | Ethernet8(UP) | Ethernet8(UP) | Ethernet10(UP) | Ethernet10(UP) -... -128 | Ethernet508(UP) | Ethernet508(UP) | Ethernet510(DN) | Ethernet510(UP) -``` - -Multi-ASIC - -```text ->> show interfaces label-port status - -Label-port | Lane 1 | Lane 2 | Lane 3 | Lane 4 ------------|---------------------|---------------------|---------------------|--------------------- -1 | Ethernet0/asic0(UP) | Ethernet512/asic1(UP) | Ethernet1024/asic2(UP) | Ethernet1536/asic3(UP) -2 | Ethernet1/asic0(UP) | Ethernet513/asic1(UP) | Ethernet1025/asic2(UP) | Ethernet1537/asic3(UP) -3 | Ethernet2/asic0(UP) | Ethernet514/asic1(UP) | Ethernet1026/asic2(UP) | Ethernet1538/asic3(UP) -... -512 | Ethernet511/asic0(UP) | Ethernet1023/asic1(UP) | Ethernet1535/asic2(DN) | Ethernet2047/asic3(UP) -``` - -## 3. Requirements (platform.json content) - -For all supported platforms, platform.json should be extended with: - -1. label_port_lanes_mapping (object): - a. Key: Label-port identifiers (strings, e.g., "1", "2"). - b. Values: list of lane numbers (strings, e.g., ["1", "2", "3", "4"] ). -2. For multi-ASIC platforms only - number_of_lanes_per_asic (stringified integer) - Used to compute global lane offsets on multi-ASIC systems: global_lane = local_lane + (asic_index × number_of_lanes_per_asic). - -Example: - -platform.json - -```json -// Single-ASIC - -"label_port_lanes_mapping": { - "1": ["0", "1", "2", "3"], - "2": ["4", "5", "6", "7"], - ... - "127": ["504", "505", "506", "507"], - "128": ["508", "509", "510", "511"] -} -``` - -```json -// Multi-ASIC - -"number_of_lanes_per_asic": "512", -"label_port_lanes_mapping": { - "1": ["0", "512", "1024", "1536"], - "2": ["1", "513", "1025", "1537"], - ... - "511": ["510", "1022", "1534", "2046"], - "512": ["511", "1023", "1535", "2047"] -} -``` - -## 4. Error Handling - -- Missing platform JSON: "No platform data found" → abort. - -- Missing Label-port _lanes_mapping: "No Label-port mapping found in platform data" → abort. - -- Missing/invalid number_of_lanes_per_asic on multi-ASIC: clear error → abort. - -- Lane not present in mapping (mismatch): skip that lane placement; continue. - -- Missing oper_status displays as DOWN. - -## 5. Unit Tests - -### Positive tests - -- Basic single-ASIC test: renders correct header and lane placements with ``(UP|DOWN). - -- Basic multi-ASIC test: renders correct header and lane placements with `/`(UP|DOWN). - -- Mixed splits (4/2/1): lane positions reflect split sizes and ordered mapping, counts match fanout. - -### Negative tests - -- Platform JSON read error: returns non-zero exit and shows "No platform data found". - -- Missing Label-port _lanes_mapping: returns non-zero exit and shows "No Label-port mapping found in platform data". - -- Multi-ASIC missing number_of_lanes_per_asic: returns non-zero exit and shows "No number of lanes per ASIC found in platform data". - -- One ASIC down (multi-ASIC): rows for the down ASIC render "-". other ASIC lanes map correctly with namespace suffix. - -- Missing oper_status: port displays as DOWN.