tunable: Convert docs to docparse

* update outdated documentation
* use passive form
* use links to man (as :man2:`mmap`) and to kernel doc
  (:kernel_doc:`admin-guide/sysctl/vm`)

Signed-off-by: Petr Vorel <pvorel@suse.cz>

Author: pevik

testcases/kernel/mem/tunable/max_map_count.c

@@ -1,43 +1,43 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
 /*
+ * Copyright (c) Linux Test Project, 2012-2025
  * Copyright (C) 2012-2017  Red Hat, Inc.
+ */
+
+/*\
+ * Test ``/proc/sys/vm/max_map_count`` tunable file.
  *
- * This program is free software;  you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY;  without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
- * the GNU General Public License for more details.
- *
- * Description:
- *
- * The program is designed to test max_map_count tunable file
+ * :kernel_doc:`admin-guide/sysctl/vm` claims:
  *
- * The kernel Documentation say that:
- * /proc/sys/vm/max_map_count contains the maximum number of memory map
- * areas a process may have. Memory map areas are used as a side-effect
- * of calling malloc, directly by mmap and mprotect, and also when
- * loading shared libraries.
+ *    /proc/sys/vm/max_map_count contains the maximum number of memory map
+ *    areas a process may have. Memory map areas are used as a side-effect
+ *    of calling malloc, directly by mmap and mprotect, and also when
+ *    loading shared libraries.
  *
  * Each process has his own maps file: /proc/[pid]/maps, and each line
  * indicates a map entry, so it can caculate the amount of maps by reading
  * the file lines' number to check the tunable performance.
  *
- * The program tries to invoke mmap() endlessly until it triggers MAP_FAILED,
- * then reads the process's maps file /proc/[pid]/maps, save the line number to
- * map_count variable, and compare it with /proc/sys/vm/max_map_count,
- * map_count should be greater than max_map_count by 1;
+ * The program tries to invoke :man2:`mmap` endlessly until it triggers
+ * ``MAP_FAILED``, then reads the process's maps file /proc/[pid]/maps, save
+ * the line number to map_count variable, and compare it with
+ * ``/proc/sys/vm/max_map_count``, map_count should be greater than
+ * max_map_count by 1.
  *
- * Note: On some architectures there is a special vma VSYSCALL, which
+ * NOTE: On some architectures there is a special vma VSYSCALL, which
  * is allocated without incrementing mm->map_count variable. On these
  * architectures each /proc/<pid>/maps has at the end:
- * ...
- * ...
- * ffffffffff600000-ffffffffff601000 r-xp 00000000 00:00 0   [vsyscall]
  *
- * so we ignore this line during /proc/[pid]/maps reading.
+ * ::
+ *
+ *    ...
+ *    ffffffffff600000-ffffffffff601000 r-xp 00000000 00:00 0   [vsyscall]
+ *
+ * Therefore this line is ignored during /proc/[pid]/maps reading.
+ *
+ * [References]
+ *
+ * - :kernel_doc:`admin-guide/sysctl/vm`
  */
 
 #define _GNU_SOURCE

testcases/kernel/mem/tunable/min_free_kbytes.c

@@ -1,31 +1,27 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
 /*
+ * Copyright (c) Linux Test Project, 2012-2025
  * Copyright (C) 2012-2017  Red Hat, Inc.
- *
- * This program is free software;  you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY;  without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
- * the GNU General Public License for more details.
- *
- * Description:
- *
- * The case is designed to test min_free_kbytes tunable.
+ */
+
+/*\
+ * Test ``/proc/sys/vm/min_free_kbytes`` tunable file.
  *
  * The tune is used to control free memory, and system always
- * reserve min_free_kbytes memory at least.
+ * reserve ``min_free_kbytes`` memory at least.
  *
  * Since the tune is not too large or too little, which will
- * lead to the system hang, so I choose two cases, and test them
- * on all overcommit_memory policy, at the same time, compare
+ * lead to the system hang, the following cases are tested
+ * on all ``overcommit_memory`` policy, at the same time, compare
  * the current free memory with the tunable value repeatedly.
  *
- * a) default min_free_kbytes with all overcommit memory policy
- * b) 2x default value with all overcommit memory policy
- * c) 5% of MemFree or %2 MemTotal with all overcommit memory policy
+ * 1. default min_free_kbytes with all ``overcommit_memory`` policy
+ * 2. 2x default value with all ``overcommit_memory`` policy
+ * 3. 5% of MemFree or %2 MemTotal with all ``overcommit_memory`` policy
+ *
+ * [References]
+ *
+ * - :kernel_doc:`admin-guide/sysctl/vm`
  */
 
 #include <sys/wait.h>

testcases/kernel/mem/tunable/overcommit_memory.c

@@ -1,13 +1,18 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 /*
- * Copyright (c) 2012-2023 Linux Test Project
+ * Copyright (c) 2012-2025 Linux Test Project
  * Copyright (c) 2012-2017 Red Hat, Inc.
+ */
+
+/*\
+ * Test for ``overcommit_memory`` and ``overcommit_ratio`` tunables.
  *
  * There are two tunables overcommit_memory and overcommit_ratio under
  * /proc/sys/vm/, which can control memory overcommitment.
  *
  * The overcommit_memory contains a flag that enables memory
  * overcommitment, it has three values:
+ *
  * - When this flag is 0, the kernel attempts to estimate the amount
  *   of free memory left when userspace requests more memory.
  * - When this flag is 1, the kernel pretends there is always enough
@@ -21,41 +26,49 @@
  * percentage added to the amount of actual RAM in a system when
  * considering whether to grant a particular memory request.
  * The general formula for this tunable is:
- * CommitLimit = SwapTotal + MemTotal * overcommit_ratio
- * CommitLimit, SwapTotal and MemTotal can read from /proc/meminfo.
+ *
+ * * CommitLimit = SwapTotal + MemTotal * overcommit_ratio
+ * * CommitLimit, SwapTotal and MemTotal can read from /proc/meminfo.
  *
  * The program is designed to test the two tunables:
  *
  * When overcommit_memory = 0, allocatable memory can't overextend
  * the amount of total memory:
- * a. less than free_total:    free_total / 2, alloc should pass.
- * b. greater than sum_total:   sum_total * 2, alloc should fail.
+ *
+ * 1. less than free_total:    free_total / 2, alloc should pass.
+ * 2. greater than sum_total:   sum_total * 2, alloc should fail.
  *
  * When overcommit_memory = 1, it can alloc enough much memory, I
  * choose the three cases:
- * a. less than sum_total:    sum_total / 2, alloc should pass
- * b. equal to sum_total:     sum_total,     alloc should pass
- * c. greater than sum_total: sum_total * 2, alloc should pass
- * *note: sum_total = SwapTotal + MemTotal
+ *
+ * 1. less than sum_total:    sum_total / 2, alloc should pass
+ * 2. equal to sum_total:     sum_total,     alloc should pass
+ * 3. greater than sum_total: sum_total * 2, alloc should pass
+ *
+ * NOTE: sum_total = SwapTotal + MemTotal
  *
  * When overcommit_memory = 2, the total virtual address space on
  * the system is limited to CommitLimit(Swap+RAM*overcommit_ratio)
  * commit_left(allocatable memory) = CommitLimit - Committed_AS
- * a. less than commit_left:    commit_left / 2, alloc should pass
- * b. overcommit limit:         CommitLimit + TotalBatchSize, should fail
- * c. greater than commit_left: commit_left * 2, alloc should fail
- * *note: CommitLimit is the current overcommit limit.
- *        Committed_AS is the amount of memory that system has used.
- * it couldn't choose 'equal to commit_left' as a case, because
- * commit_left rely on Committed_AS, but the Committed_AS is not stable.
- * *note2: TotalBatchSize is the total number of bytes, that can be
- *         accounted for in the per cpu counters for the vm_committed_as
- *         counter. Since the check used by malloc only looks at the
- *         global counter of vm_committed_as, it can overallocate a bit.
  *
- * References:
- * - Documentation/sysctl/vm.txt
- * - Documentation/vm/overcommit-accounting
+ * 1. less than commit_left:    commit_left / 2, alloc should pass
+ * 2. overcommit limit:         CommitLimit + TotalBatchSize, should fail
+ * 3. greater than commit_left: commit_left * 2, alloc should fail
+ *
+ * NOTE: CommitLimit is the current overcommit limit.
+ * Committed_AS is the amount of memory that system has used.
+ *
+ * It couldn't choose 'equal to commit_left' as a case, because commit_left rely
+ * on Committed_AS, but the Committed_AS is not stable.
+ *
+ * NOTE: TotalBatchSize is the total number of bytes, that can be accounted for
+ * in the per cpu counters for the vm_committed_as counter. Since the check used
+ * by malloc only looks at the global counter of vm_committed_as, it can
+ * overallocate a bit.
+ *
+ * [References]
+ *
+ * - :kernel_doc:`admin-guide/sysctl/vm`
  */
 
 #include <errno.h>