[Devel] [PATCH vz10 v2] tests: ve_printk: add documentation comments to test cases

[Konstantin Khorenko]

Add comprehensive documentation comments to ve_printk selftests to improve
code readability and maintainability:

- Add file-level header comment describing all test functions and test cases
- Add per-test comments explaining what each test verifies:
  * ve_log: verifies VE_LOG routing for segfault messages
  * ve0_log: verifies VE0_LOG routing for trap messages
  * ve_log_both: verifies VE_LOG_BOTH with ratelimit throttling
  * ve_printk_ratelimited: verifies VE_LOG ratelimit functionality
  * ve_printk_overflow: verifies log buffer overflow handling

The comments clarify the purpose of each test, what kernel functions they
exercise, and what behavior is being verified.

https://virtuozzo.atlassian.net/browse/VSTOR-114252

Signed-off-by: Konstantin Khorenko <khorenko at virtuozzo.com>
---
 .../selftests/ve_printk/ve_printk_test.c      | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/tools/testing/selftests/ve_printk/ve_printk_test.c b/tools/testing/selftests/ve_printk/ve_printk_test.c
index 78475ff71faa1..bb466531c39da 100644
--- a/tools/testing/selftests/ve_printk/ve_printk_test.c
+++ b/tools/testing/selftests/ve_printk/ve_printk_test.c
@@ -1,4 +1,25 @@
 // SPDX-License-Identifier: GPL-2.0
+/*
+ * ve_printk selftests
+ *
+ * This file contains tests for the VE printk virtualization feature. It verifies
+ * that kernel messages are correctly routed to containers (VE_LOG), host (VE0_LOG),
+ * or both (VE_LOG_BOTH), and that rate limiting works correctly.
+ *
+ * Test functions (executed inside containers):
+ *   - ve_printk_test_logct():     Verifies segfault messages are logged to container
+ *   - ve_printk_test_logve0():    Verifies trap messages are logged to VE0
+ *   - ve_printk_test_logboth():   Verifies net_veboth_ratelimited messages
+ *   - ve_printk_test_ratelimit(): Verifies ve_printk_ratelimited(VE_LOG) messages
+ *   - ve_printk_test_overflow():  Verifies log buffer overflow handling
+ *
+ * Test cases:
+ *   - TEST_F(ve_printk, ve_log):              Verifies VE_LOG routing (segfault)
+ *   - TEST_F(ve_printk, ve0_log):             Verifies VE0_LOG routing (trap)
+ *   - TEST_F(ve_printk, ve_log_both):         Verifies VE_LOG_BOTH + ratelimit
+ *   - TEST_F(ve_printk, ve_printk_ratelimited): Verifies VE_LOG ratelimit
+ *   - TEST_F(ve_printk, ve_printk_overflow):   Verifies buffer overflow handling
+ */
 #define _GNU_SOURCE
 #include <linux/sched.h>
 #include <time.h>
@@ -477,6 +498,12 @@ int set_param(const char *path, int val, int *old)
 	return restore_param(path, val);
 }
 
+/*
+ * Test verifies that segfault messages are logged only to the container (VE_LOG),
+ * not to VE0 (host). Inside the container, test_segf program is run which causes
+ * a segfault. The test verifies that there are NO segfault messages from this
+ * process on the host - they should be visible only inside the container.
+ */
 TEST_F(ve_printk, ve_log)
 {
 	int ret;
@@ -499,6 +526,13 @@ TEST_F(ve_printk, ve_log)
 	restore_param("/proc/sys/debug/exception-trace", old);
 }
 
+/*
+ * Test verifies that trap messages are logged to VE0 (host) via VE0_LOG.
+ * Inside the container, test_trap program is run which triggers int3 (breakpoint).
+ * The test verifies that there ARE trap messages from this process on the host -
+ * they should be visible in VE0, as some critical messages must be logged at
+ * the host level regardless of the container.
+ */
 TEST_F(ve_printk, ve0_log)
 {
 	int ret;
@@ -525,6 +559,15 @@ TEST_F(ve_printk, ve0_log)
 	ASSERT_EQ(ret, 1);
 }
 
+/*
+ * Test verifies net_veboth_ratelimited function which logs messages simultaneously
+ * to both the container (VE_LOG) and VE0 (VE0_LOG), but with ratelimit throttling.
+ * Inside the container, a small conntrack table (size 2) is configured, then many ping
+ * packets are sent, causing table overflow and generation of "nf_conntrack table full,
+ * dropping packet" messages. The test verifies that exactly TEST_RATELIMIT_BURST (10)
+ * messages appeared on the host - ratelimit should limit the number of messages even
+ * if more were generated.
+ */
 TEST_F(ve_printk, ve_log_both)
 {
 	int ret;
@@ -550,6 +593,14 @@ TEST_F(ve_printk, ve_log_both)
 	ASSERT_EQ(ret, TEST_RATELIMIT_BURST);
 }
 
+/*
+ * Test verifies ve_printk_ratelimited(VE_LOG) function which logs messages only
+ * to the container with ratelimit throttling. Inside the container, many invalid
+ * iptables rules are created (REJECT with tcp-reset for non-tcp), which generates
+ * warnings via ve_printk_ratelimited. The test verifies that there are NO such
+ * messages on the host (they should be visible only inside the container), and
+ * that ratelimit works correctly (messages are suppressed after exceeding the limit).
+ */
 TEST_F(ve_printk, ve_printk_ratelimited)
 {
 	int ret;
@@ -577,6 +628,13 @@ TEST_F(ve_printk, ve_printk_ratelimited)
 	restore_param("/proc/sys/net/core/message_cost", old_ratelimit);
 }
 
+/*
+ * Test verifies that when the container's log buffer overflows, messages are still
+ * handled correctly. Inside the container, 15 segfaults are triggered (enough to
+ * overflow the buffer), with a sleep after the 9th to bypass printk_ratelimit.
+ * The test verifies that even after buffer overflow, the logging mechanism continues
+ * to work properly and messages are still processed.
+ */
 TEST_F(ve_printk, ve_printk_overflow)
 {
 	int ret;
-- 
2.43.0