Deployed 5f539ed to dev with MkDocs 1.6.1 and mike 2.1.3

Author: HHDocs

dev/known-limitations/known-limitations/index.html

@@ -1546,6 +1546,48 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#breakout-and-cmis-transceiver-initialization-issues-on-ds5000" class="md-nav__link">
+    <span class="md-ellipsis">
+      Breakout and CMIS transceiver initialization issues on DS5000
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Breakout and CMIS transceiver initialization issues on DS5000">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#diagnosing-the-issue_1" class="md-nav__link">
+    <span class="md-ellipsis">
+      Diagnosing the issue
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#resolution" class="md-nav__link">
+    <span class="md-ellipsis">
+      Resolution
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#additional-guidance" class="md-nav__link">
+    <span class="md-ellipsis">
+      Additional guidance
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
     </ul>
@@ -1829,6 +1871,48 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#breakout-and-cmis-transceiver-initialization-issues-on-ds5000" class="md-nav__link">
+    <span class="md-ellipsis">
+      Breakout and CMIS transceiver initialization issues on DS5000
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Breakout and CMIS transceiver initialization issues on DS5000">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#diagnosing-the-issue_1" class="md-nav__link">
+    <span class="md-ellipsis">
+      Diagnosing the issue
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#resolution" class="md-nav__link">
+    <span class="md-ellipsis">
+      Resolution
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#additional-guidance" class="md-nav__link">
+    <span class="md-ellipsis">
+      Additional guidance
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
     </ul>
@@ -1862,6 +1946,7 @@ <h1 id="known-limitations">Known Limitations</h1>
 <li><a href="#configuration-not-allowed-when-port-is-member-of-portchannel">Configuration not allowed when port is member of PortChannel</a></li>
 <li><a href="#external-peering-over-a-connection-originating-from-an-mclag-switch-can-fail"><abbr title="Definition of the &quot;external system&quot; to peer with (could be one or multiple devices such as edge/provider routers)">External</abbr> peering over a connection originating from an MCLAG switch can fail</a></li>
 <li><a href="#mesh-limitations-on-th5-based-devices">Mesh limitations on TH5-based devices</a></li>
+<li><a href="#breakout-and-cmis-transceiver-initialization-issues-on-ds5000">Breakout and CMIS transceiver initialization issues on DS5000</a></li>
 </ul>
 <h3 id="deleting-a-vpc-and-creating-a-new-one-right-away-can-cause-the-agent-to-fail">Deleting a <abbr title="Virtual Private Cloud, similar to the public cloud VPC it provides an isolated private network for the resources with support for multiple subnets each with user-provided VLANs and on-demand DHCP">VPC</abbr> and creating a new one right away can cause the agent to fail</h3>
 <p>The issue is due to limitations in SONiC's gNMI interface. In this particular case,
@@ -1923,6 +2008,25 @@ <h4 id="known-workarounds_3">Known workarounds</h4>
 <p>None. We recommend avoiding mesh topologies on TH5-based devices for the
 time being, with the exception of 2-node topologies without gateway, where
 the above issues would not apply.</p>
+<h3 id="breakout-and-cmis-transceiver-initialization-issues-on-ds5000">Breakout and CMIS transceiver initialization issues on DS5000</h3>
+<p>On Celestica DS5000 devices, certain transceivers using the Common Management Interface Specification (CMIS) fail to initialize properly under specific conditions.</p>
+<p>CMIS is an open standard for managing high-speed pluggable transceivers, providing a uniform way for the network operating system to interact with and monitor them.</p>
+<h4 id="diagnosing-the-issue_1">Diagnosing the issue</h4>
+<p>If you breakout a port (for example, changing from 1x800G to 2x400G or 8x100G) while no transceiver is present, and then insert a transceiver afterward, initialization may fail and the transceiver may be missing or appear as failed in SONiC.</p>
+<p>This occurs because SONiC did not always correctly reinitialize hardware abstraction for the port after breakout and re-insertion in this scenario, especially affecting CMIS modules.</p>
+<h4 id="resolution">Resolution</h4>
+<ul>
+<li>The Hedgehog Fabric agent now automatically patches <code>/usr/share/sonic/platform/pddf/pddf-device.json</code> as needed after NOS installation (the patch is indicated by <code>-hh1</code> in the description). No user action is required to apply this workaround.</li>
+<li>A full switch reboot is still required after agent deployment for the patch to take effect.</li>
+<li>The <code>REBOOTREQ</code> column for the agent object in <code>kubectl</code> or <code>k9s</code> will indicate if a reboot is needed.</li>
+<li>If you encounter existing transceiver failures (such as after an upgrade), a full power cycle of the switch, sometimes referred as cold boot, may still be required in addition to the reboot.</li>
+</ul>
+<h4 id="additional-guidance">Additional guidance</h4>
+<ul>
+<li>Prefer inserting transceivers before breaking out ports to avoid the issue altogether, if possible.</li>
+<li>Always follow any REBOOTREQ status after upgrades or configuration changes.</li>
+<li>If problems persist, perform a full power cycle as a last resort.</li>
+</ul>
 
 
 
@@ -1945,7 +2049,7 @@ <h4 id="known-workarounds_3">Known workarounds</h4>
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">November 20, 2025</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">December 9, 2025</span>
   </span>
 
 

dev/search/search_index.json

@@ -1546,6 +1546,48 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#breakout-and-cmis-transceiver-initialization-issues-on-ds5000" class="md-nav__link">
+    <span class="md-ellipsis">
+      Breakout and CMIS transceiver initialization issues on DS5000
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Breakout and CMIS transceiver initialization issues on DS5000">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#diagnosing-the-issue_1" class="md-nav__link">
+    <span class="md-ellipsis">
+      Diagnosing the issue
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#resolution" class="md-nav__link">
+    <span class="md-ellipsis">
+      Resolution
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#additional-guidance" class="md-nav__link">
+    <span class="md-ellipsis">
+      Additional guidance
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
     </ul>
@@ -1829,6 +1871,48 @@
       </ul>
     </nav>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#breakout-and-cmis-transceiver-initialization-issues-on-ds5000" class="md-nav__link">
+    <span class="md-ellipsis">
+      Breakout and CMIS transceiver initialization issues on DS5000
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Breakout and CMIS transceiver initialization issues on DS5000">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#diagnosing-the-issue_1" class="md-nav__link">
+    <span class="md-ellipsis">
+      Diagnosing the issue
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#resolution" class="md-nav__link">
+    <span class="md-ellipsis">
+      Resolution
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#additional-guidance" class="md-nav__link">
+    <span class="md-ellipsis">
+      Additional guidance
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
 
     </ul>
@@ -1862,6 +1946,7 @@ <h1 id="known-limitations">Known Limitations</h1>
 <li><a href="#configuration-not-allowed-when-port-is-member-of-portchannel">Configuration not allowed when port is member of PortChannel</a></li>
 <li><a href="#external-peering-over-a-connection-originating-from-an-mclag-switch-can-fail"><abbr title="Definition of the &quot;external system&quot; to peer with (could be one or multiple devices such as edge/provider routers)">External</abbr> peering over a connection originating from an MCLAG switch can fail</a></li>
 <li><a href="#mesh-limitations-on-th5-based-devices">Mesh limitations on TH5-based devices</a></li>
+<li><a href="#breakout-and-cmis-transceiver-initialization-issues-on-ds5000">Breakout and CMIS transceiver initialization issues on DS5000</a></li>
 </ul>
 <h3 id="deleting-a-vpc-and-creating-a-new-one-right-away-can-cause-the-agent-to-fail">Deleting a <abbr title="Virtual Private Cloud, similar to the public cloud VPC it provides an isolated private network for the resources with support for multiple subnets each with user-provided VLANs and on-demand DHCP">VPC</abbr> and creating a new one right away can cause the agent to fail</h3>
 <p>The issue is due to limitations in SONiC's gNMI interface. In this particular case,
@@ -1923,6 +2008,25 @@ <h4 id="known-workarounds_3">Known workarounds</h4>
 <p>None. We recommend avoiding mesh topologies on TH5-based devices for the
 time being, with the exception of 2-node topologies without gateway, where
 the above issues would not apply.</p>
+<h3 id="breakout-and-cmis-transceiver-initialization-issues-on-ds5000">Breakout and CMIS transceiver initialization issues on DS5000</h3>
+<p>On Celestica DS5000 devices, certain transceivers using the Common Management Interface Specification (CMIS) fail to initialize properly under specific conditions.</p>
+<p>CMIS is an open standard for managing high-speed pluggable transceivers, providing a uniform way for the network operating system to interact with and monitor them.</p>
+<h4 id="diagnosing-the-issue_1">Diagnosing the issue</h4>
+<p>If you breakout a port (for example, changing from 1x800G to 2x400G or 8x100G) while no transceiver is present, and then insert a transceiver afterward, initialization may fail and the transceiver may be missing or appear as failed in SONiC.</p>
+<p>This occurs because SONiC did not always correctly reinitialize hardware abstraction for the port after breakout and re-insertion in this scenario, especially affecting CMIS modules.</p>
+<h4 id="resolution">Resolution</h4>
+<ul>
+<li>The Hedgehog Fabric agent now automatically patches <code>/usr/share/sonic/platform/pddf/pddf-device.json</code> as needed after NOS installation (the patch is indicated by <code>-hh1</code> in the description). No user action is required to apply this workaround.</li>
+<li>A full switch reboot is still required after agent deployment for the patch to take effect.</li>
+<li>The <code>REBOOTREQ</code> column for the agent object in <code>kubectl</code> or <code>k9s</code> will indicate if a reboot is needed.</li>
+<li>If you encounter existing transceiver failures (such as after an upgrade), a full power cycle of the switch, sometimes referred as cold boot, may still be required in addition to the reboot.</li>
+</ul>
+<h4 id="additional-guidance">Additional guidance</h4>
+<ul>
+<li>Prefer inserting transceivers before breaking out ports to avoid the issue altogether, if possible.</li>
+<li>Always follow any REBOOTREQ status after upgrades or configuration changes.</li>
+<li>If problems persist, perform a full power cycle as a last resort.</li>
+</ul>
 
 
 
@@ -1945,7 +2049,7 @@ <h4 id="known-workarounds_3">Known workarounds</h4>
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">November 20, 2025</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date">December 9, 2025</span>
   </span>