- 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)

2 files changed, 227 insertions, 1 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index 90ac144..880ba9b 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -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 \
diff --git a/lib/libc/sys/cpuset.2 b/lib/libc/sys/cpuset.2
new file mode 100644
index 0000000..fae9a38
--- /dev/null
+++ b/lib/libc/sys/cpuset.2
@@ -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