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>

4 files changed, 53 insertions, 3 deletions

diff --git a/docs/vpp/configuration/dataplane/buffers.rst b/docs/vpp/configuration/dataplane/buffers.rst
index 3d6ba5b3..999471e3 100644
--- a/docs/vpp/configuration/dataplane/buffers.rst
+++ b/docs/vpp/configuration/dataplane/buffers.rst
@@ -12,6 +12,12 @@ Buffers are essential for handling network packets efficiently, and proper confi
 
 Buffers are used to temporarily store packets during processing, therefore their configuration should 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
 ===============================
 
diff --git a/docs/vpp/configuration/dataplane/logging.rst b/docs/vpp/configuration/dataplane/logging.rst
index 41da367a..2081be24 100644
--- a/docs/vpp/configuration/dataplane/logging.rst
+++ b/docs/vpp/configuration/dataplane/logging.rst
@@ -10,7 +10,10 @@ VPP Logging Configuration
 
 VPP logging is an important part of monitoring and troubleshooting the performance and behavior of the VPP dataplane.
 
-VPP logs are stored in the ``/var/log/vpp.log`` file. Additionally daemon logs can be found in the system journal.
+VPP stores logs in two places:
+
+- ``/var/log/vpp.log`` — This file contains logs related to daemon startup and log of commands executed directly via VPP CLI. Pay attention, VyOS does not use VPP CLI for configuration, so this log will not contain any configuration changes made via VyOS CLI, and will not be informative in most cases.
+- System journal — contains logs related to the VPP daemon work, including errors, warnings, and informational messages. It is the main destination of logs generated by VPP.
 
 Logging detalization can be configured via the next command:
 
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.
diff --git a/docs/vpp/configuration/dataplane/system.rst b/docs/vpp/configuration/dataplane/system.rst
index 5ed3b5e6..660668b8 100644
--- a/docs/vpp/configuration/dataplane/system.rst
+++ b/docs/vpp/configuration/dataplane/system.rst
@@ -85,9 +85,9 @@ The NMI (Non-Maskable Interrupt) watchdog can interfere with VPP performance by
    * Range: ``2-5``
    * Mixed: ``1,3-5,7``
 
-   ..important:: 
+   .. important:: 
 
-      Always reserve at least 1-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.
+      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.