Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mihirpat1 wants to merge 1 commit into from
Closed

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions docs/testplan/transceiver/dom_test_plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,23 +38,27 @@ A `dom.json` file is used to define the attributes for the DOM tests for the var

**Note on Operational vs. Threshold Ranges:** The DOM test framework uses dual-range validation to provide more nuanced testing. Realistic operational ranges represent the expected values during normal, healthy operation in typical data center environments. These ranges are tighter than the absolute EEPROM threshold ranges and help distinguish between normal operation and edge cases that, while within specification, may indicate environmental stress, aging components, or suboptimal conditions. This approach enables early detection of potential issues before they trigger formal alarms, providing better system health monitoring and preventive maintenance capabilities.

**Note on configuring operational ranges (per-PN):** Operational ranges have no universal defaults — they depend on each transceiver's normal-operation envelope. Derive them per part number from the module datasheet (or observed steady-state DOM readings), and keep them inside the module's warning thresholds: `lowwarning < operational_min` and `operational_max < highwarning`. Do not copy a one-size-fits-all range; for example, a module whose Tx/Rx power operates at ~+3 dBm would incorrectly fail a generic `{"min": -8, "max": 2}`.

**Note on unsupported parameters:** If a module does not support a DOM parameter — indicated by an absent sensor field, or a sensor/threshold set pinned to `0.0` (e.g., `laser_temperature` with all-zero `lasertemp*` thresholds) — omit both its `_operational_range` and `_threshold_range` attributes for that PN, so availability and range checks do not run against meaningless data.

The following table summarizes the key attributes used in DOM testing. This table serves as the authoritative reference for all attributes and must be updated whenever new attributes are introduced:

**Legend:** M = Mandatory, O = Optional

| Attribute Name | Type | Default Value | Mandatory | Override Levels | Description |
|----------------|------|---------------|-----------|-----------------|-------------|
| temperature_operational_range | dict | {"min": 20.0, "max": 70.0} | O | transceivers | Realistic operational temperature range in Celsius during normal operation (typical: room temp to moderate heat) |
| temperature_operational_range | dict | (format) {"min": <float>, "max": <float>} | O | transceivers | Realistic operational temperature range in Celsius during normal operation (typical: room temp to moderate heat) |
| temperature_threshold_range | dict | (format) {"lowalarm": <float>, "lowwarning": <float>, "highwarning": <float>, "highalarm": <float>} | O | transceivers | Absolute threshold temperature range in Celsius (must define all four keys; no implicit defaults) |
| voltage_operational_range | dict | {"min": 3.20, "max": 3.40} | O | transceivers | Realistic operational voltage range in volts during normal operation (typical: 3.3V ±3%) |
| voltage_operational_range | dict | (format) {"min": <float>, "max": <float>} | O | transceivers | Realistic operational voltage range in volts during normal operation (typical: 3.3V ±3%) |
| voltage_threshold_range | dict | (format) {"lowalarm": <float>, "lowwarning": <float>, "highwarning": <float>, "highalarm": <float>} | O | transceivers | Absolute threshold voltage range in volts (provide EEPROM alarm/warn limits; skip to disable voltage threshold validation) |
| laser_temperature_operational_range | dict | {"min": 20.0, "max": 70.0} | O | transceivers | Realistic operational laser temperature range in Celsius during normal operation |
| laser_temperature_operational_range | dict | (format) {"min": <float>, "max": <float>} | O | transceivers | Realistic operational laser temperature range in Celsius during normal operation |
Comment on lines +51 to +55
| 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 | {"min": 50.0, "max": 180.0} | O | transceivers | Realistic operational TX bias current range in mA for lane LANE_NUM during normal operation |
| 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 | {"min": -3.0, "max": 3.0} | O | transceivers | Realistic operational TX power range in dBm for lane LANE_NUM during normal operation |
| 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) |
| rxLANE_NUMpower_operational_range | dict | {"min": -8.0, "max": 2.0} | O | transceivers | Realistic operational RX power range in dBm for lane LANE_NUM during normal operation |
| 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) |
| max_update_time_sec | integer | 60 | O | platform | Maximum expected time in seconds between DOM data updates for continuous monitoring validation |
| consistency_check_poll_count | integer | 3 | O | transceivers or platform | Number of polling cycles to perform when validating DOM data consistency and variation patterns |
Expand Down
Loading