docs: vpp: document that kernel prerequisites need their own commit and reboot (#2233)mergify/bp/circinus/pr-2233

* docs: vpp: document that kernel prerequisites need their own commit and reboot

VPP depends on hugepages and, since T8460, on isolated CPUs. Both are
configured under "system option kernel", take effect only after a
reboot, and are validated by VPP against the running kernel. Because
"vpp" is committed at priority 295 and "system option" at 9999, the two
can never be applied in the same commit - the VPP part is always
rejected with "Not enough free memory to start VPP!" or "Not enough
isolated CPU cores available", both of which point back at the very
command the user just issued.

This is independent of the NIC: the checks that fail take no interface
or PCI information and run before the NIC validation. It was reproduced
both with an unsupported NIC and with a validated one.

Such a commit is also partial: the "system option kernel" part is
applied even though the commit is reported as failed, while the
"set vpp ..." statements are discarded and have to be re-entered after
the reboot.

The "Optimal Configuration Example" showed exactly this failing
one-shot form, mixing "set system option kernel ..." and "set vpp
settings ..." in a single block. Split it into the two stages that
actually work and state why, and add hugepages to it so the example
covers every prerequisite.

Also:

  * add a short "Kernel Configuration" item to the requirements page,
    which is what a first-time user reads and which had no pointer to
    the kernel settings at all
  * document the isolated-CPU requirement on the cpu-cores page, which
    did not mention "isolate-cpus"
  * add the missing 1af4:1041 (virtio modern ID) row to the validated
    NIC table - it is present in SUPPORTED_PCI_IDS but was absent here
  * correct the allow-unsupported-nics note, which said the check is
    bypassed "for the specified devices". There are no specified
    devices: _is_device_allowed() returns True for every interface as
    soon as the option is set, including interfaces attached later.
    That wording is a leftover from the per-PCI-ID form originally
    proposed in T8315, which was merged as a single boolean.

Verified by building the docs; the three changed pages produce no
Sphinx warnings.

Claude-Session: https://claude.ai/code/session_01EQsKVSw5hhDu7jPq1YzQvj

* docs: vpp: correct what a failed VPP commit leaves behind

Two corrections to the pages added earlier in this PR.

The partial-commit note claimed that the "set vpp ..." statements are
"discarded". They are not. Verified on VyOS 2026.03: after the commit
fails, "compare" still shows them staged in the configuration session.

  [vpp settings]
  + resource-allocation {
  +     memory {
  +         main-heap-size "6G"
  +     }
  + }

What actually happens is worse than the previous wording suggested and
worth stating precisely: the statements are neither applied nor written
by "save", because "save" writes the running configuration - which
"system_option.py" has already updated with the kernel options while the
VPP part was rejected. The session does not survive the reboot, so the
VPP statements are lost there rather than at commit time.

The isolated-CPU requirement was also described as if it only applied
once "cpu-cores" is raised. It applies at the default of "cpu-cores 1"
as well: verify_vpp_cpu_cores() rejects the commit whenever fewer CPUs
are isolated than requested, and VPP takes its main core from the
isolated set. The project's own test_01_vpp_basic relies on this - it
never sets "cpu-cores" and still expects "main-core" to be taken from
/sys/devices/system/cpu/isolated. Without this, a reader doing a minimal
setup would conclude that CPU isolation is optional for them.

Claude-Session: https://claude.ai/code/session_016gXeKHVBq2N8qRAMQkrdM6
(cherry picked from commit 93f84b050c90cb2d21d5216fc9d54fbcd118f407)

3 files changed, 104 insertions, 4 deletions

diff --git a/docs/vpp/configuration/dataplane/cpu.md b/docs/vpp/configuration/dataplane/cpu.md
index d92f6587..bd67b91e 100644
--- a/docs/vpp/configuration/dataplane/cpu.md
+++ b/docs/vpp/configuration/dataplane/cpu.md
@@ -35,6 +35,27 @@ This parameter defines the total number of CPU cores allocated to VPP.
 ```{cfgcmd} set vpp settings resource-allocation cpu-cores \<core-number\>
 ```
 
+:::{important}
+`cpu-cores` requires at least the same number of CPUs to be isolated from the
+kernel scheduler with `set system option kernel cpu isolate-cpus`. VPP takes
+its main core and its worker cores from the isolated set, and the commit is
+rejected when fewer CPUs are isolated than requested:
+
+```none
+Not enough isolated CPU cores available: 2 requested, but only 0 isolated.
+To isolate CPUs please use command
+"set system option kernel cpu isolate-cpus ..." save and reboot!
+```
+
+This applies even when `cpu-cores` is left at its default of `1`. VPP always
+takes its main core from the isolated set, so at least one CPU has to be
+isolated before the dataplane can be enabled at all.
+
+CPU isolation is a kernel option, so it has to be committed, saved and applied
+with a reboot **before** VPP is configured — the two cannot be set in the same
+commit. See {ref}`Optimal Configuration Example <vpp-config-setup-order>`.
+:::
+
 The system automatically assigns cores using the following rules:
 
 > - The first two CPU cores are always reserved for the operating system and
diff --git a/docs/vpp/configuration/dataplane/system.md b/docs/vpp/configuration/dataplane/system.md
index 51ee8f54..7ece3192 100644
--- a/docs/vpp/configuration/dataplane/system.md
+++ b/docs/vpp/configuration/dataplane/system.md
@@ -190,9 +190,24 @@ Disables all optional CPU mitigations for security vulnerabilities
 platforms.
 ```
 
+(vpp-config-setup-order)=
+
 ### Optimal Configuration Example
 
-For a system with 4 CPU cores (0-3) where cores 2-3 are dedicated to VPP:
+For a system with 4 CPU cores (0-3) where cores 2-3 are dedicated to VPP.
+
+:::{important}
+Kernel options and VPP settings **cannot be applied in the same commit**.
+
+Everything under `system option kernel` only takes effect after a reboot,
+while the VPP configuration is validated against the *running* kernel. VPP is
+also committed before `system option`, so within a single commit the kernel
+options are never in place yet and the VPP part is rejected.
+
+Configure the kernel options first, save, reboot, and only then configure VPP.
+:::
+
+**Step 1 — kernel options**
 
 ```none
 # Kernel CPU optimizations
@@ -201,12 +216,50 @@ set system option kernel cpu isolate-cpus '2-3'
 set system option kernel cpu nohz-full '2-3'
 set system option kernel cpu rcu-no-cbs '2-3'
 
+# Hugepages
+set system option kernel memory hugepage-size 2M hugepage-count '2048'
+
 # System optimizations
 set system option kernel disable-hpet
 set system option kernel disable-mce
 set system option kernel disable-power-saving
 set system option kernel disable-softlockup
+```
+
+Commit, save and reboot:
+
+```none
+commit
+save
+exit
+reboot
+```
+
+**Step 2 — VPP configuration, after the reboot**
 
+```none
 # VPP CPU assignment
 set vpp settings resource-allocation cpu-cores '2'
+
+# Interfaces to attach to the dataplane
+set vpp settings interface eth0
+set vpp settings interface eth1
 ```
+
+```none
+commit
+save
+```
+
+:::{note}
+If the VPP part is committed too early, the commit fails with a message such
+as `Not enough free memory to start VPP!` or `Not enough isolated CPU cores
+available`, both of which point back at `set system option kernel ...`. That
+means the reboot from step 1 has not happened yet.
+
+Note that such a commit is *partial*: the `system option kernel` part is still
+applied even though the commit is reported as failed. The `set vpp ...`
+statements stay in the configuration session, but they are neither applied nor
+written by `save`, which writes the *running* configuration. They are lost on
+the reboot and have to be entered again.
+:::
diff --git a/docs/vpp/requirements.md b/docs/vpp/requirements.md
index 159f70d4..db53058a 100644
--- a/docs/vpp/requirements.md
+++ b/docs/vpp/requirements.md
@@ -52,6 +52,23 @@ prerequisites before enabling VPP:
   - Recommended: 16 GB or more (especially for high throughput, many interfaces,
     or large routing tables).
 
+- **Kernel Configuration**
+
+  Besides the hardware itself, VPP needs hugepages and isolated CPU cores.
+  Both are configured under `system option kernel` and only take effect after
+  a reboot, while VPP validates them against the *running* kernel.
+
+  :::{important}
+  The kernel options and the VPP configuration cannot be applied in the same
+  commit. Configure them under `system option kernel` first, `commit`, `save`
+  and reboot, and only then configure VPP.
+  :::
+
+  :::{seealso}
+  {ref}`VyOS Configuration for VPP <vpp_config_system>` — hugepages, CPU
+  isolation and kernel tuning, with a worked example of both steps.
+  :::
+
 - **Network Interface Cards (NICs)**
 
   :::{warning}
@@ -102,6 +119,13 @@ prerequisites before enabling VPP:
   * - PCI ID
     - 1af4:1000
     - Red Hat, Inc. Virtio network device
+      (legacy ID)
+    - KVM-based hypervisors, including with
+      Open vSwitch; Google Cloud
+  * - PCI ID
+    - 1af4:1041
+    - Red Hat, Inc. Virtio network device
+      (modern ID)
     - KVM-based hypervisors, including with
       Open vSwitch; Google Cloud
   * - PCI ID
@@ -125,7 +149,9 @@ prerequisites before enabling VPP:
   ```
 
   :::{note}
-  This option bypasses the hardware validation checks for the specified
-  devices. Stability and performance are not guaranteed when using
-  unsupported NICs or drivers.
+  This option is a single global switch, not a per-device one: it bypasses
+  the hardware validation check for every interface attached to VPP, not
+  only for the one that needed it, and for interfaces attached later as
+  well. Stability and performance are not guaranteed when using unsupported
+  NICs or drivers.
   :::