Dev/nl/switch qos rdma doc update

[Nick Liu (liunick-msft)]

Summary

Separates Azure Local RDMA networking guidance into three focused documents:

• The QoS reference defines the end-to-end RDMA QoS requirements and Cisco NX-OS implementation.
• The ECN reference explains congestion marking, transport feedback, and validation.
• The LLDP/DCBX/PFC troubleshooting guide covers the validated Mellanox ConnectX and Cisco NX-OS failure scenario.

Changes

• Clarified PFC, ETS, ECN, MTU, traffic-class, and end-to-end validation requirements.
• Replaced Mermaid diagrams with fixed-width text diagrams.
• Corrected ECN codepoints and terminology.
• Added metadata and cross-references to all three documents.
• Narrowed the troubleshooting guide to its validated Mellanox/Cisco scope.
• Removed duplicated policy guidance and unsupported multi-vendor remediation.
• Consolidated four duplicate firmware-staging blocks into one shared procedure.
• Preserved storage-health gates, risk labels, rollback guidance, and verification steps.
• Updated the Networking index with the revised troubleshooting scope.

Before and After

Before	After
QoS design, ECN details, and incident remediation were repeated across documents.	Each document has a distinct purpose and links to the appropriate companion guidance.
The troubleshooting guide included unvalidated vendor-specific branches.	The guide is scoped to the validated Mellanox ConnectX and Cisco NX-OS case.
Firmware staging was repeated in every activation option.	Firmware staging is performed once before selecting an activation method.
DCBX wording blurred local host settings and transmitted DCBX TLVs.	Local Willing=False posture is distinguished from LLDP/DCBX TLV transmission.

Validation

• Validated all metadata markers against TSG/Templates/tsg-metadata.schema.json.
• Verified local document and Networking index links.
• Confirmed no Mermaid blocks remain in the three-document set.
• Confirmed the firmware staging command appears exactly once.
• Ran Markdown diagnostics with no reported errors.
• Ran git diff --check successfully.

Notes

This is a documentation-only change. It does not change the remediation outcome: maintain a durable Windows LLDP agent, force priority-3 PFC on Cisco storage ports, disable the Mellanox firmware LLDP/DCBX agent, and verify the resulting state.

[Copilot]

🟡 Changes recommended

Switch configuration consistency and remediation safety gaps must be addressed before publication.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This documentation-only PR separates Azure Local RDMA guidance into focused QoS, ECN, and Mellanox/Cisco troubleshooting documents.

Changes:

• Adds end-to-end QoS and ECN requirements.
• Narrows troubleshooting to validated Mellanox ConnectX/Cisco NX-OS scenarios.
• Consolidates firmware staging and updates cross-references.

File summaries

File	Description
Troubleshoot-TOR-LLDP-DCBX-PFC-RoCEv2.md	Refines scope and remediation workflow.
Reference-TOR-QOS-Policy-Configuration.md	Expands end-to-end QoS guidance.
Reference-TOR-Explicit-Congestion-Notification.md	Clarifies ECN behavior and validation.
README.md	Updates the troubleshooting index entry.

Review details

Suppressed comments (3)

TSG/Networking/Top-Of-Rack-Switch/Troubleshoot-TOR-LLDP-DCBX-PFC-RoCEv2.md:1411

• The rollback restores only the running configuration even though this step has already copied the new state to startup configuration. A later reload would therefore reapply forced PFC instead of the rollback; verify and save the restored state as part of the rollback.

**Rollback:** Restore the captured interface configuration. If the prior state was PFC auto mode, apply it only long enough to return to the recorded state, verify the interface, and stop the remediation because Step 3 requires forced PFC to remain operational.

TSG/Networking/Top-Of-Rack-Switch/Troubleshoot-TOR-LLDP-DCBX-PFC-RoCEv2.md:1423

• This new stop rule conflicts with later non-Mellanox branches that still say Steps 1 and 2 apply (lines 1540, 1725, 1779, and 1954), while other updated branches say the TSG does not apply. Make every non-Mellanox branch emit the same stop-and-route message so operators are not given mutually exclusive instructions.

> tells you whether this node has Mellanox NICs. If it reports none, **skip Step 3
> and stop this TSG**. Do not apply these firmware commands to another adapter family.

TSG/Networking/Top-Of-Rack-Switch/Troubleshoot-TOR-LLDP-DCBX-PFC-RoCEv2.md:1754

• The staging block does not inspect mlxconfig's exit status, so a failed device write does not actually stop the loop as this instruction requires. An operator can then activate a partially staged node; make the block terminate on the first nonzero exit and always restore the working directory.

Confirm the staging command succeeds for every discovered device. If any write fails, stop before resetting or rebooting a card. Re-run Diagnosis Step 6 to record the current and next-boot values.

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.