From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/vpp/configuration/dataplane/system.md | 212 +++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 docs/vpp/configuration/dataplane/system.md (limited to 'docs/vpp/configuration/dataplane/system.md') diff --git a/docs/vpp/configuration/dataplane/system.md b/docs/vpp/configuration/dataplane/system.md new file mode 100644 index 00000000..51ee8f54 --- /dev/null +++ b/docs/vpp/configuration/dataplane/system.md @@ -0,0 +1,212 @@ +--- +lastproofread: '2026-02-27' +--- + +(vpp_config_system)= + +```{include} /_include/need_improvement.txt +``` + +# VyOS Configuration for VPP + +(vpp-config-hugepages)= + +## Hugepages + +VPP uses hugepages for efficient memory management. Hugepages are larger +memory pages that reduce the overhead of page management and improve +performance for applications that require large amounts of memory. + +Hugepages can be configured in VyOS using the following commands: + +:::{warning} +Changes to hugepage settings require a system reboot to take effect. + +Hugepages must be enabled before VPP configuration is applied. +::: + +To enable hugepages: + +```{cfgcmd} set system option kernel memory hugepage-size \ hugepage-count '\' +``` + +Enables hugepages with the specified size and count. The size can be either +2MB or 1GB, and the count specifies the number of hugepages to allocate. + +If your system has multiple NUMA nodes, the total amount of hugepages will be +divided equally among them. + +## Resources Limits + +:::{note} +By default, system will calculate and set the recommended values for +resource limits. Avoid tuning these values if you are not sure what you +are doing. +::: + +During operations VPP utilizes a significant amount of system resources, +especially memory. There are two main settings that may need to be +adjusted to ensure VPP runs smoothly: + +Maximum number of memory map areas a process may have: + +```{cfgcmd} set system option resource-limits max-map-count \ +``` + +Maximum shared memory segment size: + +```{cfgcmd} set system option resource-limits shmmax \ +``` + +Both settings are automatically calculated based on configured hugepages. + +## Kernel Tuning + +VPP performance greatly benefits from proper kernel tuning, especially +CPU isolation and disabling unnecessary kernel features. These +optimizations ensure dedicated CPU cores are available exclusively for +VPP dataplane processing without interference from the kernel scheduler +or other system processes. + +:::{warning} +Kernel tuning changes require a system reboot to take effect. + +Improper CPU isolation can lead to system instability if essential +system processes are starved of CPU resources. +::: + +### CPU Isolation and Optimization + +CPU isolation is crucial for VPP performance as it dedicates specific +CPU cores exclusively to VPP dataplane processing. The isolated cores are +removed from the kernel scheduler and will not run regular system +processes. + +**Disable NMI Watchdog** + +The NMI (Non-Maskable Interrupt) watchdog can interfere with VPP +performance by generating interrupts on isolated cores and is not +compatible with nohz-full mode: + +```{cfgcmd} set system option kernel cpu disable-nmi-watchdog + +Disables the NMI watchdog for detecting hard CPU lockups. This +prevents unnecessary interrupts on VPP worker cores. +``` + +**CPU Core Isolation** + +```{cfgcmd} set system option kernel cpu isolate-cpus \ + +Isolates specified CPUs from the kernel scheduler. Isolated cores will +not run regular system processes and are dedicated to applications like +VPP. + +The ```` can be: +* Single core: ``2`` +* Range: ``2-5`` +* Mixed: ``1,3-5,7`` + +:::{important} +Always reserve at least 2 cores for the operating system to ensure +system stability. For example, on a 4-core system, isolate cores +2-3 for VPP and leave cores 0-1 for the OS. + +Assign the first isolated core as the VPP main core and the +remaining isolated cores as VPP worker cores. Ensure that VPP CPU +assignments match the isolated CPU range. +::: +``` + +**Adaptive-Tick Mode** + +```{cfgcmd} set system option kernel cpu nohz-full \ + +Enables adaptive-tick mode (NO_HZ_FULL) for specified CPUs. This +causes the kernel to avoid sending scheduling-clock interrupts to CPUs +that have only one runnable task, significantly reducing interrupt +overhead for dedicated workloads like VPP. + +Use the same CPU range as configured for ``isolate-cpus``. +``` + +**RCU Callback Offloading** + +```{cfgcmd} set system option kernel cpu rcu-no-cbs \ + +Offloads Read-Copy-Update (RCU) callback processing from specified +CPUs. This ensures that RCU callbacks do not prevent the specified CPUs +from entering dyntick-idle or adaptive-tick mode, which is essential +for nohz-full functionality. + +Use the same CPU range as configured for ``isolate-cpus``. +``` + +### System Optimization + +Additional kernel optimizations can further improve VPP performance by +disabling unnecessary features and reducing system overhead. + +**Disable High Precision Event Timer** + +```{cfgcmd} set system option kernel disable-hpet + +Disables the High Precision Event Timer (HPET). HPET can cause +additional interrupts and overhead that may impact VPP performance. +``` + +**Disable Machine Check Exceptions** + +```{cfgcmd} set system option kernel disable-mce + +Disables Machine Check Exception (MCE) reporting and handling. While +MCE provides hardware error detection, it can introduce latency in +high-performance scenarios. +``` + +**Disable CPU Power Saving** + +```{cfgcmd} set system option kernel disable-power-saving + +Disables CPU power saving mechanisms (C-states). This keeps CPU cores +at maximum performance levels, eliminating latency from power state +transitions. +``` + +**Disable Soft Lockup Detection** + +```{cfgcmd} set system option kernel disable-softlockup + +Disables the soft lockup detector for kernel threads. This prevents +false positives when VPP worker threads are busy processing packets. +``` + +**Disable CPU Mitigations** + +```{cfgcmd} set system option kernel disable-mitigations + +Disables all optional CPU mitigations for security vulnerabilities +(for example, Spectre, Meltdown). This may improve performance on some +platforms. +``` + +### Optimal Configuration Example + +For a system with 4 CPU cores (0-3) where cores 2-3 are dedicated to VPP: + +```none +# Kernel CPU optimizations +set system option kernel cpu disable-nmi-watchdog +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' + +# 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 + +# VPP CPU assignment +set vpp settings resource-allocation cpu-cores '2' +``` -- cgit v1.2.3