1 .\" Copyright (c) 2000-2001
2 .\" The Regents of the University of California. All rights reserved.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 .Nm kproc_suspend_check
39 .Nd "kernel processes"
43 .Fn kproc_start "const void *udata"
45 .Fn kproc_shutdown "void *arg" "int howto"
48 .Fa "void (*func)(void *)" "void *arg" "struct proc **newpp"
49 .Fa "int flags" "int pages"
50 .Fa "const char *fmt" ...
53 .Fn kproc_exit "int ecode"
55 .Fn kproc_resume "struct proc *p"
57 .Fn kproc_suspend "struct proc *p" "int timo"
59 .Fn kproc_suspend_check "struct proc *p"
62 .Fa "void (*func)(void *)" "void *arg"
63 .Fa "struct proc **procptr" "struct thread **tdptr"
64 .Fa "int flags" "int pages" "char * procname" "const char *fmt" "..."
71 family of functions was renamed to be the
73 family of functions, as they were misnamed
74 and actually produced kernel processes.
78 functions was added to produce
84 man page for more information on those calls.
86 .Fn kproc_kthread_add 9
87 function appears in both pages as its functionality is split.
94 .Nm bufdaemon , pagedaemon , vmdaemon ,
102 argument is actually a pointer to a
103 .Vt "struct kproc_desc"
104 which describes the kernel process that should be created:
105 .Bd -literal -offset indent
109 struct proc **global_procpp;
113 The structure members are used by
116 .Bl -tag -width ".Va global_procpp" -offset indent
118 String to be used for the name of the process.
119 This string will be copied into the
121 member of the new process'
124 The main function for this kernel process to run.
128 pointer that should be updated to point to the newly created process' process
137 function is used to create a kernel process.
138 The new process shares its address space with process 0, the
141 and runs in kernel mode only.
144 argument specifies the function that the process should execute.
147 argument is an arbitrary pointer that is passed in as the only argument to
149 when it is called by the new process.
154 pointer that is to be updated to point to the newly created process.
160 argument specifies a set of flags as described in
164 argument specifies the size of the new kernel process's stack in pages.
165 If 0 is used, the default kernel stack size is allocated.
166 The rest of the arguments form a
168 argument list that is used to build the name of the new process and is stored
171 member of the new process's
176 function is used to terminate kernel processes.
177 It should be called by the main function of the kernel process rather than
178 letting the main function return to its caller.
181 argument specifies the exit status of the process.
182 While exiting, the function
184 will initiate a call to
186 on the process handle.
192 .Fn kproc_suspend_check
193 functions are used to suspend and resume a kernel process.
194 During the main loop of its execution, a kernel process that wishes to allow
195 itself to be suspended should call
196 .Fn kproc_suspend_check
199 as the only argument.
200 This function checks to see if the kernel process has been asked to suspend.
203 until it is told to resume.
204 Once it has been told to resume it will return allowing execution of the
205 kernel process to continue.
206 The other two functions are used to notify a kernel process of a suspend or
210 argument points to the
212 of the kernel process to suspend or resume.
217 argument specifies a timeout to wait for the kernel process to acknowledge the
218 suspend request and suspend itself.
222 function is meant to be registered as a shutdown event for kernel processes that
223 need to be suspended voluntarily during system shutdown so as not to interfere
224 with system shutdown activities.
225 The actual suspension of the kernel process is done with
229 .Fn kproc_kthread_add
230 function is much like the
232 function above except that if the kproc already exists,
233 then only a new thread (see
235 is created on the existing process.
238 argument specifies the function that the process should execute.
241 argument is an arbitrary pointer that is passed in as the only argument to
243 when it is called by the new process.
248 pointer that is the location to be updated with the new proc pointer
249 if a new process is created, or if not
251 must contain the process pointer for the already existing process.
252 If this argument points to
254 then a new process is created and the field updated.
259 pointer that is the location to be updated with the new thread pointer.
262 argument specifies a set of flags as described in
266 argument specifies the size of the new kernel thread's stack in pages.
267 If 0 is used, the default kernel stack size is allocated.
268 The procname argument is the name the new process should be given if it needs to be created.
271 a printf style format specifier but a simple string.
272 The rest of the arguments form a
274 argument list that is used to build the name of the new thread and is stored
277 member of the new thread's
278 .Vt "struct thread" .
285 functions return zero on success and non-zero on failure.
287 This example demonstrates the use of a
288 .Vt "struct kproc_desc"
293 .Fn kproc_suspend_check
297 .Bd -literal -offset indent
298 static struct proc *bufdaemonproc;
300 static struct kproc_desc buf_kp = {
305 SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start,
313 * This process needs to be suspended prior to shutdown sync.
315 EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown,
316 bufdaemonproc, SHUTDOWN_PRI_LAST);
319 kproc_suspend_check(bufdaemonproc);
329 functions will fail if:
334 argument does not reference a kernel process.
339 function will fail if:
342 The system-imposed limit on the total
343 number of processes under execution would be exceeded.
344 The limit is given by the
351 flag was specified in the
364 function first appeared in
373 .Fn kproc_suspend_check
374 functions were introduced in
383 .Fn kproc_suspend_check
389 .Fn kproc_suspend_loop ,
391 Originally they had the names
395 when real kthreads became available.