1.\"	$NetBSD: pset.3,v 1.15 2025/02/21 15:33:58 wiz Exp $
2.\"
3.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Mindaugas Rasiukevicius <rmind at NetBSD org>.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd February 21, 2025
31.Dt PSET 3
32.Os
33.Sh NAME
34.Nm pset_create ,
35.Nm pset_assign ,
36.Nm pset_bind ,
37.Nm pset_destroy
38.Nd processor sets
39.Sh LIBRARY
40.Lb librt
41.Sh SYNOPSIS
42.In sys/pset.h
43.Ft int
44.Fn pset_create "psetid_t *psid"
45.Ft int
46.Fn pset_assign "psetid_t psid" "cpuid_t cpuid" "psetid_t *opsid"
47.Ft int
48.Fn pset_bind "psetid_t psid" "idtype_t type" "id_t id" "psetid_t *opsid"
49.Ft int
50.Fn pset_destroy "psetid_t psid"
51.Sh DESCRIPTION
52The processor sets API provides the possibility to exclusively
53dedicate specific processors or groups of processors to processes
54or threads.
55After processes or threads are bound to a group of processors by
56the API, the group henceforth runs only those processes or threads.
57This section describes the functions used to control processor sets.
58.Sh FUNCTIONS
59.Bl -tag -width compact
60.It Fn pset_create psid
61Creates a processor set, and returns its ID into
62.Fa psid .
63.It Fn pset_assign psid cpu opsid
64Assigns the processor specified by
65.Fa cpuid
66to the processor set specified by
67.Fa psid .
68Stores the current processor set ID of the processor or
69.Dv PS_NONE
70into
71.Fa opsid ,
72if the pointer is not
73.Dv NULL .
74.Pp
75The following actions can be specified:
76.Bl -enum -offset 2n
77.It
78If
79.Fa psid
80is set to
81.Dv PS_QUERY ,
82then the current processor set ID will be returned into
83.Fa psid ,
84and no assignment will be performed.
85.It
86If
87.Fa psid
88is set to
89.Dv PS_MYID ,
90then the processor set ID of the calling process will be used, and
91.Fa psid
92will be ignored.
93.It
94If
95.Fa psid
96is set to
97.Dv PS_NONE ,
98any assignment to the processor will be cleared.
99.El
100.It Fn pset_bind psid type id opsid
101Dedicates the processor set specified by
102.Fa psid
103to the target specified by
104.Fa id .
105The current processor set ID to which the target is bound or
106.Dv PS_NONE
107will be returned in
108.Fa opsid ,
109if the pointer is not
110.Dv NULL .
111.Nx
112supports the following types of targets specified by
113.Fa type :
114.Bl -tag -width P_LWPID -offset 2n
115.It Dv P_PID
116Process identified by the PID.
117.It Dv P_LWPID
118Thread of the calling process identified by the LID.
119.El
120.Pp
121The following actions can be specified:
122.Bl -enum -offset 2n
123.It
124If
125.Fa psid
126is set to
127.Dv PS_QUERY ,
128then the current processor set ID to which the target is bound or
129.Dv PS_NONE
130will be returned in
131.Fa opsid ,
132and no binding will be performed.
133.It
134If
135.Fa psid
136is set to
137.Dv PS_MYID ,
138then the processor set ID of the calling process will be used.
139.It
140If
141.Fa psid
142is set to
143.Dv PS_NONE ,
144the specified target will be unbound from the processor set.
145.El
146.It Fn pset_destroy psid
147Destroys the processor set specified by
148.Fa psid .
149Before destroying the processor set, all related assignments of the
150processors will be cleared, and all bound threads will be unbound.
151.Pp
152If
153.Fa psid
154is
155.Dv PS_MYID ,
156the processor set ID of the caller thread will be used.
157.El
158.Sh IMPLEMENTATION NOTES
159Except for
160.Dv PS_QUERY
161operations, these interfaces require super-user privileges.
162.Pp
163The
164.Fn pset_bind
165function can return the current processor set ID to which the
166target is bound, or
167.Dv PS_NONE .
168However, for example, the process may have many threads, which could be
169bound to different processor sets.
170In such a case it is unspecified which thread will be used to return
171the information.
172.Pp
173There is an alternative thread affinity interface, see
174.Xr affinity 3 .
175However, processor sets and thread affinity are mutually exclusive,
176hence mixing of these interfaces is prohibited.
177.Sh RETURN VALUES
178Upon successful completion these functions return 0.
179Otherwise, \-1 is returned and
180.Va errno
181is set to indicate the error.
182.Sh EXAMPLES
183An example of code fragment, which assigns the CPU whose ID is 0,
184for current process:
185.Bd -literal
186	psetid_t psid;
187	cpuid_t ci = 0;
188
189	if (pset_create(&psid) < 0)
190		err(EXIT_FAILURE, "pset_create");
191
192	/* Assign CPU 0 to the processor-set */
193	if (pset_assign(psid, ci, NULL) < 0)
194		err(EXIT_FAILURE, "pset_assign");
195
196	/* Bind the current process to the processor-set */
197	if (pset_bind(psid, P_PID, P_MYID, NULL) < 0)
198		err(EXIT_FAILURE, "pset_bind");
199
200	/*
201	 * At this point, CPU 0 runs only the current process.
202	 */
203	perform_work();
204
205	if (pset_destroy(psid) < 0)
206		err(EXIT_FAILURE, "pset_destroy");
207.Ed
208.Sh ERRORS
209The
210.Fn pset_create
211function fails if:
212.Bl -tag -width Er
213.It Bq Er ENOMEM
214No memory is available for creation of the processor set, or limit
215of the allowed count of the processor sets was reached.
216.It Bq Er EPERM
217The calling process is not the super-user.
218.El
219.Pp
220The
221.Fn pset_assign
222function fails if:
223.Bl -tag -width Er
224.It Bq Er EBUSY
225Another operation is performing on the processor set.
226.It Bq Er EINVAL
227.Fa psid
228or
229.Fa cpuid
230are invalid.
231.It Bq Er EPERM
232The calling process is not the super-user, and
233.Fa psid
234is not
235.Dv PS_QUERY .
236.El
237.Pp
238The
239.Fn pset_bind
240function fails if:
241.Bl -tag -width Er
242.It Bq Er EBUSY
243Another operation is performing on the processor set.
244.It Bq Er EINVAL
245.Fa psid
246or
247.Fa type
248are invalid.
249.It Bq Er EPERM
250The calling process is not the super-user, and
251.Fa psid
252is not
253.Dv PS_QUERY .
254.It Bq Er ESRCH
255The specified target was not found.
256.El
257.Pp
258The
259.Fn pset_destroy
260function fails if:
261.Bl -tag -width Er
262.It Bq Er EBUSY
263Another operation is performing on the processor set.
264.It Bq Er EPERM
265The calling process is not the super-user.
266.El
267.Sh SEE ALSO
268.Xr affinity 3 ,
269.Xr cpuset 3 ,
270.Xr sched 3 ,
271.Xr schedctl 8
272.Sh STANDARDS
273This API is expected to be compatible with the APIs found in Solaris and
274HP-UX operating systems.
275.Sh HISTORY
276The processor sets appeared in
277.Nx 5.0 .
278