* [patch] update kernel documentation references in cgroups(7) and cpuset(7)
@ 2020-06-19 16:35 Sven Hoexter
2020-06-29 11:40 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 3+ messages in thread
From: Sven Hoexter @ 2020-06-19 16:35 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man
cgroups-v1/v2 documentation got moved to the "admin-guide" subfolder
and converted from .txt files to .rst
---
man7/cgroups.7 | 38 +++++++++++++++++++-------------------
man7/cpuset.7 | 2 +-
2 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/man7/cgroups.7 b/man7/cgroups.7
index 7a7210177..4b4afbbd7 100644
--- a/man7/cgroups.7
+++ b/man7/cgroups.7
@@ -76,7 +76,7 @@ with the result that many inconsistencies arose between controllers
and management of the cgroup hierarchies became rather complex.
(A longer description of these problems can be found in
the kernel source file
-.IR Documentation/cgroup\-v2.txt .)
+.IR Documentation/admin\-guide/cgroup\-v2.rst .)
.PP
Because of the problems with the initial cgroups implementation
(cgroups version 1),
@@ -264,7 +264,7 @@ Cgroups can be guaranteed a minimum number of "CPU shares"
when a system is busy.
This does not limit a cgroup's CPU usage if the CPUs are not busy.
For further information, see
-.IR Documentation/scheduler/sched-design-CFS.txt .
+.IR Documentation/scheduler/sched\-design\-CFS.rst .
.IP
In Linux 3.2,
this controller was extended to provide CPU "bandwidth" control.
@@ -275,27 +275,27 @@ then within each scheduling period
an upper limit on the CPU time allocated to the processes in a cgroup.
This upper limit applies even if there is no other competition for the CPU.
Further information can be found in the kernel source file
-.IR Documentation/scheduler/sched\-bwc.txt .
+.IR Documentation/scheduler/sched\-bwc.rst .
.TP
.IR cpuacct " (since Linux 2.6.24; " \fBCONFIG_CGROUP_CPUACCT\fP )
This provides accounting for CPU usage by groups of processes.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup\-v1/cpuacct.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/cpuacct.rst .
.TP
.IR cpuset " (since Linux 2.6.24; " \fBCONFIG_CPUSETS\fP )
This cgroup can be used to bind the processes in a cgroup to
a specified set of CPUs and NUMA nodes.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup\-v1/cpusets.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/cpusets.rst .
.TP
.IR memory " (since Linux 2.6.25; " \fBCONFIG_MEMCG\fP )
The memory controller supports reporting and limiting of process memory, kernel
memory, and swap used by cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup\-v1/memory.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/memory.rst .
.TP
.IR devices " (since Linux 2.6.26; " \fBCONFIG_CGROUP_DEVICE\fP )
This supports controlling which processes may create (mknod) devices as
@@ -305,7 +305,7 @@ Hierarchy is enforced, so new rules must not
violate existing rules for the target or ancestor cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/devices.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/devices.rst .
.TP
.IR freezer " (since Linux 2.6.28; " \fBCONFIG_CGROUP_FREEZER\fP )
The
@@ -318,7 +318,7 @@ also causes its children, for example, processes in
to be frozen.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/freezer-subsystem.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/freezer\-subsystem.rst .
.TP
.IR net_cls " (since Linux 2.6.29; " \fBCONFIG_CGROUP_NET_CLASSID\fP )
This places a classid, specified for the cgroup, on network packets
@@ -330,7 +330,7 @@ This applies only to packets
leaving the cgroup, not to traffic arriving at the cgroup.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/net_cls.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/net_cls.rst .
.TP
.IR blkio " (since Linux 2.6.33; " \fBCONFIG_BLK_CGROUP\fP )
The
@@ -347,41 +347,41 @@ The second is a throttling policy which specifies
upper I/O rate limits on a device.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/blkio-controller.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/blkio\-controller.rst .
.TP
.IR perf_event " (since Linux 2.6.39; " \fBCONFIG_CGROUP_PERF\fP )
This controller allows
.I perf
monitoring of the set of processes grouped in a cgroup.
.IP
-Further information can be found in the kernel source file
-.IR tools/perf/Documentation/perf-record.txt .
+Further information can be found in the kernel source files in
+.IR tools/perf/Documentation/admin\-guide/perf/ .
.TP
.IR net_prio " (since Linux 3.3; " \fBCONFIG_CGROUP_NET_PRIO\fP )
This allows priorities to be specified, per network interface, for cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/net_prio.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/net_prio.rst .
.TP
.IR hugetlb " (since Linux 3.5; " \fBCONFIG_CGROUP_HUGETLB\fP )
This supports limiting the use of huge pages by cgroups.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/hugetlb.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/hugetlb.rst .
.TP
.IR pids " (since Linux 4.3; " \fBCONFIG_CGROUP_PIDS\fP )
This controller permits limiting the number of process that may be created
in a cgroup (and its descendants).
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/pids.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/pids.rst .
.TP
.IR rdma " (since Linux 4.11; " \fBCONFIG_CGROUP_RDMA\fP )
The RDMA controller permits limiting the use of
RDMA/IB-specific resources per cgroup.
.IP
Further information can be found in the kernel source file
-.IR Documentation/cgroup-v1/rdma.txt .
+.IR Documentation/admin\-guide/cgroup\-v1/rdma.rst .
.\"
.SS Creating cgroups and moving processes
A cgroup filesystem initially contains a single root cgroup, '/',
@@ -566,7 +566,7 @@ An improved mechanism for notification of empty cgroups is provided by the
file.
.PP
For more changes, see the
-.I Documentation/cgroup-v2.txt
+.I Documentation/admin\-guide/cgroup\-v2.rst
file in the kernel source.
.PP
Some of the new behaviors listed above saw subsequent modification with
@@ -648,7 +648,7 @@ it is silently ignored in noninitial namespaces.
.\"
.SS Cgroups v2 controllers
The following controllers, documented in the kernel source file
-.IR Documentation/cgroup-v2.txt ,
+.IR Documentation/admin\-guide/cgroup\-v2.rst ,
are supported in cgroups version 2:
.TP
.IR cpu " (since Linux 4.15)"
@@ -1878,4 +1878,4 @@ mount option.
.BR user_namespaces (7)
.PP
The kernel source file
-.IR Documentation/admin-guide/cgroup-v2.rst .
+.IR Documentation/admin\-guide/cgroup\-v2.rst .
diff --git a/man7/cpuset.7 b/man7/cpuset.7
index 44e63d64f..fdfc3b662 100644
--- a/man7/cpuset.7
+++ b/man7/cpuset.7
@@ -1503,7 +1503,7 @@ syntax that works on any shell, but alas more obscurely, by using the
.BR migratepages (8),
.BR numactl (8)
.PP
-.IR Documentation/cgroup\-v1/cpusets.txt
+.IR Documentation/admin\-guide/cgroup\-v1/cpusets.rst
in the Linux kernel source tree
.\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8
(or
--
2.20.1
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [patch] update kernel documentation references in cgroups(7) and cpuset(7)
2020-06-19 16:35 [patch] update kernel documentation references in cgroups(7) and cpuset(7) Sven Hoexter
@ 2020-06-29 11:40 ` Michael Kerrisk (man-pages)
2020-06-29 12:07 ` Sven Hoexter
0 siblings, 1 reply; 3+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-29 11:40 UTC (permalink / raw)
To: Sven Hoexter; +Cc: linux-man
Hello Sven,
On Fri, 19 Jun 2020 at 18:35, Sven Hoexter <sven@stormbind.net> wrote:
>
> cgroups-v1/v2 documentation got moved to the "admin-guide" subfolder
> and converted from .txt files to .rst
Thanks for your patch and for the ping, and sorry I did not respond
earlier. I had not forgotten this patch, but I was still working out
what to do with it.
The general philosophy in man-pages is to maintain historical
information, since the man-pages that are installed on a system may
not correspond to the kernel running on that system. In the context of
your patch, what this means is that I would prefer to have text like:
[[
The kernel source file
.IR Documentation/admin\-guide/cgroup\-v2.rst
(or
.IR Documentation/admin-guide/cgroup-v2.rst in Linux x.y and earlier)
]]
Would you be willing to revise your patch to that style?
Thanks,
Michael
> ---
> man7/cgroups.7 | 38 +++++++++++++++++++-------------------
> man7/cpuset.7 | 2 +-
> 2 files changed, 20 insertions(+), 20 deletions(-)
>
> diff --git a/man7/cgroups.7 b/man7/cgroups.7
> index 7a7210177..4b4afbbd7 100644
> --- a/man7/cgroups.7
> +++ b/man7/cgroups.7
> @@ -76,7 +76,7 @@ with the result that many inconsistencies arose between controllers
> and management of the cgroup hierarchies became rather complex.
> (A longer description of these problems can be found in
> the kernel source file
> -.IR Documentation/cgroup\-v2.txt .)
> +.IR Documentation/admin\-guide/cgroup\-v2.rst .)
> .PP
> Because of the problems with the initial cgroups implementation
> (cgroups version 1),
> @@ -264,7 +264,7 @@ Cgroups can be guaranteed a minimum number of "CPU shares"
> when a system is busy.
> This does not limit a cgroup's CPU usage if the CPUs are not busy.
> For further information, see
> -.IR Documentation/scheduler/sched-design-CFS.txt .
> +.IR Documentation/scheduler/sched\-design\-CFS.rst .
> .IP
> In Linux 3.2,
> this controller was extended to provide CPU "bandwidth" control.
> @@ -275,27 +275,27 @@ then within each scheduling period
> an upper limit on the CPU time allocated to the processes in a cgroup.
> This upper limit applies even if there is no other competition for the CPU.
> Further information can be found in the kernel source file
> -.IR Documentation/scheduler/sched\-bwc.txt .
> +.IR Documentation/scheduler/sched\-bwc.rst .
> .TP
> .IR cpuacct " (since Linux 2.6.24; " \fBCONFIG_CGROUP_CPUACCT\fP )
> This provides accounting for CPU usage by groups of processes.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup\-v1/cpuacct.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/cpuacct.rst .
> .TP
> .IR cpuset " (since Linux 2.6.24; " \fBCONFIG_CPUSETS\fP )
> This cgroup can be used to bind the processes in a cgroup to
> a specified set of CPUs and NUMA nodes.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup\-v1/cpusets.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/cpusets.rst .
> .TP
> .IR memory " (since Linux 2.6.25; " \fBCONFIG_MEMCG\fP )
> The memory controller supports reporting and limiting of process memory, kernel
> memory, and swap used by cgroups.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup\-v1/memory.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/memory.rst .
> .TP
> .IR devices " (since Linux 2.6.26; " \fBCONFIG_CGROUP_DEVICE\fP )
> This supports controlling which processes may create (mknod) devices as
> @@ -305,7 +305,7 @@ Hierarchy is enforced, so new rules must not
> violate existing rules for the target or ancestor cgroups.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/devices.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/devices.rst .
> .TP
> .IR freezer " (since Linux 2.6.28; " \fBCONFIG_CGROUP_FREEZER\fP )
> The
> @@ -318,7 +318,7 @@ also causes its children, for example, processes in
> to be frozen.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/freezer-subsystem.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/freezer\-subsystem.rst .
> .TP
> .IR net_cls " (since Linux 2.6.29; " \fBCONFIG_CGROUP_NET_CLASSID\fP )
> This places a classid, specified for the cgroup, on network packets
> @@ -330,7 +330,7 @@ This applies only to packets
> leaving the cgroup, not to traffic arriving at the cgroup.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/net_cls.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/net_cls.rst .
> .TP
> .IR blkio " (since Linux 2.6.33; " \fBCONFIG_BLK_CGROUP\fP )
> The
> @@ -347,41 +347,41 @@ The second is a throttling policy which specifies
> upper I/O rate limits on a device.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/blkio-controller.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/blkio\-controller.rst .
> .TP
> .IR perf_event " (since Linux 2.6.39; " \fBCONFIG_CGROUP_PERF\fP )
> This controller allows
> .I perf
> monitoring of the set of processes grouped in a cgroup.
> .IP
> -Further information can be found in the kernel source file
> -.IR tools/perf/Documentation/perf-record.txt .
> +Further information can be found in the kernel source files in
> +.IR tools/perf/Documentation/admin\-guide/perf/ .
> .TP
> .IR net_prio " (since Linux 3.3; " \fBCONFIG_CGROUP_NET_PRIO\fP )
> This allows priorities to be specified, per network interface, for cgroups.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/net_prio.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/net_prio.rst .
> .TP
> .IR hugetlb " (since Linux 3.5; " \fBCONFIG_CGROUP_HUGETLB\fP )
> This supports limiting the use of huge pages by cgroups.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/hugetlb.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/hugetlb.rst .
> .TP
> .IR pids " (since Linux 4.3; " \fBCONFIG_CGROUP_PIDS\fP )
> This controller permits limiting the number of process that may be created
> in a cgroup (and its descendants).
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/pids.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/pids.rst .
> .TP
> .IR rdma " (since Linux 4.11; " \fBCONFIG_CGROUP_RDMA\fP )
> The RDMA controller permits limiting the use of
> RDMA/IB-specific resources per cgroup.
> .IP
> Further information can be found in the kernel source file
> -.IR Documentation/cgroup-v1/rdma.txt .
> +.IR Documentation/admin\-guide/cgroup\-v1/rdma.rst .
> .\"
> .SS Creating cgroups and moving processes
> A cgroup filesystem initially contains a single root cgroup, '/',
> @@ -566,7 +566,7 @@ An improved mechanism for notification of empty cgroups is provided by the
> file.
> .PP
> For more changes, see the
> -.I Documentation/cgroup-v2.txt
> +.I Documentation/admin\-guide/cgroup\-v2.rst
> file in the kernel source.
> .PP
> Some of the new behaviors listed above saw subsequent modification with
> @@ -648,7 +648,7 @@ it is silently ignored in noninitial namespaces.
> .\"
> .SS Cgroups v2 controllers
> The following controllers, documented in the kernel source file
> -.IR Documentation/cgroup-v2.txt ,
> +.IR Documentation/admin\-guide/cgroup\-v2.rst ,
> are supported in cgroups version 2:
> .TP
> .IR cpu " (since Linux 4.15)"
> @@ -1878,4 +1878,4 @@ mount option.
> .BR user_namespaces (7)
> .PP
> The kernel source file
> -.IR Documentation/admin-guide/cgroup-v2.rst .
> +.IR Documentation/admin\-guide/cgroup\-v2.rst .
> diff --git a/man7/cpuset.7 b/man7/cpuset.7
> index 44e63d64f..fdfc3b662 100644
> --- a/man7/cpuset.7
> +++ b/man7/cpuset.7
> @@ -1503,7 +1503,7 @@ syntax that works on any shell, but alas more obscurely, by using the
> .BR migratepages (8),
> .BR numactl (8)
> .PP
> -.IR Documentation/cgroup\-v1/cpusets.txt
> +.IR Documentation/admin\-guide/cgroup\-v1/cpusets.rst
> in the Linux kernel source tree
> .\" commit 45ce80fb6b6f9594d1396d44dd7e7c02d596fef8
> (or
> --
> 2.20.1
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [patch] update kernel documentation references in cgroups(7) and cpuset(7)
2020-06-29 11:40 ` Michael Kerrisk (man-pages)
@ 2020-06-29 12:07 ` Sven Hoexter
0 siblings, 0 replies; 3+ messages in thread
From: Sven Hoexter @ 2020-06-29 12:07 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: linux-man
On Mon, Jun 29, 2020 at 01:40:50PM +0200, Michael Kerrisk (man-pages) wrote:
> On Fri, 19 Jun 2020 at 18:35, Sven Hoexter <sven@stormbind.net> wrote:
Hi,
> > cgroups-v1/v2 documentation got moved to the "admin-guide" subfolder
> > and converted from .txt files to .rst
>
> Thanks for your patch and for the ping, and sorry I did not respond
> earlier. I had not forgotten this patch, but I was still working out
> what to do with it.
>
> The general philosophy in man-pages is to maintain historical
> information, since the man-pages that are installed on a system may
> not correspond to the kernel running on that system.
Indeed, a valid point I did not consider.
> In the context of
> your patch, what this means is that I would prefer to have text like:
>
> [[
> The kernel source file
> .IR Documentation/admin\-guide/cgroup\-v2.rst
> (or
> .IR Documentation/admin-guide/cgroup-v2.rst in Linux x.y and earlier)
> ]]
>
> Would you be willing to revise your patch to that style?
Sure, I will prepare a new version.
Regards,
Sven
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-06-29 20:46 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-19 16:35 [patch] update kernel documentation references in cgroups(7) and cpuset(7) Sven Hoexter
2020-06-29 11:40 ` Michael Kerrisk (man-pages)
2020-06-29 12:07 ` Sven Hoexter
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).