vpp: Enhanced memory, buffers, and CGNAT documentation, added troubleshooting (#1687)

* vpp: Enhanced memory and buffer configuration documentation

- Added physmem configuration section with practical examples and troubleshooting
- Clarified relationship between physmem and buffer allocation with cross-references
- Improved VPP logging documentation with detailed log location descriptions
- Fixed formatting issues in system configuration

* vpp: Added CGNAT memory requirements

Expanded CGNAT settings page with information about:
- Memory requirements
- Hardcoded simultaneous sessions limit

* vpp: Added troubleshooting page

Added page with basic steps for troubleshooting:
- Capturing packets (PCAP)
- Tracing packets
- Additional diagnostics information from VPP
- Automatic collection of most details with Python script

---------

Co-authored-by: Daniil Baturin <daniil@baturin.org>

1 files changed, 41 insertions, 0 deletions

diff --git a/docs/vpp/configuration/dataplane/memory.rst b/docs/vpp/configuration/dataplane/memory.rst
index 8f0ebe61..7b100c92 100644
--- a/docs/vpp/configuration/dataplane/memory.rst
+++ b/docs/vpp/configuration/dataplane/memory.rst
@@ -32,6 +32,39 @@ Sets the main heap page size for VPP.
 
 Sets the main heap size for VPP.
 
+.. _vpp_config_dataplane_physmem:
+
+Physical Memory Configuration
+=============================
+
+VPP uses physical memory for packet buffers and interface operations. The ``physmem`` setting controls how much memory VPP can allocate for these operations.
+
+.. cfgcmd:: set vpp settings physmem max-size <size>
+
+Sets the maximum amount of physical memory VPP can use for packet processing and interface buffers.
+
+**Default**: 16GB (usually sufficient for most deployments)
+
+You may need to modify the value for high-throughput environments with many interfaces, large packet buffers, or very high packet rates or memory-constrained systems where you need to limit VPP's memory usage.
+
+**Physmem Independent of main heap size** - physmem is for packet buffers, main heap is for routing tables.
+
+.. seealso::
+
+   - :ref:`Hugepages in VyOS Configuration for VPP <vpp_config_hugepages>`
+   - :ref:`VPP Buffer Configuration <vpp_config_dataplane_buffers>` - for controlling buffer allocation within physmem
+
+Common configurations
+---------------------
+
+.. code-block:: none
+
+   # Reduce for memory-constrained systems
+   set vpp settings physmem max-size 4G
+
+   # Increase for high-throughput environments
+   set vpp settings physmem max-size 32G
+
 
 Potential Issues and Troubleshooting
 ====================================
@@ -43,3 +76,11 @@ Improper configuration of main heap size can lead to performance degradation or
 - Error messages related to memory allocation failures
 
 You need to tune the main heap size based on expected FIB entries. Pay attention - same amount of routes with a single next-hop and with multiple next-hops will consume different amounts of memory.
+
+For physmem, insufficient allocation can lead to packet drops, interface initialization failures, and overall degraded performance. Symptoms include:
+
+- Packet drops or failures to allocate buffers
+- Increased latency or jitter in packet processing
+- Crashes or restarts of VPP processes under heavy load
+
+You need to tune the physmem settings based on expected traffic patterns and interface usage. Monitor memory usage closely and adjust the configuration as needed to ensure optimal performance.