mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-06 09:17:25 +00:00
- Add a man page for cpuset(), cpuset_setid(), and cpuset_getid() and hook
it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
This commit is contained in:
Jeff Roberson
parent
52481a9a9d
commit
329356f9f2
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=177705
@ -63,7 +63,7 @@ MAN+= _exit.2 abort2.2 accept.2 access.2 acct.2 adjtime.2 \
|
||||
aio_suspend.2 aio_waitcomplete.2 aio_write.2 \
|
||||
bind.2 brk.2 chdir.2 chflags.2 \
|
||||
chmod.2 chown.2 chroot.2 clock_gettime.2 close.2 \
|
||||
connect.2 dup.2 execve.2 extattr_get_file.2 \
|
||||
connect.2 cpuset.2 dup.2 execve.2 extattr_get_file.2 \
|
||||
fcntl.2 fhopen.2 flock.2 fork.2 fsync.2 \
|
||||
getdirentries.2 getdtablesize.2 \
|
||||
getfh.2 getfsstat.2 getgid.2 getgroups.2 getitimer.2 getlogin.2 \
|
||||
@ -104,6 +104,7 @@ MLINKS+=chflags.2 fchflags.2 chflags.2 lchflags.2
|
||||
MLINKS+=chmod.2 fchmod.2 chmod.2 lchmod.2
|
||||
MLINKS+=chown.2 fchown.2 chown.2 lchown.2
|
||||
MLINKS+=clock_gettime.2 clock_getres.2 clock_gettime.2 clock_settime.2
|
||||
MLINKS+=cpuset.2 cpuset_setid.2 cpuset.2 cpuset_getid.2
|
||||
MLINKS+=dup.2 dup2.2
|
||||
MLINKS+=extattr_get_file.2 extattr.2 \
|
||||
extattr_get_file.2 extattr_delete_fd.2 \
|
||||
|
||||
225
lib/libc/sys/cpuset.2
Normal file
225
lib/libc/sys/cpuset.2
Normal file
@ -0,0 +1,225 @@
|
||||
.\" 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/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
|
||||
Loading…
Reference in New Issue
Block a user