Merging upstream version 6.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 117 insertions, 0 deletions

diff --git a/man5/proc_timer_stats.5 b/man5/proc_timer_stats.5
new file mode 100644
index 0000000..3503f11
--- /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 2023-08-15 "Linux man-pages 6.7"
+.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)