Date: Tue, 20 Oct 2015 23:48:14 +0000 (UTC) From: "Conrad E. Meyer" <cem@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r289667 - head/share/man/man9 Message-ID: <201510202348.t9KNmEAh029662@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: cem Date: Tue Oct 20 23:48:14 2015 New Revision: 289667 URL: https://svnweb.freebsd.org/changeset/base/289667 Log: Document cpuset(9) A follow-up to r289467. Coerced by: jhb Sponsored by: EMC / Isilon Storage Division Added: head/share/man/man9/cpuset.9 (contents, props changed) Modified: head/share/man/man9/Makefile head/share/man/man9/bitset.9 Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Tue Oct 20 21:20:34 2015 (r289666) +++ head/share/man/man9/Makefile Tue Oct 20 23:48:14 2015 (r289667) @@ -57,6 +57,7 @@ MAN= accept_filter.9 \ contigmalloc.9 \ copy.9 \ counter.9 \ + cpuset.9 \ cr_cansee.9 \ critical_enter.9 \ cr_seeothergids.9 \ @@ -636,6 +637,31 @@ MLINKS+=counter.9 counter_u64_alloc.9 \ counter.9 counter_u64_add_protected.9 \ counter.9 counter_u64_fetch.9 \ counter.9 counter_u64_zero.9 +MLINKS+=cpuset.9 CPUSET_T_INITIALIZER.9 \ + cpuset.9 CPUSET_FSET.9 \ + cpuset.9 CPU_CLR.9 \ + cpuset.9 CPU_COPY.9 \ + cpuset.9 CPU_ISSET.9 \ + cpuset.9 CPU_SET.9 \ + cpuset.9 CPU_ZERO.9 \ + cpuset.9 CPU_FILL.9 \ + cpuset.9 CPU_SETOF.9 \ + cpuset.9 CPU_EMPTY.9 \ + cpuset.9 CPU_ISFULLSET.9 \ + cpuset.9 CPU_FFS.9 \ + cpuset.9 CPU_COUNT.9 \ + cpuset.9 CPU_SUBSET.9 \ + cpuset.9 CPU_OVERLAP.9 \ + cpuset.9 CPU_CMP.9 \ + cpuset.9 CPU_OR.9 \ + cpuset.9 CPU_AND.9 \ + cpuset.9 CPU_NAND.9 \ + cpuset.9 CPU_CLR_ATOMIC.9 \ + cpuset.9 CPU_SET_ATOMIC.9 \ + cpuset.9 CPU_SET_ATOMIC_ACQ.9 \ + cpuset.9 CPU_AND_ATOMIC.9 \ + cpuset.9 CPU_OR_ATOMIC.9 \ + cpuset.9 CPU_COPY_STORE_REL.9 MLINKS+=critical_enter.9 critical.9 \ critical_enter.9 critical_exit.9 MLINKS+=crypto.9 crypto_dispatch.9 \ Modified: head/share/man/man9/bitset.9 ============================================================================== --- head/share/man/man9/bitset.9 Tue Oct 20 21:20:34 2015 (r289666) +++ head/share/man/man9/bitset.9 Tue Oct 20 23:48:14 2015 (r289667) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 17, 2015 +.Dd October 20, 2015 .Dt BITSET 9 .Os .Sh NAME @@ -352,16 +352,9 @@ myset = BITSET_T_INITIALIZER(BITSET_FSET myset = BITSET_T_INITIALIZER(0x1); .Ed .Sh SEE ALSO -The older -.Xr bitstring 3 . +.Xr bitstring 3 , +.Xr cpuset 9 .Sh HISTORY -.In sys/cpuset.h -first appeared in -.Fx 7.1 , -released in January 2009, and in -.Fx 8.0 , -released in November 2009 . -.Pp The .Nm macros first appeared in @@ -377,11 +370,9 @@ This manual page first appeared in .An -nosplit The .Nm -macros were written for +macros were generalized and pulled out of .In sys/cpuset.h -by -.An Jeff Roberson Aq Mt jeff@FreeBSD.org ; -they were generalized and pulled out as +as .In sys/_bitset.h and .In sys/bitset.h Added: head/share/man/man9/cpuset.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/cpuset.9 Tue Oct 20 23:48:14 2015 (r289667) @@ -0,0 +1,350 @@ +.\" Copyright (c) 2015 Conrad Meyer <cem@FreeBSD.org> +.\" 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 October 20, 2015 +.Dt CPUSET 9 +.Os +.Sh NAME +.Nm cpuset(9) +\(em +.Nm CPUSET_T_INITIALIZER , +.Nm CPUSET_FSET , +.Nm CPU_CLR , +.Nm CPU_COPY , +.Nm CPU_ISSET , +.Nm CPU_SET , +.Nm CPU_ZERO , +.Nm CPU_FILL , +.Nm CPU_SETOF , +.Nm CPU_EMPTY , +.Nm CPU_ISFULLSET , +.Nm CPU_FFS , +.Nm CPU_COUNT , +.Nm CPU_SUBSET , +.Nm CPU_OVERLAP , +.Nm CPU_CMP , +.Nm CPU_OR , +.Nm CPU_AND , +.Nm CPU_NAND , +.Nm CPU_CLR_ATOMIC , +.Nm CPU_SET_ATOMIC , +.Nm CPU_SET_ATOMIC_ACQ , +.Nm CPU_AND_ATOMIC , +.Nm CPU_OR_ATOMIC , +.Nm CPU_COPY_STORE_REL +.Nd cpuset manipulation macros +.Sh SYNOPSIS +.In sys/_cpuset.h +.In sys/cpuset.h +.\" +.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS" +.Vt CPUSET_FSET +.\" +.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to" +.Ft bool +.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_ZERO "cpuset_t *cpuset" +.Fn CPU_FILL "cpuset_t *cpuset" +.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset" +.Ft bool +.Fn CPU_EMPTY "cpuset_t *cpuset" +.Ft bool +.Fn CPU_ISFULLSET "cpuset_t *cpuset" +.Ft size_t +.Fn CPU_FFS "cpuset_t *cpuset" +.Ft size_t +.Fn CPU_COUNT "cpuset_t *cpuset" +.\" +.Ft bool +.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle" +.Ft bool +.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2" +.Ft bool +.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2" +.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_NAND "cpuset_t *dst" "cpuset_t *src" +.\" +.Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset" +.\" +.Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_COPY_STORE_REL "cpuset_t *from" "cpuset_t *to" +.Sh DESCRIPTION +The +.Nm +family of macros provide a flexible and efficient CPU set implementation, +backed by the +.Xr bitset 9 +macros. +Each CPU is represented by a single bit. +The maximum number of CPUs representable by +.Vt cpuset_t +is +.Va MAXCPU . +Individual CPUs in cpusets are referenced with indices zero through +.Fa MAXCPU - 1 . +.Pp +The +.Fn CPUSET_T_INITIALIZER +macro allows one to initialize a +.Vt cpuset_t +with a compile time literal value. +.Pp +The +.Fn CPUSET_FSET +macro defines a compile time literal, usable by +.Fn CPUSET_T_INITIALIZER , +representing a full cpuset (all CPUs present). +For examples of +.Fn CPUSET_T_INITIALIZER +and +.Fn CPUSET_FSET +usage, see the +.Sx CPUSET_T_INITIALIZER EXAMPLE +section. +.Pp +The +.Fn CPU_CLR +macro removes CPU +.Fa cpu_idx +from the cpuset pointed to by +.Fa cpuset . +The +.Fn CPU_CLR_ATOMIC +macro is identical, but the bit representing the CPU is cleared with atomic +machine instructions. +.Pp +The +.Fn CPU_COPY +macro copies the contents of the cpuset +.Fa from +to the cpuset +.Fa to . +.Fn CPU_COPY_STORE_REL +is similar, but copies component machine words from +.Fa from +and writes them to +.Fa to +with atomic store with release semantics. +(That is, if +.Fa to +is composed of multiple machine words, +.Fn CPU_COPY_STORE_REL +performs multiple individually atomic operations.) +.Pp +The +.Fn CPU_SET +macro adds CPU +.Fa cpu_idx +to the cpuset pointed to by +.Fa cpuset , +if it is not already present. +The +.Fn CPU_SET_ATOMIC +macro is identical, but the bit representing the CPU is set with atomic +machine instructions. +The +.Fn CPU_SET_ATOMIC_ACQ +macro sets the bit representing the CPU with atomic acquire semantics. +.Pp +The +.Fn CPU_ZERO +macro removes all CPUs from +.Fa cpuset . +.Pp +The +.Fn CPU_FILL +macro adds all CPUs to +.Fa cpuset . +.Pp +The +.Fn CPU_SETOF +macro removes all CPUs in +.Fa cpuset +before adding only CPU +.Fa cpu_idx . +.Pp +The +.Fn CPU_EMPTY +macro returns +.Dv true +if +.Fa cpuset +is empty. +.Pp +The +.Fn CPU_ISFULLSET +macro returns +.Dv true +if +.Fa cpuset +is full (the set of all CPUs). +.Pp +The +.Fn CPU_FFS +macro returns the 1-index of the first (lowest) CPU in +.Fa cpuset , +or zero if +.Fa cpuset +is empty. +Like with +.Xr ffs 3 , +to use the non-zero result of +.Fn CPU_FFS +as a +.Fa cpu_idx +index parameter to any other +.Nm +macro, you must subtract one from the result. +.Pp +The +.Fn CPU_COUNT +macro returns the total number of CPUs in +.Fa cpuset . +.Pp +The +.Fn CPU_SUBSET +macro returns +.Dv true +if +.Fa needle +is a subset of +.Fa haystack . +.Pp +The +.Fn CPU_OVERLAP +macro returns +.Dv true +if +.Fa cpuset1 +and +.Fa cpuset2 +have any common CPUs. +(That is, if +.Fa cpuset1 +AND +.Fa cpuset2 +is not the empty set.) +.Pp +The +.Fn CPU_CMP +macro returns +.Dv true +if +.Fa cpuset1 +is NOT equal to +.Fa cpuset2 . +.Pp +The +.Fn CPU_OR +macro adds CPUs present in +.Fa src +to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa src . ) +.Fn CPU_OR_ATOMIC +is similar, but sets the bits representing CPUs in the component machine words +in +.Fa dst +with atomic machine instructions. +(That is, if +.Fa dst +is composed of multiple machine words, +.Fn CPU_OR_ATOMIC +performs multiple individually atomic operations.) +.Pp +The +.Fn CPU_AND +macro removes CPUs absent from +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa src . ) +.Fn CPU_AND_ATOMIC +is similar, with the same atomic semantics as +.Fn CPU_OR_ATOMIC . +.Pp +The +.Fn CPU_NAND +macro removes CPUs in +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa ~ src . ) +.Sh CPUSET_T_INITIALIZER EXAMPLE +.Bd -literal +cpuset_t myset; + +/* Initialize myset to filled (all CPUs) */ +myset = CPUSET_T_INITIALIZER(CPUSET_FSET); + +/* Initialize myset to only the lowest CPU */ +myset = CPUSET_T_INITIALIZER(0x1); +.Ed +.Sh SEE ALSO +.Xr bitset 9 +.Sh HISTORY +.In sys/cpuset.h +first appeared in +.Fx 7.1 , +released in January 2009, and in +.Fx 8.0 , +released in November 2009. +.Pp +This manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +macros were written by +.An Jeff Roberson Aq Mt jeff@FreeBSD.org . +This manual page was written by +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +.Sh CAVEATS +Unlike every other reference to individual set members, which are zero-indexed, +.Fn CPU_FFS +returns a one-indexed result (or zero if the cpuset is empty).
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201510202348.t9KNmEAh029662>