diff --git a/doc/transceiver_clis_key_formatting/platform_specific_key_formatting.md b/doc/transceiver_clis_key_formatting/platform_specific_key_formatting.md new file mode 100644 index 00000000000..bf5bd3650eb --- /dev/null +++ b/doc/transceiver_clis_key_formatting/platform_specific_key_formatting.md @@ -0,0 +1,179 @@ +# Align transceiver CLIs formatting for common and platform-specific technology extensions + +## 1. Revision + +| Rev | Date | Author | Change Description | +|:---:|:----:|:------:|:-------------------| +| 0.1 | 05/2026 | | Initial version | + +## 2. Scope + +This HLD defines the minimal changes required to align the 'sfputil' and 'show interface transceiver' CLIs +to include new common and platform-specific data in the output (CPO as reference use case). + +It includes 2 main parts: +1. Ensure we print the common new CPO fields - using new key formatting map for these fields. +2. Create new ability to have key formatting map for the platform-specific fields. + +Relevant CLIs: +- `sfputil show eeprom -d` +- `show interfaces transceiver eeprom -d` +- `show interfaces transceiver status` + +## 3. Overview + +The goal is simple: **New technology fields must be formatted consistently across CLIs**, +while keeping platform-specific formatting logic in platform code. + +## 4. Requirements + +- Ensure we print the common new CPO fields - using new key formatting map for these fields (as done today for other types). +- Create new ability to have key formatting map for the platform-specific fields (of any technology). +- `sonic-utilities` should not hardcode platform-specific labels/units. +Platform implementations should provide their own maps via the APIs (5.3). + +## 5. High-Level Design + +### 5.1. How it works today + +```python +# The real code is more complex but the following is a simpler version just to present the idea + +DATA_MAP = { + 'model': 'Vendor PN', + 'vendor_oui': 'Vendor OUI', + 'vendor_date': 'Vendor Date Code(YYYY-MM-DD Lot)', + 'manufacturer': 'Vendor Name', + 'vendor_rev': 'Vendor Rev', + # ... +} + +# CMIS_DATA_MAP = { ... } +# QSFP_DD_DATA_MAP = { ... } +# DOM_DATA_MAP = { ... } + +# ... + +sfp = platform_chassis.get_sfp(physical_port) +# Since sfp is platform object, it will return also platform-specific fields. +info = sfp.get_transceiver_info() # Or get_all('TRANSCEIVER_INFO|') + +for key in info: + print(f'{DATA_MAP[key]} : {info[key]}') +``` + +### 5.2. Add common CPO format maps in utilities (sfputil and sfpshow) + +Add/extend CPO-specific display maps in shared utility code for common fields (not platform-specific fields), including: + +- CPO transceiver info labels +- CPO DOM labels/units +- CPO status labels + +These maps are merged into the existing flows only when the transceiver type is CPO. + +### 5.3. Add explicit platform-specific formatting APIs on `SfpBase` + +Expose platform hooks as three explicit APIs: + +- `get_platform_specific_transceiver_info_format_map() -> dict` +- `get_platform_specific_transceiver_status_format_map() -> dict` +- `get_platform_specific_dom_format_map() -> tuple(dict, dict)` + +Default implementation returns empty maps, so platforms with no platform-specific extension continue to work without behavior change. + +### 5.4. Keep platform-specific map ownership in platform code + +`sonic-utilities` should not hardcode platform-specific labels/units. +Platform implementations should provide their own maps via the APIs above. + +### 5.5. Integration Example (Reference) + +```python +# src/sonic-platform-common/sonic_platform_base/sfp_base.py:SfpBase + +def get_platform_specific_transceiver_info_format_map(self): + """ + Retrieves the platform-specific transceiver info format map. + """ + return {} + +def get_platform_specific_transceiver_status_format_map(self): + """ + Retrieves the platform-specific transceiver status format map. + """ + return {} + +def get_platform_specific_dom_format_map(self): + """ + Retrieves platform-specific DOM format and unit maps. + + Returns: + tuple(dict, dict): (dom_value_map, dom_unit_map) + """ + return {}, {} +``` + +```python +# platform/mellanox/mlnx-platform-api/sonic_platform/sfp.py:CpoPort + +CPO_DOM_CHANNEL_FORMAT_MAP = { + # ... +} + +CPO_STATUS_MAP = { + # ... +} + +# ... + +def get_platform_specific_transceiver_status_format_map(self): + """ + Retrieves the platform-specific transceiver status format map. + """ + return self.CPO_STATUS_MAP +``` + +```python +# src/sonic-utilities/sfputil/main.py + +CMIS_DOM_CHANNEL_MONITOR_MAP = { + 'rx1power': 'RX1Power', + 'rx2power': 'RX2Power', + # ... +} + +''' NEW ''' +CPO_DOM_CHANNEL_MONITOR_MAP = { + 'els_tx1bias': 'ELS Lane1Bias', + 'els_tx1voltage': 'ELS Lane1Voltage', + 'els_tx1power': 'ELS Lane1Power', + # ... +} + +# Flow for displaying the DOM information: + +# Since sfp is platform object, it will return also platform-specific fields. +info = sfp.get_transceiver_dom_real_value() + +format_map = CMIS_DOM_CHANNEL_MONITOR_MAP +''' NEW ''' +if sfp_type == 'CPO': + # Adding new common CPO formatting + format_map.update(CPO_DOM_CHANNEL_MONITOR_MAP) + +print('ChannelMonitorValues:') +for key in info: + print(f'{format_map[key]} : {info[key]}') + +print('ModuleMonitorValues:') +# ... + +''' NEW ''' +# platform-specific DOM formatting +print('PlatformSpecificDomValues:') +platform_specific_dom_format_map = sfp.get_platform_specific_dom_format_map() +for key in info: + if key in platform_specific_dom_format_map: + print(f'{platform_specific_dom_format_map[key]} : {info[key]}') +```