Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 427 insertions, 0 deletions

diff --git a/upstream/fedora-rawhide/man2/sched_setaffinity.2 b/upstream/fedora-rawhide/man2/sched_setaffinity.2
new file mode 100644
index 00000000..d7455b34
--- /dev/null
+++ b/upstream/fedora-rawhide/man2/sched_setaffinity.2
@@ -0,0 +1,427 @@
+.\" Copyright (C) 2002 Robert Love
+.\" and Copyright (C) 2006, 2015 Michael Kerrisk
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" 2002-11-19 Robert Love <rml@tech9.net> - initial version
+.\" 2004-04-20 mtk - fixed description of return value
+.\" 2004-04-22 aeb - added glibc prototype history
+.\" 2005-05-03 mtk - noted that sched_setaffinity may cause thread
+.\"	migration and that CPU affinity is a per-thread attribute.
+.\" 2006-02-03 mtk -- Major rewrite
+.\" 2008-11-12, mtk, removed CPU_*() macro descriptions to a
+.\" separate CPU_SET(3) page.
+.\"
+.TH sched_setaffinity 2 2023-10-31 "Linux man-pages 6.06"
+.SH NAME
+sched_setaffinity, sched_getaffinity \- \
+set and get a thread's CPU affinity mask
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
+.B #include <sched.h>
+.P
+.BI "int sched_setaffinity(pid_t " pid ", size_t " cpusetsize ,
+.BI "                      const cpu_set_t *" mask );
+.BI "int sched_getaffinity(pid_t " pid ", size_t " cpusetsize ,
+.BI "                      cpu_set_t *" mask );
+.fi
+.SH DESCRIPTION
+A thread's CPU affinity mask determines the set of CPUs on which
+it is eligible to run.
+On a multiprocessor system, setting the CPU affinity mask
+can be used to obtain performance benefits.
+For example,
+by dedicating one CPU to a particular thread
+(i.e., setting the affinity mask of that thread to specify a single CPU,
+and setting the affinity mask of all other threads to exclude that CPU),
+it is possible to ensure maximum execution speed for that thread.
+Restricting a thread to run on a single CPU also avoids
+the performance cost caused by the cache invalidation that occurs
+when a thread ceases to execute on one CPU and then
+recommences execution on a different CPU.
+.P
+A CPU affinity mask is represented by the
+.I cpu_set_t
+structure, a "CPU set", pointed to by
+.IR mask .
+A set of macros for manipulating CPU sets is described in
+.BR CPU_SET (3).
+.P
+.BR sched_setaffinity ()
+sets the CPU affinity mask of the thread whose ID is
+.I pid
+to the value specified by
+.IR mask .
+If
+.I pid
+is zero, then the calling thread is used.
+The argument
+.I cpusetsize
+is the length (in bytes) of the data pointed to by
+.IR mask .
+Normally this argument would be specified as
+.IR "sizeof(cpu_set_t)" .
+.P
+If the thread specified by
+.I pid
+is not currently running on one of the CPUs specified in
+.IR mask ,
+then that thread is migrated to one of the CPUs specified in
+.IR mask .
+.P
+.BR sched_getaffinity ()
+writes the affinity mask of the thread whose ID is
+.I pid
+into the
+.I cpu_set_t
+structure pointed to by
+.IR mask .
+The
+.I cpusetsize
+argument specifies the size (in bytes) of
+.IR mask .
+If
+.I pid
+is zero, then the mask of the calling thread is returned.
+.SH RETURN VALUE
+On success,
+.BR sched_setaffinity ()
+and
+.BR sched_getaffinity ()
+return 0 (but see "C library/kernel differences" below,
+which notes that the underlying
+.BR sched_getaffinity ()
+differs in its return value).
+On failure, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+A supplied memory address was invalid.
+.TP
+.B EINVAL
+The affinity bit mask
+.I mask
+contains no processors that are currently physically on the system
+and permitted to the thread according to any restrictions that
+may be imposed by
+.I cpuset
+cgroups or the "cpuset" mechanism described in
+.BR cpuset (7).
+.TP
+.B EINVAL
+.RB ( sched_getaffinity ()
+and, before Linux 2.6.9,
+.BR sched_setaffinity ())
+.I cpusetsize
+is smaller than the size of the affinity mask used by the kernel.
+.TP
+.B EPERM
+.RB ( sched_setaffinity ())
+The calling thread does not have appropriate privileges.
+The caller needs an effective user ID equal to the real user ID
+or effective user ID of the thread identified by
+.IR pid ,
+or it must possess the
+.B CAP_SYS_NICE
+capability in the user namespace of the thread
+.IR pid .
+.TP
+.B ESRCH
+The thread whose ID is \fIpid\fP could not be found.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.5.8,
+glibc 2.3.
+.P
+Initially, the glibc interfaces included a
+.I cpusetsize
+argument, typed as
+.IR "unsigned int" .
+In glibc 2.3.3, the
+.I cpusetsize
+argument was removed, but was then restored in glibc 2.3.4, with type
+.IR size_t .
+.SH NOTES
+After a call to
+.BR sched_setaffinity (),
+the set of CPUs on which the thread will actually run is
+the intersection of the set specified in the
+.I mask
+argument and the set of CPUs actually present on the system.
+The system may further restrict the set of CPUs on which the thread
+runs if the "cpuset" mechanism described in
+.BR cpuset (7)
+is being used.
+These restrictions on the actual set of CPUs on which the thread
+will run are silently imposed by the kernel.
+.P
+There are various ways of determining the number of CPUs
+available on the system, including: inspecting the contents of
+.IR /proc/cpuinfo ;
+using
+.BR sysconf (3)
+to obtain the values of the
+.B _SC_NPROCESSORS_CONF
+and
+.B _SC_NPROCESSORS_ONLN
+parameters; and inspecting the list of CPU directories under
+.IR /sys/devices/system/cpu/ .
+.P
+.BR sched (7)
+has a description of the Linux scheduling scheme.
+.P
+The affinity mask is a per-thread attribute that can be
+adjusted independently for each of the threads in a thread group.
+The value returned from a call to
+.BR gettid (2)
+can be passed in the argument
+.IR pid .
+Specifying
+.I pid
+as 0 will set the attribute for the calling thread,
+and passing the value returned from a call to
+.BR getpid (2)
+will set the attribute for the main thread of the thread group.
+(If you are using the POSIX threads API, then use
+.BR pthread_setaffinity_np (3)
+instead of
+.BR sched_setaffinity ().)
+.P
+The
+.I isolcpus
+boot option can be used to isolate one or more CPUs at boot time,
+so that no processes are scheduled onto those CPUs.
+Following the use of this boot option,
+the only way to schedule processes onto the isolated CPUs is via
+.BR sched_setaffinity ()
+or the
+.BR cpuset (7)
+mechanism.
+For further information, see the kernel source file
+.IR Documentation/admin\-guide/kernel\-parameters.txt .
+As noted in that file,
+.I isolcpus
+is the preferred mechanism of isolating CPUs
+(versus the alternative of manually setting the CPU affinity
+of all processes on the system).
+.P
+A child created via
+.BR fork (2)
+inherits its parent's CPU affinity mask.
+The affinity mask is preserved across an
+.BR execve (2).
+.SS C library/kernel differences
+This manual page describes the glibc interface for the CPU affinity calls.
+The actual system call interface is slightly different, with the
+.I mask
+being typed as
+.IR "unsigned long\ *" ,
+reflecting the fact that the underlying implementation of CPU
+sets is a simple bit mask.
+.P
+On success, the raw
+.BR sched_getaffinity ()
+system call returns the number of bytes placed copied into the
+.I mask
+buffer;
+this will be the minimum of
+.I cpusetsize
+and the size (in bytes) of the
+.I cpumask_t
+data type that is used internally by the kernel to
+represent the CPU set bit mask.
+.SS Handling systems with large CPU affinity masks
+The underlying system calls (which represent CPU masks as bit masks of type
+.IR "unsigned long\ *" )
+impose no restriction on the size of the CPU mask.
+However, the
+.I cpu_set_t
+data type used by glibc has a fixed size of 128 bytes,
+meaning that the maximum CPU number that can be represented is 1023.
+.\" FIXME . See https://sourceware.org/bugzilla/show_bug.cgi?id=15630
+.\" and https://sourceware.org/ml/libc-alpha/2013-07/msg00288.html
+If the kernel CPU affinity mask is larger than 1024,
+then calls of the form:
+.P
+.in +4n
+.EX
+sched_getaffinity(pid, sizeof(cpu_set_t), &mask);
+.EE
+.in
+.P
+fail with the error
+.BR EINVAL ,
+the error produced by the underlying system call for the case where the
+.I mask
+size specified in
+.I cpusetsize
+is smaller than the size of the affinity mask used by the kernel.
+(Depending on the system CPU topology, the kernel affinity mask can
+be substantially larger than the number of active CPUs in the system.)
+.P
+When working on systems with large kernel CPU affinity masks,
+one must dynamically allocate the
+.I mask
+argument (see
+.BR CPU_ALLOC (3)).
+Currently, the only way to do this is by probing for the size
+of the required mask using
+.BR sched_getaffinity ()
+calls with increasing mask sizes (until the call does not fail with the error
+.BR EINVAL ).
+.P
+Be aware that
+.BR CPU_ALLOC (3)
+may allocate a slightly larger CPU set than requested
+(because CPU sets are implemented as bit masks allocated in units of
+.IR sizeof(long) ).
+Consequently,
+.BR sched_getaffinity ()
+can set bits beyond the requested allocation size, because the kernel
+sees a few additional bits.
+Therefore, the caller should iterate over the bits in the returned set,
+counting those which are set, and stop upon reaching the value returned by
+.BR CPU_COUNT (3)
+(rather than iterating over the number of bits
+requested to be allocated).
+.SH EXAMPLES
+The program below creates a child process.
+The parent and child then each assign themselves to a specified CPU
+and execute identical loops that consume some CPU time.
+Before terminating, the parent waits for the child to complete.
+The program takes three command-line arguments:
+the CPU number for the parent,
+the CPU number for the child,
+and the number of loop iterations that both processes should perform.
+.P
+As the sample runs below demonstrate, the amount of real and CPU time
+consumed when running the program will depend on intra-core caching effects
+and whether the processes are using the same CPU.
+.P
+We first employ
+.BR lscpu (1)
+to determine that this (x86)
+system has two cores, each with two CPUs:
+.P
+.in +4n
+.EX
+$ \fBlscpu | egrep \-i \[aq]core.*:|socket\[aq]\fP
+Thread(s) per core:    2
+Core(s) per socket:    2
+Socket(s):             1
+.EE
+.in
+.P
+We then time the operation of the example program for three cases:
+both processes running on the same CPU;
+both processes running on different CPUs on the same core;
+and both processes running on different CPUs on different cores.
+.P
+.in +4n
+.EX
+$ \fBtime \-p ./a.out 0 0 100000000\fP
+real 14.75
+user 3.02
+sys 11.73
+$ \fBtime \-p ./a.out 0 1 100000000\fP
+real 11.52
+user 3.98
+sys 19.06
+$ \fBtime \-p ./a.out 0 3 100000000\fP
+real 7.89
+user 3.29
+sys 12.07
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (sched_setaffinity.c)
+.EX
+#define _GNU_SOURCE
+#include <err.h>
+#include <sched.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/wait.h>
+#include <unistd.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    int           parentCPU, childCPU;
+    cpu_set_t     set;
+    unsigned int  nloops;
+\&
+    if (argc != 4) {
+        fprintf(stderr, "Usage: %s parent\-cpu child\-cpu num\-loops\en",
+                argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    parentCPU = atoi(argv[1]);
+    childCPU = atoi(argv[2]);
+    nloops = atoi(argv[3]);
+\&
+    CPU_ZERO(&set);
+\&
+    switch (fork()) {
+    case \-1:            /* Error */
+        err(EXIT_FAILURE, "fork");
+\&
+    case 0:             /* Child */
+        CPU_SET(childCPU, &set);
+\&
+        if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1)
+            err(EXIT_FAILURE, "sched_setaffinity");
+\&
+        for (unsigned int j = 0; j < nloops; j++)
+            getppid();
+\&
+        exit(EXIT_SUCCESS);
+\&
+    default:            /* Parent */
+        CPU_SET(parentCPU, &set);
+\&
+        if (sched_setaffinity(getpid(), sizeof(set), &set) == \-1)
+            err(EXIT_FAILURE, "sched_setaffinity");
+\&
+        for (unsigned int j = 0; j < nloops; j++)
+            getppid();
+\&
+        wait(NULL);     /* Wait for child to terminate */
+        exit(EXIT_SUCCESS);
+    }
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.ad l
+.nh
+.BR lscpu (1),
+.BR nproc (1),
+.BR taskset (1),
+.BR clone (2),
+.BR getcpu (2),
+.BR getpriority (2),
+.BR gettid (2),
+.BR nice (2),
+.BR sched_get_priority_max (2),
+.BR sched_get_priority_min (2),
+.BR sched_getscheduler (2),
+.BR sched_setscheduler (2),
+.BR setpriority (2),
+.BR CPU_SET (3),
+.BR get_nprocs (3),
+.BR pthread_setaffinity_np (3),
+.BR sched_getcpu (3),
+.BR capabilities (7),
+.BR cpuset (7),
+.BR sched (7),
+.BR numactl (8)