2 files changed, 144 insertions, 0 deletions
diff --git a/docs/vpp/configuration/dataplane/md-buffers.md b/docs/vpp/configuration/dataplane/md-buffers.md
new file mode 100644
index 00000000..e9bddec9
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-buffers.md
@@ -0,0 +1,90 @@
+---
+lastproofread: '2026-02-23'
+---
+
+(vpp-config-dataplane-buffers)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Dataplane Buffers Configuration
+
+Buffers are essential for handling network packets efficiently. Proper
+configuration enhances performance and reliability, and is mandatory for
+VPP to work. Buffers temporarily store packets during processing. Therefore,
+their configuration must be in sync with NIC configuration, CPU threads, and
+overall system resources.
+
+:::{important}
+VPP buffers are allocated from the physical memory pool (`physmem`). The
+total amount of memory available for buffer allocation is controlled by the
+`physmem-max-size` setting, while the buffer configuration parameters
+below control how that memory is used for buffer allocation.
+
+See {ref}`VPP Physical Memory Configuration <vpp-config-dataplane-physmem>`
+for details on configuring `physmem`.
+:::
+
+## Buffer Configuration Parameters
+
+The following parameters can be configured for VPP buffers:
+
+### buffers-per-numa
+Number of buffers allocated per NUMA node. This setting optimizes
+memory access patterns for multi-CPU systems.
+
+Typically, you need to tune this value if:
+- The system has many interfaces
+- NICs have many queues
+- NICs have large descriptor sizes
+
+Set this value carefully to balance memory usage and performance.
+```{cfgcmd} set vpp settings resource-allocation buffers buffers-per-numa \<value\>
+```
+The common approach for the calculation is to use the formula:
+```none
+buffers-per-numa = (num-rx-queues * num-rx-desc) + (num-tx-queues * num-tx-desc)
+```
+Calculate this formula for each NIC and sum the results. Multiply the
+total by 2.5 to get the minimum recommended value for
+`buffers-per-numa`.
+
+Avoid setting this value too low to prevent packet drops.
+
+### data-size
+This value sets how much payload data can be stored in a single buffer
+allocated by VPP. Larger values reduce buffer chains for large packets,
+while smaller values conserve memory for environments handling mostly
+small packets.
+```{cfgcmd} set vpp settings resource-allocation buffers data-size \<value\>
+```
+Optimal size depends on the typical packet size in your network. If
+unsure, use the largest MTU in your network plus overhead (for example,
+128 bytes).
+
+### page-size
+A memory pages type used for buffer allocation. Common values are 4K, 2M, or 1G.
+
+Use page sizes configured in your system settings.
+```{cfgcmd} set vpp settings resource-allocation buffers page-size \<value\>
+```
+
+## Potential Issues and Troubleshooting
+
+Improper buffer configuration can lead to issues such as:
+
+- Increased latency and packet loss
+- Inefficient CPU utilization
+- Interface initialization failures
+
+Indicators of such issues are:
+
+- Errors during interfaces initialization in VPP logs
+- Packet drops observed in VPP statistics
+
+To troubleshoot buffer-related issues, consider the following steps:
+
+- Review VPP logs for errors related to buffer allocation. Look for
+  error `-5` messages.
+- Tune available buffers by adjusting the `buffers-per-numa` and
+  `data-size` parameters.
diff --git a/docs/vpp/configuration/dataplane/md-unix.md b/docs/vpp/configuration/dataplane/md-unix.md
new file mode 100644
index 00000000..9832b86d
--- /dev/null
+++ b/docs/vpp/configuration/dataplane/md-unix.md
@@ -0,0 +1,54 @@
+---
+lastproofread: '2026-02-27'
+---
+
+(vpp-config-dataplane-unix)=
+
+```{include} /_include/need_improvement.txt
+```
+
+# VPP Unix Dataplane Configuration
+The UNIX configuration section is used to control VPP's interaction
+with the underlying operating system, including operations scheduling.
+
+VPP relies on the polling mechanism to efficiently manage I/O operations
+and system events. By default VPP continuously polls for events, which
+leads to permanent 100% CPU usage by all cores assigned to VPP dataplane.
+This is optimal for performance, but may not be desirable in all
+environments, especially where power consumption is a concern or where VPP
+is running inside a hypervisor, especially if the VM has burstable
+thresholds and CPU usage limits.
+
+To mitigate this, VPP provides a configurable polling delay that allows
+reducing CPU usage by introducing a delay between polling cycles. This
+introduces a trade-off between CPU usage and latency, as longer delays
+can lead to increased latency in processing events.
+
+You can configure the polling delay using the following command in the
+VyOS CLI:
+```{cfgcmd} set vpp settings poll-sleep-usec \<delay\>
+```
+
+Sets the polling delay in microseconds. A value of 0 means no delay
+(default), while higher values introduce a delay between polling cycles.
+
+## Troubleshooting
+
+Setting the polling delay too high can lead to increased latency and
+reduced performance, as VPP may not respond to events as quickly.
+Conversely, setting it too low may result in high CPU usage, which can be
+problematic in resource-constrained environments.
+
+Symptoms of improper configuration may include:
+
+- Increased latency in packet processing
+- Higher CPU usage than expected
+- Packets lost due to buffer overruns
+
+If you do not need to reduce CPU usage, it is recommended to leave the
+polling delay at its default value of 0 for optimal performance.
+
+If you need to reduce CPU usage, you may also consider using `interrupt` or
+`adaptive` {ref}`DPDK driver modes <vpp-config-dataplane-interface-rx-mode>`,
+which can provide a balance between performance and resource utilization
+without affecting polling behavior.