.\" Copyright (c) 2008 Christian Brueffer
.\" Copyright (c) 2008 Jeffrey Roberson
.\" 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 March 29, 2008
.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
assign processes and threads to these sets.
Processor sets contain lists of CPUs 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.
.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 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 .
.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_CPUSET -offset indent
.It Dv CPU_WHICH_TID Ta "id is lpwid_t (thread id)"
.It Dv CPU_WHICH_PID Ta "id is pid_t (process 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"
.El
.Pp
An
.Fa id
of '-1' may be used with a
.Fa which
of
.Dv CPU_WHICH_TID ,
.Dv CPU_WHICH_PID ,
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
and
.Xr cpuset_setaffinity 2 .
See those manual pages for more detail.
.Sh RETURN VALUES
.Rv -std
.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
.Fn cpusetid_t
for allocation.
.El
.Sh SEE ALSO
.Xr cpuset 1 ,
.Xr cpuset_getaffinity 2 ,
.Xr cpuset_setaffinity 2 ,
.Xr CPU_SET 3
.Sh HISTORY
The
.Nm
family of system calls first appeared in
.Fx 8.0 .
.Sh AUTHOR
.An Jeffrey Roberson Aq jeff@FreeBSD.org