diff options
Diffstat (limited to 'static/freebsd/man2/cpuset.2')
| -rw-r--r-- | static/freebsd/man2/cpuset.2 | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/static/freebsd/man2/cpuset.2 b/static/freebsd/man2/cpuset.2 new file mode 100644 index 00000000..3d47f1b4 --- /dev/null +++ b/static/freebsd/man2/cpuset.2 @@ -0,0 +1,302 @@ +.\" 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. +.\" +.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 |