c21b080f3d
Under Linux to sched_[g|s]etaffinity() functions the value returned from a call to gettid(2) (thread id) can be passed in the argument pid. Specifying pid as 0 will set the attribute for the calling thread, and passing the value returned from a call to getpid(2) (process id) will set the attribute for the main thread of the thread group. Native cpuset(2) family of system calls has "which" argument to determine how the value of id argument is interpreted, i.e., CPU_WHICH_TID is used to pass a thread id and CPU_WHICH_PID - to pass a process id. For now native sched_[g|s]etaffinity() implementation is wrong as uses "which" CPU_WHICH_PID to pass both (process and thread id) to the kernel. To fix this adding a new "which" CPU_WHICH_TIDPID intended to handle both id's. Reviewed by: kib Differential Revision: https://reviews.freebsd.org/D38209 MFC after: 1 week
305 lines
8.8 KiB
Groff
305 lines
8.8 KiB
Groff
.\" Copyright (c) 2008 Christian Brueffer
|
|
.\" Copyright (c) 2008 Jeffrey Roberson
|
|
.\" Copyright (c) 2021 Robert N. M. Watson
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd January 29, 2023
|
|
.Dt CPUSET 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cpuset ,
|
|
.Nm cpuset_getid ,
|
|
.Nm cpuset_setid
|
|
.Nd manage CPU affinity sets
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/param.h
|
|
.In sys/cpuset.h
|
|
.Ft int
|
|
.Fn cpuset "cpusetid_t *setid"
|
|
.Ft int
|
|
.Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid"
|
|
.Ft int
|
|
.Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
family of system calls allow applications to control sets of processors and
|
|
memory domains and assign processes and threads to these sets.
|
|
Processor sets contain lists of CPUs and domains that members may run on
|
|
and exist only as long as some process is a member of the set.
|
|
All processes in the system have an assigned set.
|
|
The default set for all processes in the system is the set numbered 1.
|
|
Threads belong to the same set as the process which contains them,
|
|
however, they may further restrict their set with the anonymous
|
|
per-thread mask to bind to a specific CPU or subset of CPUs and memory domains.
|
|
.Pp
|
|
Sets are referenced by a number of type
|
|
.Ft cpuset_id_t .
|
|
Each thread has a root set, an assigned set, and an anonymous mask.
|
|
Only the root and assigned sets are numbered.
|
|
The root set is the set of all CPUs and memory domains available in the system
|
|
or in the system partition the thread is running in.
|
|
The assigned set is a subset of the root set and is administratively
|
|
assignable on a per-process basis.
|
|
Many processes and threads may be members of a numbered set.
|
|
.Pp
|
|
The anonymous set is a further thread-specific refinement on the assigned
|
|
set.
|
|
It is intended that administrators will manipulate numbered sets using
|
|
.Xr cpuset 1
|
|
while application developers will manipulate anonymous sets using
|
|
.Xr cpuset_setaffinity 2 and
|
|
.Xr cpuset_setdomain 2 .
|
|
.Pp
|
|
To select the correct set a value of type
|
|
.Ft cpulevel_t
|
|
is used.
|
|
The following values for
|
|
.Fa level
|
|
are supported:
|
|
.Bl -column CPU_LEVEL_CPUSET -offset indent
|
|
.It Dv CPU_LEVEL_ROOT Ta "Root set"
|
|
.It Dv CPU_LEVEL_CPUSET Ta "Assigned set"
|
|
.It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument"
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa which
|
|
argument determines how the value of
|
|
.Fa id
|
|
is interpreted and is of type
|
|
.Ft cpuwhich_t .
|
|
The
|
|
.Fa which
|
|
argument may have the following values:
|
|
.Bl -column CPU_WHICH_INTRHANDLER -offset indent
|
|
.It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)"
|
|
.It Dv CPU_WHICH_PID Ta "id is pid_t (process id)"
|
|
.It Dv CPU_WHICH_TIDPID Ta "id is either a thread or process id"
|
|
.It Dv CPU_WHICH_JAIL Ta "id is jid (jail id)"
|
|
.It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)"
|
|
.It Dv CPU_WHICH_IRQ Ta "id is an irq number"
|
|
.It Dv CPU_WHICH_INTRHANDLER Ta "id is an irq number for an interrupt handler"
|
|
.It Dv CPU_WHICH_ITHREAD Ta "id is an irq number for an ithread"
|
|
.It Dv CPU_WHICH_DOMAIN Ta "id is a NUMA domain"
|
|
.El
|
|
.Pp
|
|
An
|
|
.Fa id
|
|
of '-1' may be used with a
|
|
.Fa which
|
|
of
|
|
.Dv CPU_WHICH_TID ,
|
|
.Dv CPU_WHICH_PID ,
|
|
.Dv CPU_WHICH_TIDPID ,
|
|
or
|
|
.Dv CPU_WHICH_CPUSET
|
|
to mean the current thread, process, or current thread's
|
|
cpuset.
|
|
All cpuset syscalls allow this usage.
|
|
.Pp
|
|
A
|
|
.Fa level
|
|
argument of
|
|
.Dv CPU_LEVEL_WHICH
|
|
combined with a
|
|
.Fa which
|
|
argument other than
|
|
.Dv CPU_WHICH_CPUSET
|
|
refers to the anonymous mask of the object.
|
|
This mask does not have an id and may only be manipulated with
|
|
.Xr cpuset_setaffinity 2 .
|
|
.Pp
|
|
.Fn cpuset
|
|
creates a new set containing the same CPUs as the root set of the current
|
|
process and stores its id in the space provided by
|
|
.Fa setid .
|
|
On successful completion the calling process joins the set and is the
|
|
only member.
|
|
Children inherit this set after a call to
|
|
.Xr fork 2 .
|
|
.Pp
|
|
.Fn cpuset_setid
|
|
attempts to set the id of the object specified by the
|
|
.Fa which
|
|
argument.
|
|
Currently
|
|
.Dv CPU_WHICH_PID
|
|
is the only acceptable value for which as
|
|
threads do not have an id distinct from their process and the API does
|
|
not permit changing the id of an existing set.
|
|
Upon successful completion all of the threads in the target process will
|
|
be running on CPUs permitted by the set.
|
|
.Pp
|
|
.Fn cpuset_getid
|
|
retrieves a set id from the object indicated by
|
|
.Fa which
|
|
and stores it in the space pointed to by
|
|
.Fa setid .
|
|
The retrieved id may be that of either the root or assigned set
|
|
depending on the value of
|
|
.Fa level .
|
|
.Fa level
|
|
should be
|
|
.Dv CPU_LEVEL_CPUSET
|
|
or
|
|
.Dv CPU_LEVEL_ROOT
|
|
to get the set id from
|
|
the process or thread specified by the
|
|
.Fa id
|
|
argument.
|
|
Specifying
|
|
.Dv CPU_LEVEL_WHICH
|
|
with a process or thread is unsupported since
|
|
this references the unnumbered anonymous mask.
|
|
.Pp
|
|
The actual contents of the sets may be retrieved or manipulated using
|
|
.Xr cpuset_getaffinity 2 ,
|
|
.Xr cpuset_setaffinity 2 ,
|
|
.Xr cpuset_getdomain 2 , and
|
|
.Xr cpuset_setdomain 2 .
|
|
The
|
|
.Xr cpuset 9
|
|
macros may be used to manipulate masks of type
|
|
.Ft cpuset_t
|
|
get and set using those APIs.
|
|
See those manual pages for more detail.
|
|
.Sh RETURN VALUES
|
|
.Rv -std
|
|
.Sh EXAMPLES
|
|
In this example, a CPU set mask is configured to limit execution to the first
|
|
CPU using
|
|
.Xr CPU_ZERO 9
|
|
and
|
|
.Xr CPU_SET 9 ,
|
|
members of the
|
|
.Xr cpuset 9
|
|
programming interface.
|
|
Then, the mask is applied to a new anonymous CPU set associated with the
|
|
current process using
|
|
.Xr cpuset_setaffinity 2 .
|
|
This mask will be used by the current process, and inherited by any new
|
|
child processes.
|
|
.Bd -literal -offset indent
|
|
#include <sys/param.h>
|
|
#include <sys/cpuset.h>
|
|
|
|
#include <sysexits.h>
|
|
|
|
cpuset_t cpuset_mask;
|
|
|
|
/* Initialize a CPU mask and enable CPU 0. */
|
|
CPU_ZERO(&cpuset_mask);
|
|
CPU_SET(0, &cpuset_mask);
|
|
|
|
/* Set affinity for the CPU set for the current process. */
|
|
if (cpuset_setaffinity(CPU_LEVEL_WHICH, CPU_WHICH_PID, -1,
|
|
sizeof(cpuset_mask), &cpuset_mask) < 0)
|
|
err(EX_OSERR, "cpuset_setaffinity");
|
|
.Ed
|
|
.Pp
|
|
In the next example, a named CPU set is created containing the current
|
|
process, and its affinity similarly configured.
|
|
The resulting CPU set ID can then be used for further external management of
|
|
the affinity of the set.
|
|
.Bd -literal -offset indent
|
|
#include <sys/param.h>
|
|
#include <sys/cpuset.h>
|
|
|
|
#include <sysexits.h>
|
|
|
|
cpusetid_t cpuset_id;
|
|
cpuset_t cpuset_mask;
|
|
|
|
/* Create new cpuset for the current process. */
|
|
if (cpuset(&cpuset_id) < 0)
|
|
err(EX_OSERR, "cpuset");
|
|
|
|
/* Initialize a CPU mask and enable CPU 0. */
|
|
CPU_ZERO(&cpuset_mask);
|
|
CPU_SET(0, &cpuset_mask);
|
|
|
|
/* Set affinity for the CPU set for the current process. */
|
|
if (cpuset_setaffinity(CPU_LEVEL_SET, CPU_WHICH_CPUSET, cpuset_id,
|
|
sizeof(cpuset_mask), &cpuset_mask) < 0)
|
|
err(EX_OSERR, "cpuset_setaffinity");
|
|
.Ed
|
|
.Sh ERRORS
|
|
The following error codes may be set in
|
|
.Va errno :
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The
|
|
.Fa which
|
|
or
|
|
.Fa level
|
|
argument was not a valid value.
|
|
.It Bq Er EDEADLK
|
|
The
|
|
.Fn cpuset_setid
|
|
call would leave a thread without a valid CPU to run on because the set
|
|
does not overlap with the thread's anonymous mask.
|
|
.It Bq Er EFAULT
|
|
The setid pointer passed to
|
|
.Fn cpuset_getid
|
|
or
|
|
.Fn cpuset
|
|
was invalid.
|
|
.It Bq Er ESRCH
|
|
The object specified by the
|
|
.Fa id
|
|
and
|
|
.Fa which
|
|
arguments could not be found.
|
|
.It Bq Er EPERM
|
|
The calling process did not have the credentials required to complete the
|
|
operation.
|
|
.It Bq Er ENFILE
|
|
There was no free
|
|
.Ft cpusetid_t
|
|
for allocation.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr cpuset 1 ,
|
|
.Xr cpuset_getaffinity 2 ,
|
|
.Xr cpuset_getdomain 2 ,
|
|
.Xr cpuset_setaffinity 2 ,
|
|
.Xr cpuset_setdomain 2 ,
|
|
.Xr pthread_affinity_np 3 ,
|
|
.Xr pthread_attr_affinity_np 3 ,
|
|
.Xr CPU_SET 9 ,
|
|
.Xr CPU_ZERO 9 ,
|
|
.Xr cpuset 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
family of system calls first appeared in
|
|
.Fx 7.1 .
|
|
.Sh AUTHORS
|
|
.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org
|