system/freebsd-src
system/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src synced 2024-07-22 10:48:02 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
freebsd-src/lib/libsys/cpuset_getaffinity.2

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

178 lines
4.9 KiB
Groff
Raw Normal View History

- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.\" 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.
.\"
Use Linux semantics for the thread affinity syscalls. Linux has more tolerant checks of the user supplied cpuset_t's. Minimum cpuset_t size that the Linux kernel permits in case of getaffinity() is the maximum CPU id, present in the system / NBBY, the maximum size is not limited. For setaffinity(), Linux does not limit the size of the user-provided cpuset_t, internally using only the meaningful part of the set, where the upper bound is the maximum CPU id, present in the system, no larger than the size of the kernel cpuset_t. Unlike FreeBSD, Linux ignores high bits if set in the setaffinity(), so clear it in the sched_setaffinity() and Linuxulator itself. Reviewed by: Pau Amma (man pages) In collaboration with: jhb Differential revision: https://reviews.freebsd.org/D34849 MFC after: 2 weeks
2022-05-11 07:36:01 +00:00
.Dd April 27, 2022
Remove cross-references to nonexistent CPU_SET(3) manpage. Also fix cpu_getaffinity(2) document title. PR: 176317 Submitted by: brucec
2013-04-21 06:46:41 +00:00
.Dt CPUSET_GETAFFINITY 2
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.Os
.Sh NAME
.Nm cpuset_getaffinity ,
.Nm cpuset_setaffinity
.Nd manage CPU affinity
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
Document that you must include <sys/param.h> before <sys/cpuset.h>. Approved by: rwatson (mentor)
2008-04-20 15:51:56 +00:00
.In sys/param.h
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.In sys/cpuset.h
.Ft int
.Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask"
.Ft int
.Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask"
.Sh DESCRIPTION
.Fn cpuset_getaffinity
and
.Fn cpuset_setaffinity
Remove trailing whitespace per mdoc lint warning Disussed with: gavin No objection from: doc Approved by: joel MFC after: 3 days
2012-03-29 05:02:12 +00:00
allow the manipulation of sets of CPUs available to processes, threads,
MFp4: Bring in updated jail support from bz_jail branch. This enhances the current jail implementation to permit multiple addresses per jail. In addtion to IPv4, IPv6 is supported as well. Due to updated checks it is even possible to have jails without an IP address at all, which basically gives one a chroot with restricted process view, no networking,.. SCTP support was updated and supports IPv6 in jails as well. Cpuset support permits jails to be bound to specific processor sets after creation. Jails can have an unrestricted (no duplicate protection, etc.) name in addition to the hostname. The jail name cannot be changed from within a jail and is considered to be used for management purposes or as audit-token in the future. DDB 'show jails' command was added to aid debugging. Proper compat support permits 32bit jail binaries to be used on 64bit systems to manage jails. Also backward compatibility was preserved where possible: for jail v1 syscalls, as well as with user space management utilities. Both jail as well as prison version were updated for the new features. A gap was intentionally left as the intermediate versions had been used by various patches floating around the last years. Bump __FreeBSD_version for the afore mentioned and in kernel changes. Special thanks to: - Pawel Jakub Dawidek (pjd) for his multi-IPv4 patches and Olivier Houchard (cognet) for initial single-IPv6 patches. - Jeff Roberson (jeff) and Randall Stewart (rrs) for their help, ideas and review on cpuset and SCTP support. - Robert Watson (rwatson) for lots and lots of help, discussions, suggestions and review of most of the patch at various stages. - John Baldwin (jhb) for his help. - Simon L. Nielsen (simon) as early adopter testing changes on cluster machines as well as all the testers and people who provided feedback the last months on freebsd-jail and other channels. - My employer, CK Software GmbH, for the support so I could work on this. Reviewed by: (see above) MFC after: 3 months (this is just so that I get the mail) X-MFC Before: 7.2-RELEASE if possible
2008-11-29 14:32:14 +00:00
interrupts, jails and other resources.
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
These functions may manipulate sets of CPUs that contain many processes
or per-object anonymous masks that effect only a single object.
.Pp
The valid values for the
.Fa level
and
.Fa which
arguments are documented in
.Xr cpuset 2 .
These arguments specify which object and which set of the object we are
referring to.
Not all possible combinations are valid.
For example, only processes may belong to a numbered set accessed by a
.Fa level
argument of
.Dv CPU_LEVEL_CPUSET .
All resources, however, have a mask which may be manipulated with
.Dv CPU_LEVEL_WHICH .
.Pp
Masks of type
.Ft cpuset_t
are composed using the
Remove cross-references to nonexistent CPU_SET(3) manpage. Also fix cpu_getaffinity(2) document title. PR: 176317 Submitted by: brucec
2013-04-21 06:46:41 +00:00
.Dv CPU_SET
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
macros.
Use Linux semantics for the thread affinity syscalls. Linux has more tolerant checks of the user supplied cpuset_t's. Minimum cpuset_t size that the Linux kernel permits in case of getaffinity() is the maximum CPU id, present in the system / NBBY, the maximum size is not limited. For setaffinity(), Linux does not limit the size of the user-provided cpuset_t, internally using only the meaningful part of the set, where the upper bound is the maximum CPU id, present in the system, no larger than the size of the kernel cpuset_t. Unlike FreeBSD, Linux ignores high bits if set in the setaffinity(), so clear it in the sched_setaffinity() and Linuxulator itself. Reviewed by: Pau Amma (man pages) In collaboration with: jhb Differential revision: https://reviews.freebsd.org/D34849 MFC after: 2 weeks
2022-05-11 07:36:01 +00:00
If the user-supplied mask is not large enough to fit all of the matching CPUs,
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.Fn cpuset_getaffinity
Use Linux semantics for the thread affinity syscalls. Linux has more tolerant checks of the user supplied cpuset_t's. Minimum cpuset_t size that the Linux kernel permits in case of getaffinity() is the maximum CPU id, present in the system / NBBY, the maximum size is not limited. For setaffinity(), Linux does not limit the size of the user-provided cpuset_t, internally using only the meaningful part of the set, where the upper bound is the maximum CPU id, present in the system, no larger than the size of the kernel cpuset_t. Unlike FreeBSD, Linux ignores high bits if set in the setaffinity(), so clear it in the sched_setaffinity() and Linuxulator itself. Reviewed by: Pau Amma (man pages) In collaboration with: jhb Differential revision: https://reviews.freebsd.org/D34849 MFC after: 2 weeks
2022-05-11 07:36:01 +00:00
fails with
.Er ERANGE .
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
Calls to
.Fn cpuset_setaffinity
Use Linux semantics for the thread affinity syscalls. Linux has more tolerant checks of the user supplied cpuset_t's. Minimum cpuset_t size that the Linux kernel permits in case of getaffinity() is the maximum CPU id, present in the system / NBBY, the maximum size is not limited. For setaffinity(), Linux does not limit the size of the user-provided cpuset_t, internally using only the meaningful part of the set, where the upper bound is the maximum CPU id, present in the system, no larger than the size of the kernel cpuset_t. Unlike FreeBSD, Linux ignores high bits if set in the setaffinity(), so clear it in the sched_setaffinity() and Linuxulator itself. Reviewed by: Pau Amma (man pages) In collaboration with: jhb Differential revision: https://reviews.freebsd.org/D34849 MFC after: 2 weeks
2022-05-11 07:36:01 +00:00
tolerate masks of any size with no restrictions.
The kernel uses the meaningful part of the mask, where the upper bound is
the maximum CPU id present in the system.
If bits for non-existing CPUs are set, calls to
.Fn cpuset_setaffinity
Correct grammo.
2023-07-08 12:25:44 +00:00
fail with
Use Linux semantics for the thread affinity syscalls. Linux has more tolerant checks of the user supplied cpuset_t's. Minimum cpuset_t size that the Linux kernel permits in case of getaffinity() is the maximum CPU id, present in the system / NBBY, the maximum size is not limited. For setaffinity(), Linux does not limit the size of the user-provided cpuset_t, internally using only the meaningful part of the set, where the upper bound is the maximum CPU id, present in the system, no larger than the size of the kernel cpuset_t. Unlike FreeBSD, Linux ignores high bits if set in the setaffinity(), so clear it in the sched_setaffinity() and Linuxulator itself. Reviewed by: Pau Amma (man pages) In collaboration with: jhb Differential revision: https://reviews.freebsd.org/D34849 MFC after: 2 weeks
2022-05-11 07:36:01 +00:00
.Er EINVAL .
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.Pp
The supplied mask should have a size of
.Fa setsize
bytes.
This size is usually provided by calling
.Li sizeof(mask)
which is ultimately determined by the value of
.Dv CPU_SETSIZE
as defined in
.In sys/cpuset.h .
.Pp
.Fn cpuset_getaffinity
retrieves the
mask from the object specified by
.Fa level ,
.Fa which
and
.Fa id
and stores it in the space provided by
.Fa mask .
.Pp
.Fn cpuset_setaffinity
attempts to set the mask for the object specified by
.Fa level ,
.Fa which
and
.Fa id
to the value in
.Fa mask .
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
The following error codes may be set in
.Va errno :
.Bl -tag -width Er
Improve errno documentation in pthread_create(3) and thr_new(2) Add some missing errno values to thr_new(2) and pthread_create(3). In particular, EDEADLK was not documented in the latter. While I'm here, improve some English and cross-references. Reviewed by: kib Sponsored by: Dell Inc. Differential Revision: https://reviews.freebsd.org/D6663
2016-06-03 14:30:32 +00:00
.\" When changing this list, consider updating share/man/man3/pthread_create.3,
.\" since that function can return any of these errors.
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.It Bq Er EINVAL
The
.Fa level
or
.Fa which
argument was not a valid value.
Add EINVAL to list of possible return values for cpuset_getaffinity(2). PR: 149978 Submitted by: gcooper Patch by: gcooper Approved by: keramida (mentor) MFC after: 1 week
2010-09-10 23:15:05 +00:00
.It Bq Er EINVAL
The
.Fa mask
argument specified when calling
.Fn cpuset_setaffinity
was not a valid value.
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.It Bq Er EDEADLK
The
.Fn cpuset_setaffinity
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 mask pointer passed was invalid.
.It Bq Er ESRCH
The object specified by the
.Fa id
and
.Fa which
arguments could not be found.
.It Bq Er ERANGE
The
.Fa cpusetsize
Use Linux semantics for the thread affinity syscalls. Linux has more tolerant checks of the user supplied cpuset_t's. Minimum cpuset_t size that the Linux kernel permits in case of getaffinity() is the maximum CPU id, present in the system / NBBY, the maximum size is not limited. For setaffinity(), Linux does not limit the size of the user-provided cpuset_t, internally using only the meaningful part of the set, where the upper bound is the maximum CPU id, present in the system, no larger than the size of the kernel cpuset_t. Unlike FreeBSD, Linux ignores high bits if set in the setaffinity(), so clear it in the sched_setaffinity() and Linuxulator itself. Reviewed by: Pau Amma (man pages) In collaboration with: jhb Differential revision: https://reviews.freebsd.org/D34849 MFC after: 2 weeks
2022-05-11 07:36:01 +00:00
was smaller than needed to fit all of the matching CPUs.
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.It Bq Er EPERM
The calling process did not have the credentials required to complete the
operation.
Allow cpuset_{get,set}affinity in capabilities mode bhyve was recently sandboxed with capsicum, and needs to be able to control the CPU sets of its vcpu threads Reviewed by: emaste, oshogbo, rwatson MFC after: 2 weeks Sponsored by: ScaleEngine Inc. Differential Revision: https://reviews.freebsd.org/D10170
2017-05-24 00:58:30 +00:00
.It Bq Er ECAPMODE
Fix a few mandoc issues - skipping paragraph macro: Pp after Sh - sections out of conventional order: Sh EXAMPLES - whitespace at end of input line - normalizing date format
2020-10-09 19:12:44 +00:00
The calling process attempted to act on a process other than itself, while
Allow cpuset_{get,set}affinity in capabilities mode bhyve was recently sandboxed with capsicum, and needs to be able to control the CPU sets of its vcpu threads Reviewed by: emaste, oshogbo, rwatson MFC after: 2 weeks Sponsored by: ScaleEngine Inc. Differential Revision: https://reviews.freebsd.org/D10170
2017-05-24 00:58:30 +00:00
in capability mode.
See
.Xr capsicum 4 .
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.El
.Sh SEE ALSO
.Xr cpuset 1 ,
.Xr cpuset 2 ,
Document new NUMA related syscalls and utility options. Sponsored by: Netflix, Dell/EMC Isilon
2018-03-24 23:58:44 +00:00
.Xr cpuset_getdomain 2 ,
cpuset{,_getaffinity,_getdomain}.2: fix SEE ALSO Sort by manpage section, then sort entries alphabetically. This makes the manpages `make manlint` clean. MFC after: 1 week Sponsored by: DellEMC Isilon
2020-12-11 01:52:27 +00:00
.Xr cpuset_getid 2 ,
Document new NUMA related syscalls and utility options. Sponsored by: Netflix, Dell/EMC Isilon
2018-03-24 23:58:44 +00:00
.Xr cpuset_setdomain 2 ,
cpuset{,_getaffinity,_getdomain}.2: fix SEE ALSO Sort by manpage section, then sort entries alphabetically. This makes the manpages `make manlint` clean. MFC after: 1 week Sponsored by: DellEMC Isilon
2020-12-11 01:52:27 +00:00
.Xr cpuset_setid 2 ,
Add a set of manual pages for pthread[_attr]_[sg]etaffinity(3). Reviewed by: davidxu MFC after: 2 weeks
2010-01-09 12:31:11 +00:00
.Xr pthread_affinity_np 3 ,
cpuset.9: Link to/from the new page A follow-up to r289667. Sponsored by: EMC / Isilon Storage Division
2015-10-20 23:52:37 +00:00
.Xr pthread_attr_affinity_np 3 ,
cpuset{,_getaffinity,_getdomain}.2: fix SEE ALSO Sort by manpage section, then sort entries alphabetically. This makes the manpages `make manlint` clean. MFC after: 1 week Sponsored by: DellEMC Isilon
2020-12-11 01:52:27 +00:00
.Xr capsicum 4 ,
cpuset.9: Link to/from the new page A follow-up to r289667. Sponsored by: EMC / Isilon Storage Division
2015-10-20 23:52:37 +00:00
.Xr cpuset 9
- Add a man page for cpuset_getaffinity() and cpuset_setaffinity() and hook it up to the build. Reviewed by: brueffer (skeleton and formatting assistance)
2008-03-29 10:26:29 +00:00
.Sh HISTORY
The
.Nm
family of system calls first appeared in
Support for CPU sets is going to appear in 7.1 before 8.0. MFC after: 3 days
2008-09-29 15:44:48 +00:00
.Fx 7.1 .
use .Mt to mark up email addresses consistently (part4) PR: 191174 Submitted by: Franco Fichtner <franco at lastsummer.de>
2014-06-23 08:25:03 +00:00
.Sh AUTHORS
.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org
Reference in a new issue Copy permalink