proc.5, proc_timer_stats.5: Split /proc/timer_stats from proc(5)

Signed-off-by: Alejandro Colomar <alx@kernel.org>

2 files changed, 117 insertions, 105 deletions

diff --git a/man5/proc.5 b/man5/proc.5
index f68bda52d..fa6d3c7c0 100644
--- a/man5/proc.5
+++ b/man5/proc.5
@@ -225,111 +225,6 @@ hierarchy.
 .\" FIXME Document /proc/sched_debug (since Linux 2.6.23)
 .\" See also /proc/[pid]/sched
 .TP
-.IR /proc/timer_stats " (from  Linux 2.6.21 until Linux 4.10)"
-.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221
-.\"	Date:   Fri Feb 16 01:28:13 2007 -0800
-.\" Text largely derived from Documentation/timers/timer_stats.txt
-.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1
-.\"     Date:   Wed Feb 8 11:26:59 2017 -0800
-This is a debugging facility to make timer (ab)use in a Linux
-system visible to kernel and user-space developers.
-It can be used by kernel and user-space developers to verify that
-their code does not make undue use of timers.
-The goal is to avoid unnecessary wakeups,
-thereby optimizing power consumption.
-.IP
-If enabled in the kernel
-.RB ( CONFIG_TIMER_STATS ),
-but not used,
-it has almost zero run-time overhead and a relatively small
-data-structure overhead.
-Even if collection is enabled at run time, overhead is low:
-all the locking is per-CPU and lookup is hashed.
-.IP
-The
-.I /proc/timer_stats
-file is used both to control sampling facility and to read out the
-sampled information.
-.IP
-The
-.I timer_stats
-functionality is inactive on bootup.
-A sampling period can be started using the following command:
-.IP
-.in +4n
-.EX
-# echo 1 > /proc/timer_stats
-.EE
-.in
-.IP
-The following command stops a sampling period:
-.IP
-.in +4n
-.EX
-# echo 0 > /proc/timer_stats
-.EE
-.in
-.IP
-The statistics can be retrieved by:
-.IP
-.in +4n
-.EX
-$ cat /proc/timer_stats
-.EE
-.in
-.IP
-While sampling is enabled, each readout from
-.I /proc/timer_stats
-will see
-newly updated statistics.
-Once sampling is disabled, the sampled information
-is kept until a new sample period is started.
-This allows multiple readouts.
-.IP
-Sample output from
-.IR /proc/timer_stats :
-.IP
-.in +4n
-.EX
-.RB $ " cat /proc/timer_stats"
-Timer Stats Version: v0.3
-Sample period: 1.764 s
-Collection: active
-  255,     0 swapper/3        hrtimer_start_range_ns (tick_sched_timer)
-   71,     0 swapper/1        hrtimer_start_range_ns (tick_sched_timer)
-   58,     0 swapper/0        hrtimer_start_range_ns (tick_sched_timer)
-    4,  1694 gnome\-shell      mod_delayed_work_on (delayed_work_timer_fn)
-   17,     7 rcu_sched        rcu_gp_kthread (process_timeout)
-\&...
-    1,  4911 kworker/u16:0    mod_delayed_work_on (delayed_work_timer_fn)
-   1D,  2522 kworker/0:0      queue_delayed_work_on (delayed_work_timer_fn)
-1029 total events, 583.333 events/sec
-.EE
-.in
-.IP
-The output columns are:
-.RS
-.IP [1] 5
-a count of the number of events,
-optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq]
-.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers
-if this is a deferrable timer;
-.IP [2]
-the PID of the process that initialized the timer;
-.IP [3]
-the name of the process that initialized the timer;
-.IP [4]
-the function where the timer was initialized; and
-(in parentheses)
-the callback function that is associated with the timer.
-.RE
-.IP
-During the Linux 4.11 development cycle,
-this file  was removed because of security concerns,
-as it exposes information across namespaces.
-Furthermore, it is possible to obtain
-the same information via in-kernel tracing facilities such as ftrace.
-.TP
 .I /proc/tty
 Subdirectory containing the pseudo-files and subdirectories for
 tty drivers and line disciplines.
diff --git a/man5/proc_timer_stats.5 b/man5/proc_timer_stats.5
new file mode 100644
index 000000000..0c9f45978
--- /dev/null
+++ b/man5/proc_timer_stats.5
@@ -0,0 +1,117 @@
+.\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
+.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\"
+.TH proc_timer_stats 5 (date) "Linux man-pages (unreleased)"
+.SH NAME
+/proc/timer_stats \- timer statistics
+.SH DESCRIPTION
+.TP
+.IR /proc/timer_stats " (from  Linux 2.6.21 until Linux 4.10)"
+.\" commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221
+.\"	Date:   Fri Feb 16 01:28:13 2007 -0800
+.\" Text largely derived from Documentation/timers/timer_stats.txt
+.\" removed in commit dfb4357da6ddbdf57d583ba64361c9d792b0e0b1
+.\"     Date:   Wed Feb 8 11:26:59 2017 -0800
+This is a debugging facility to make timer (ab)use in a Linux
+system visible to kernel and user-space developers.
+It can be used by kernel and user-space developers to verify that
+their code does not make undue use of timers.
+The goal is to avoid unnecessary wakeups,
+thereby optimizing power consumption.
+.IP
+If enabled in the kernel
+.RB ( CONFIG_TIMER_STATS ),
+but not used,
+it has almost zero run-time overhead and a relatively small
+data-structure overhead.
+Even if collection is enabled at run time, overhead is low:
+all the locking is per-CPU and lookup is hashed.
+.IP
+The
+.I /proc/timer_stats
+file is used both to control sampling facility and to read out the
+sampled information.
+.IP
+The
+.I timer_stats
+functionality is inactive on bootup.
+A sampling period can be started using the following command:
+.IP
+.in +4n
+.EX
+# echo 1 > /proc/timer_stats
+.EE
+.in
+.IP
+The following command stops a sampling period:
+.IP
+.in +4n
+.EX
+# echo 0 > /proc/timer_stats
+.EE
+.in
+.IP
+The statistics can be retrieved by:
+.IP
+.in +4n
+.EX
+$ cat /proc/timer_stats
+.EE
+.in
+.IP
+While sampling is enabled, each readout from
+.I /proc/timer_stats
+will see
+newly updated statistics.
+Once sampling is disabled, the sampled information
+is kept until a new sample period is started.
+This allows multiple readouts.
+.IP
+Sample output from
+.IR /proc/timer_stats :
+.IP
+.in +4n
+.EX
+.RB $ " cat /proc/timer_stats"
+Timer Stats Version: v0.3
+Sample period: 1.764 s
+Collection: active
+  255,     0 swapper/3        hrtimer_start_range_ns (tick_sched_timer)
+   71,     0 swapper/1        hrtimer_start_range_ns (tick_sched_timer)
+   58,     0 swapper/0        hrtimer_start_range_ns (tick_sched_timer)
+    4,  1694 gnome\-shell      mod_delayed_work_on (delayed_work_timer_fn)
+   17,     7 rcu_sched        rcu_gp_kthread (process_timeout)
+\&...
+    1,  4911 kworker/u16:0    mod_delayed_work_on (delayed_work_timer_fn)
+   1D,  2522 kworker/0:0      queue_delayed_work_on (delayed_work_timer_fn)
+1029 total events, 583.333 events/sec
+.EE
+.in
+.IP
+The output columns are:
+.RS
+.IP [1] 5
+a count of the number of events,
+optionally (since Linux 2.6.23) followed by the letter \[aq]D\[aq]
+.\" commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers
+if this is a deferrable timer;
+.IP [2]
+the PID of the process that initialized the timer;
+.IP [3]
+the name of the process that initialized the timer;
+.IP [4]
+the function where the timer was initialized; and
+(in parentheses)
+the callback function that is associated with the timer.
+.RE
+.IP
+During the Linux 4.11 development cycle,
+this file  was removed because of security concerns,
+as it exposes information across namespaces.
+Furthermore, it is possible to obtain
+the same information via in-kernel tracing facilities such as ftrace.
+.SH SEE ALSO
+.BR proc (5)