[docs][transceiver]: DOM HLD - operational ranges are per-PN (drop default values, add guidance)

[mihirpat1]

Description of PR

Summary: The DOM test plan's Attributes table lists concrete default values for the six *_operational_range attributes. Operational ranges are inherently per-transceiver — they depend on the module's normal-operation envelope — so a single default invites copy-paste that false-fails modules operating outside it. This change converts the operational-range rows to format placeholders (as the *_threshold_range rows already are) and documents how to derive operational ranges per part number, plus the "unsupported ⇒ omit" rule.

MSFT ADO - 39011423

Type of change

• Bug fix
• Testbed and Framework(new/improvement)
• New Test case
  • Skipped for non-supported platforms
• Test case improvement

Back port request

• 202205
• 202305
• 202311
• 202405
• 202411
• 202505
• 202511

Approach

What is the motivation for this PR?

A module whose Tx/Rx power operates at ~+3 dBm would false-fail the current illustrative operational maxes if those were copied verbatim into a module's dom.json. Because the presence of an attribute drives verification, shipping concrete default values in the HLD is a footgun.

How did you do it?

Replaced the default-value cells for the six *_operational_range attributes with (format) {"min": <float>, "max": <float>} (matching the existing *_threshold_range rows), and added two notes:

• Operational ranges are per-PN, derived from the module datasheet or observed steady-state DOM readings, and must sit within the module's warning thresholds (lowwarning < operational_min, operational_max < highwarning).
• Omit both *_operational_range and *_threshold_range for a parameter the module does not support (e.g., laser_temperature with all-zero threshold fields), so availability/range checks don't run against meaningless data.

How did you verify/test it?

Documentation-only change; no code paths modified. Validated the guidance against a live module whose operational values exceed the previous illustrative maxes.

Any platform specific information?

No.

Supported testbed topology if it's a new test case?

N/A (documentation).

Documentation

HLD updated: docs/testplan/transceiver/dom_test_plan.md.

[Copilot]

Pull request overview

This PR updates the DOM transceiver test plan documentation to avoid implying universal “default” operational ranges for DOM sensors, and adds guidance for configuring operational ranges per transceiver part number (PN), including how to handle unsupported parameters.

Changes:

• Replaces concrete default values for *_operational_range attributes with format placeholders to discourage copy/paste misconfiguration.
• Adds guidance to derive operational ranges per PN and keep them within warning thresholds.
• Documents an “unsupported ⇒ omit” rule to avoid running checks against meaningless DOM fields.

Comments suppressed due to low confidence (2)

docs/testplan/transceiver/dom_test_plan.md:60

• Same Markdown rendering issue here: <float> inside the table cell is interpreted as an HTML tag unless it’s inside inline code or escaped. Wrapping the JSON examples in backticks keeps the placeholders visible.

| laser_temperature_threshold_range | dict | (format) {"lowalarm": <float>, "lowwarning": <float>, "highwarning": <float>, "highalarm": <float>} | O | transceivers | Absolute threshold laser temperature range in Celsius (specify all four; omit to skip laser temperature threshold checks) |
| txLANE_NUMbias_operational_range | dict | (format) {"min": <float>, "max": <float>} | O | transceivers | Realistic operational TX bias current range in mA for lane LANE_NUM during normal operation |
| tx_bias_threshold_range | dict | (format) {"lowalarm": <float>, "lowwarning": <float>, "highwarning": <float>, "highalarm": <float>} | O | transceivers | Absolute threshold TX bias current range in mA (EEPROM limits; skip attribute to disable bias threshold validation) |
| txLANE_NUMpower_operational_range | dict | (format) {"min": <float>, "max": <float>} | O | transceivers | Realistic operational TX power range in dBm for lane LANE_NUM during normal operation |
| tx_power_threshold_range | dict | (format) {"lowalarm": <float>, "lowwarning": <float>, "highwarning": <float>, "highalarm": <float>} | O | transceivers | Absolute threshold TX power range in dBm (define all four for TX power threshold validation) |

docs/testplan/transceiver/dom_test_plan.md:62

• These table placeholders have the same <float>-as-HTML-tag rendering problem; consider formatting the JSON as inline code so the angle-bracket placeholders remain visible in rendered Markdown.

| rxLANE_NUMpower_operational_range | dict | (format) {"min": <float>, "max": <float>} | O | transceivers | Realistic operational RX power range in dBm for lane LANE_NUM during normal operation |
| rx_power_threshold_range | dict | (format) {"lowalarm": <float>, "lowwarning": <float>, "highwarning": <float>, "highalarm": <float>} | O | transceivers | Absolute threshold RX power range in dBm (omit attribute to skip RX power threshold validation) |

[mssonicbld]

/azp run

[mihirpat1]

Superseded by upstream PR sonic-net#26663 (base should target upstream, not the fork).