xref: /freebsd/share/man/man9/cpuset.9 (revision 4b9d605768acabc460aa6dcfe8a1f8db35b16794)
1.\" Copyright (c) 2015 Conrad Meyer <cem@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
14.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
15.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE
17.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
23.\" POSSIBILITY OF SUCH DAMAGE.
24.\"
25.Dd September 23, 2022
26.Dt CPUSET 9
27.Os
28.Sh NAME
29.Nm cpuset(9)
30\(em
31.Nm CPUSET_T_INITIALIZER ,
32.Nm CPUSET_FSET ,
33.Nm CPU_CLR ,
34.Nm CPU_COPY ,
35.Nm CPU_ISSET ,
36.Nm CPU_SET ,
37.Nm CPU_ZERO ,
38.Nm CPU_FILL ,
39.Nm CPU_SETOF ,
40.Nm CPU_EMPTY ,
41.Nm CPU_ISFULLSET ,
42.Nm CPU_FFS ,
43.Nm CPU_COUNT ,
44.Nm CPU_SUBSET ,
45.Nm CPU_OVERLAP ,
46.Nm CPU_CMP ,
47.Nm CPU_OR ,
48.Nm CPU_AND ,
49.Nm CPU_ANDNOT ,
50.Nm CPU_XOR ,
51.Nm CPU_CLR_ATOMIC ,
52.Nm CPU_SET_ATOMIC ,
53.Nm CPU_SET_ATOMIC_ACQ ,
54.Nm CPU_AND_ATOMIC ,
55.Nm CPU_OR_ATOMIC ,
56.Nm CPU_COPY_STORE_REL
57.Nd cpuset manipulation macros
58.Sh SYNOPSIS
59.In sys/_cpuset.h
60.In sys/cpuset.h
61.\"
62.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS"
63.Vt CPUSET_FSET
64.\"
65.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset"
66.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to"
67.Ft bool
68.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset"
69.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset"
70.Fn CPU_ZERO "cpuset_t *cpuset"
71.Fn CPU_FILL "cpuset_t *cpuset"
72.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset"
73.Ft bool
74.Fn CPU_EMPTY "cpuset_t *cpuset"
75.Ft bool
76.Fn CPU_ISFULLSET "cpuset_t *cpuset"
77.Ft int
78.Fn CPU_FFS "cpuset_t *cpuset"
79.Ft int
80.Fn CPU_COUNT "cpuset_t *cpuset"
81.\"
82.Ft bool
83.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle"
84.Ft bool
85.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2"
86.Ft bool
87.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2"
88.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2"
89.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2"
90.Fn CPU_ANDNOT "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2"
91.Fn CPU_XOR "cpuset_t *dst" "cpuset_t *src1" "cpuset_t *src2"
92.\"
93.Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset"
94.Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset"
95.Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset"
96.\"
97.Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src"
98.Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src"
99.Fn CPU_COPY_STORE_REL "cpuset_t *from" "cpuset_t *to"
100.Sh DESCRIPTION
101The
102.Nm
103family of macros provide a flexible and efficient CPU set implementation,
104backed by the
105.Xr bitset 9
106macros.
107Each CPU is represented by a single bit.
108The maximum number of CPUs representable by
109.Vt cpuset_t
110is
111.Va CPU_SETSIZE .
112Individual CPUs in cpusets are referenced with indices zero through
113.Fa CPU_SETSIZE - 1 .
114.Pp
115The
116.Fn CPUSET_T_INITIALIZER
117macro allows one to initialize a
118.Vt cpuset_t
119with a compile time literal value.
120.Pp
121The
122.Fn CPUSET_FSET
123macro defines a compile time literal, usable by
124.Fn CPUSET_T_INITIALIZER ,
125representing a full cpuset (all CPUs present).
126For examples of
127.Fn CPUSET_T_INITIALIZER
128and
129.Fn CPUSET_FSET
130usage, see the
131.Sx CPUSET_T_INITIALIZER EXAMPLE
132section.
133.Pp
134The
135.Fn CPU_CLR
136macro removes CPU
137.Fa cpu_idx
138from the cpuset pointed to by
139.Fa cpuset .
140The
141.Fn CPU_CLR_ATOMIC
142macro is identical, but the bit representing the CPU is cleared with atomic
143machine instructions.
144.Pp
145The
146.Fn CPU_COPY
147macro copies the contents of the cpuset
148.Fa from
149to the cpuset
150.Fa to .
151.Fn CPU_COPY_STORE_REL
152is similar, but copies component machine words from
153.Fa from
154and writes them to
155.Fa to
156with atomic store with release semantics.
157(That is, if
158.Fa to
159is composed of multiple machine words,
160.Fn CPU_COPY_STORE_REL
161performs multiple individually atomic operations.)
162.Pp
163The
164.Fn CPU_SET
165macro adds CPU
166.Fa cpu_idx
167to the cpuset pointed to by
168.Fa cpuset ,
169if it is not already present.
170The
171.Fn CPU_SET_ATOMIC
172macro is identical, but the bit representing the CPU is set with atomic
173machine instructions.
174The
175.Fn CPU_SET_ATOMIC_ACQ
176macro sets the bit representing the CPU with atomic acquire semantics.
177.Pp
178The
179.Fn CPU_ISSET
180macro returns
181.Dv true
182if CPU
183.Fa cpu_idx
184is a member of the cpuset pointed to by
185.Fa cpuset .
186.Pp
187The
188.Fn CPU_ZERO
189macro removes all CPUs from
190.Fa cpuset .
191.Pp
192The
193.Fn CPU_FILL
194macro adds all CPUs to
195.Fa cpuset .
196.Pp
197The
198.Fn CPU_SETOF
199macro removes all CPUs in
200.Fa cpuset
201before adding only CPU
202.Fa cpu_idx .
203.Pp
204The
205.Fn CPU_EMPTY
206macro returns
207.Dv true
208if
209.Fa cpuset
210is empty.
211.Pp
212The
213.Fn CPU_ISFULLSET
214macro returns
215.Dv true
216if
217.Fa cpuset
218is full (the set of all CPUs).
219.Pp
220The
221.Fn CPU_FFS
222macro returns the 1-index of the first (lowest) CPU in
223.Fa cpuset ,
224or zero if
225.Fa cpuset
226is empty.
227Like with
228.Xr ffs 3 ,
229to use the non-zero result of
230.Fn CPU_FFS
231as a
232.Fa cpu_idx
233index parameter to any other
234.Nm
235macro, you must subtract one from the result.
236.Pp
237The
238.Fn CPU_COUNT
239macro returns the total number of CPUs in
240.Fa cpuset .
241.Pp
242The
243.Fn CPU_SUBSET
244macro returns
245.Dv true
246if
247.Fa needle
248is a subset of
249.Fa haystack .
250.Pp
251The
252.Fn CPU_OVERLAP
253macro returns
254.Dv true
255if
256.Fa cpuset1
257and
258.Fa cpuset2
259have any common CPUs.
260(That is, if
261.Fa cpuset1
262AND
263.Fa cpuset2
264is not the empty set.)
265.Pp
266The
267.Fn CPU_CMP
268macro returns
269.Dv true
270if
271.Fa cpuset1
272is NOT equal to
273.Fa cpuset2 .
274.Pp
275The
276.Fn CPU_OR
277macro adds CPUs present in
278.Fa src
279to
280.Fa dst .
281(It is the
282.Nm
283equivalent of the scalar:
284.Fa dst
285|=
286.Fa src . )
287.Fn CPU_OR_ATOMIC
288is similar, but sets the bits representing CPUs in the component machine words
289in
290.Fa dst
291with atomic machine instructions.
292(That is, if
293.Fa dst
294is composed of multiple machine words,
295.Fn CPU_OR_ATOMIC
296performs multiple individually atomic operations.)
297.Pp
298The
299.Fn CPU_AND
300macro removes CPUs absent from
301.Fa src
302from
303.Fa dst .
304(It is the
305.Nm
306equivalent of the scalar:
307.Fa dst
308&=
309.Fa src . )
310.Fn CPU_AND_ATOMIC
311is similar, with the same atomic semantics as
312.Fn CPU_OR_ATOMIC .
313.Pp
314The
315.Fn CPU_ANDNOT
316macro removes CPUs in
317.Fa src
318from
319.Fa dst .
320(It is the
321.Nm
322equivalent of the scalar:
323.Fa dst
324&=
325.Fa ~ src . )
326.Sh CPUSET_T_INITIALIZER EXAMPLE
327.Bd -literal
328cpuset_t myset;
329
330/* Initialize myset to filled (all CPUs) */
331myset = CPUSET_T_INITIALIZER(CPUSET_FSET);
332
333/* Initialize myset to only the lowest CPU */
334myset = CPUSET_T_INITIALIZER(0x1);
335.Ed
336.Sh SEE ALSO
337.Xr cpuset 1 ,
338.Xr cpuset 2 ,
339.Xr bitset 9
340.Sh HISTORY
341.In sys/cpuset.h
342first appeared in
343.Fx 7.1 ,
344released in January 2009, and in
345.Fx 8.0 ,
346released in November 2009.
347.Pp
348This manual page first appeared in
349.Fx 11.0 .
350.Sh AUTHORS
351.An -nosplit
352The
353.Nm
354macros were written by
355.An Jeff Roberson Aq Mt jeff@FreeBSD.org .
356This manual page was written by
357.An Conrad Meyer Aq Mt cem@FreeBSD.org .
358.Sh CAVEATS
359Unlike every other reference to individual set members, which are zero-indexed,
360.Fn CPU_FFS
361returns a one-indexed result (or zero if the cpuset is empty).
362