Merge pull request #20 from autowarefoundation/docs/update_to_add_switch_kmod

docs: update to add `switch_kmod.bash`

Author: Koichi98

docs/environment-setup/scripts.md

@@ -13,6 +13,12 @@ Neither script requires `agnocast.ko` to be loaded or `libagnocast_heaphook.so`
 | `dds_config.bash` | Apply CycloneDDS runtime settings (`net.core.rmem_max`, loopback multicast) required for Agnocast over CycloneDDS. Guarded by `/tmp/cycloneDDS_configured` so it runs only once per boot. |
 | `setup_thread_configurator.bash` | Grant `CAP_SYS_NICE` to `thread_configurator_node` and register library paths in `/etc/ld.so.conf.d/agnocast-cie.conf`. Automates the manual steps described in [CallbackIsolatedExecutor → Integration Guide, Step 2](../callback-isolated-executor/integration-guide.md#step-2-set-up-the-thread-configurator). |
 
+## Kernel module management
+
+| Script | Purpose |
+|---|---|
+| `switch_kmod.bash` | Swap the host's `agnocast-kmod-v<ver>` 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 [Running in Containers → Swapping the host kernel module](../tips/containers.md#swapping-the-host-kernel-module) for details. |
+
 ## Sample application launchers
 
 Each `sample_application/run_*.bash` script is a thin wrapper that runs `source install/setup.bash` followed by `ros2 launch agnocast_sample_application <name>.launch.xml`. All launch files set `LD_PRELOAD=libagnocast_heaphook.so` automatically, so every sample below requires both `agnocast.ko` to be loaded and `libagnocast_heaphook.so` to be available (via apt or a local source build).

docs/tips/containers.md

@@ -99,3 +99,30 @@ services:
     devices:
       - /dev/agnocast
 ```
+
+## Swapping the host kernel module
+
+When you need to change the host's `agnocast-kmod` 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 [`switch_kmod.bash`](https://github.com/autowarefoundation/agnocast/blob/main/scripts/switch_kmod.bash):
+
+```bash
+sudo ./scripts/switch_kmod.bash <VERSION>
+# e.g.
+sudo ./scripts/switch_kmod.bash 2.4.0
+```
+
+The script unloads the current module, purges every installed `agnocast-kmod-v*` package, cleans any leftover DKMS state, installs the target from apt, and verifies the new load via `dmesg`.
+
+!!! warning
+    All Agnocast containers and ROS nodes must be stopped before running this script — the module cannot be unloaded while `/dev/agnocast` is held open.
+
+!!! warning
+    The kmod version on the host and the `libagnocast_heaphook.so` 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.
+
+After the swap, verify that the host kmod, the in-container `libagnocast_heaphook.so`, and the in-container `agnocastlib` are on compatible versions by running
+
+```bash
+source <your-workspace>/install/setup.bash   # must include the ros2agnocast package
+ros2 agnocast -v
+```
+
+**inside the container** where your Agnocast application actually runs. The command prints the detected kmod / heaphook / agnocastlib versions and flags any incompatibility.