Deploy preview for PR 20 🛫

Author: Koichi98

pr-preview/pr-20/environment-setup/scripts/index.html

@@ -1319,7 +1319,7 @@ <h2 id="kernel-module-management">Kernel module management<a class="headerlink"
 <tbody>
 <tr>
 <td><code>switch_kmod.bash</code></td>
-<td>Swap the host's <code>agnocast-kmod-v&lt;ver&gt;</code> to another version. For container-based setups where the heaphook travels with the container image and only the host-side kmod needs to be replaced independently. See <a href="../upgrading/#switching-only-the-host-kmod-container-based-setups">Upgrading → Switching only the host kmod</a> for details.</td>
+<td>Swap the host's <code>agnocast-kmod-v&lt;ver&gt;</code> to another version. For container-based setups where the heaphook travels with the container image and only the host-side kmod needs to be replaced independently. See <a href="../../tips/containers/#swapping-the-host-kernel-module">Running in Containers → Swapping the host kernel module</a> for details.</td>
 </tr>
 </tbody>
 </table>

pr-preview/pr-20/environment-setup/upgrading/index.html

@@ -510,13 +510,6 @@
     Version compatibility
   </a>
 
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#switching-only-the-host-kmod-container-based-setups" class="md-nav__link">
-    Switching only the host kmod (container-based setups)
-  </a>
-  
 </li>
 
     </ul>
@@ -1286,13 +1279,6 @@
     Version compatibility
   </a>
 
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#switching-only-the-host-kmod-container-based-setups" class="md-nav__link">
-    Switching only the host kmod (container-based setups)
-  </a>
-  
 </li>
 
     </ul>
@@ -1350,22 +1336,6 @@ <h2 id="version-compatibility">Version compatibility<a class="headerlink" href="
 <li><strong>Minor upgrades</strong> (e.g., 2.3.x → 2.4.0) — <code>agnocastlib</code> and <code>agnocast-kmod</code> must be upgraded together, as the kmod syscall API may have changed.</li>
 <li><strong>Major upgrades</strong> — User-facing API may have breaking changes. Review the changelog before upgrading.</li>
 </ul>
-<h2 id="switching-only-the-host-kmod-container-based-setups">Switching only the host kmod (container-based setups)<a class="headerlink" href="#switching-only-the-host-kmod-container-based-setups" title="Permanent link">#</a></h2>
-<p>When Agnocast workloads run inside a container, <code>agnocast-heaphook</code> is bundled with the container image and is swapped by rolling to a new container. In that setup, only the host-side <code>agnocast-kmod</code> needs to be replaced independently to keep the ioctl ABI in sync with the heaphook inside the container.</p>
-<p>The <a href="https://github.com/autowarefoundation/agnocast/blob/main/scripts/switch_kmod.bash"><code>switch_kmod.bash</code></a> script automates the host-side kmod swap:</p>
-<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>./scripts/switch_kmod.bash<span class="w"> </span>&lt;VERSION&gt;
-<span class="c1"># e.g.</span>
-sudo<span class="w"> </span>./scripts/switch_kmod.bash<span class="w"> </span><span class="m">2</span>.4.0
-</code></pre></div>
-<p>The script unloads the current module, purges every installed <code>agnocast-kmod-v*</code> package, cleans any leftover DKMS state, installs the target from apt, and verifies the new load via <code>dmesg</code>.</p>
-<div class="admonition warning">
-<p class="admonition-title">Warning</p>
-<p>All Agnocast containers and ROS nodes must be stopped before running this script — the module cannot be unloaded while <code>/dev/agnocast</code> is held open.</p>
-</div>
-<div class="admonition warning">
-<p class="admonition-title">Warning</p>
-<p>The kmod version on the host and the <code>libagnocast_heaphook.so</code> version inside the container must share the same ioctl ABI. Mismatched versions cause runtime errors. This script does not touch the container; it is the operator's responsibility to roll the container to a matching version.</p>
-</div>
 
 
 

pr-preview/pr-20/search/search_index.json

@@ -885,6 +885,13 @@
     Docker Compose Example
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#swapping-the-host-kernel-module" class="md-nav__link">
+    Swapping the host kernel module
+  </a>
+  
 </li>
 
     </ul>
@@ -1359,6 +1366,13 @@
     Docker Compose Example
   </a>
 
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#swapping-the-host-kernel-module" class="md-nav__link">
+    Swapping the host kernel module
+  </a>
+  
 </li>
 
     </ul>
@@ -1445,6 +1459,21 @@ <h2 id="docker-compose-example">Docker Compose Example<a class="headerlink" href
 <span class="w">    </span><span class="nt">devices</span><span class="p">:</span>
 <span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">/dev/agnocast</span>
 </code></pre></div>
+<h2 id="swapping-the-host-kernel-module">Swapping the host kernel module<a class="headerlink" href="#swapping-the-host-kernel-module" title="Permanent link">#</a></h2>
+<p>When you need to change the host's <code>agnocast-kmod</code> version independently of the heaphook bundled in the container (for example, after rolling the container image to a new version, or to reproduce a bug on an older kmod), use <a href="https://github.com/autowarefoundation/agnocast/blob/main/scripts/switch_kmod.bash"><code>switch_kmod.bash</code></a>:</p>
+<div class="highlight"><pre><span></span><code>sudo<span class="w"> </span>./scripts/switch_kmod.bash<span class="w"> </span>&lt;VERSION&gt;
+<span class="c1"># e.g.</span>
+sudo<span class="w"> </span>./scripts/switch_kmod.bash<span class="w"> </span><span class="m">2</span>.4.0
+</code></pre></div>
+<p>The script unloads the current module, purges every installed <code>agnocast-kmod-v*</code> package, cleans any leftover DKMS state, installs the target from apt, and verifies the new load via <code>dmesg</code>.</p>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>All Agnocast containers and ROS nodes must be stopped before running this script — the module cannot be unloaded while <code>/dev/agnocast</code> is held open.</p>
+</div>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>The kmod version on the host and the <code>libagnocast_heaphook.so</code> version inside the container must share the same ioctl ABI. Mismatched versions cause runtime errors. This script does not touch the container; it is the operator's responsibility to roll the container to a matching version.</p>
+</div>