/share/man/man9/kproc.9

  1.\" Copyright (c) 2000-2001
  2.\"	The Regents of the University of California.  All rights reserved.
  3.\"
  4.\" All rights reserved.
  5.\"
  6.\" Redistribution and use in source and binary forms, with or without
  7.\" modification, are permitted provided that the following conditions
  8.\" are met:
  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.
 14.\"
 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.
 25.\"
 26.\" $FreeBSD$
 27.\"
 28.Dd October 19, 2007
 29.Dt KPROC 9
 30.Os
 31.Sh NAME
 32.Nm kproc_start ,
 33.Nm kproc_shutdown ,
 34.Nm kproc_create ,
 35.Nm kproc_exit ,
 36.Nm kproc_resume ,
 37.Nm kproc_suspend ,
 38.Nm kproc_suspend_check
 39.Nd "kernel processes"
 40.Sh SYNOPSIS
 41.In sys/kthread.h
 42.Ft void
 43.Fn kproc_start "const void *udata"
 44.Ft void
 45.Fn kproc_shutdown "void *arg" "int howto"
 46.Ft int
 47.Fo kproc_create
 48.Fa "void (*func)(void *)" "void *arg" "struct proc **newpp"
 49.Fa "int flags" "int pages"
 50.Fa "const char *fmt" ...
 51.Fc
 52.Ft void
 53.Fn kproc_exit "int ecode"
 54.Ft int
 55.Fn kproc_resume "struct proc *p"
 56.Ft int
 57.Fn kproc_suspend "struct proc *p" "int timo"
 58.Ft void
 59.Fn kproc_suspend_check "struct proc *p"
 60.Ft int
 61.Fo kproc_kthread_add
 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" "..."
 65.Fc
 66.Sh DESCRIPTION
 67In
 68.Fx 8.0 ,
 69the
 70.Fn kthread* 9
 71family of functions was renamed to be the
 72.Fn kproc* 9
 73family of functions, as they were misnamed
 74and actually produced kernel processes.
 75A new family of
 76.Em different
 77.Fn kthread_* 9
 78functions was added to produce
 79.Em real
 80kernel
 81.Em threads .
 82See the
 83.Xr kthread 9
 84man page for more information on those calls.
 85Also note that the
 86.Fn kproc_kthread_add 9
 87function appears in both pages as its functionality is split.
 88.Pp
 89The function
 90.Fn kproc_start
 91is used to start
 92.Dq internal
 93daemons such as
 94.Nm bufdaemon , pagedaemon , vmdaemon ,
 95and the
 96.Nm syncer
 97and is intended
 98to be called from
 99.Xr SYSINIT 9 .
100The
101.Fa udata
102argument is actually a pointer to a
103.Vt "struct kproc_desc"
104which describes the kernel process that should be created:
105.Bd -literal -offset indent
106struct kproc_desc {
107	char		*arg0;
108	void		(*func)(void);
109	struct proc	**global_procpp;
110};
111.Ed
112.Pp
113The structure members are used by
114.Fn kproc_start
115as follows:
116.Bl -tag -width ".Va global_procpp" -offset indent
117.It Va arg0
118String to be used for the name of the process.
119This string will be copied into the
120.Va p_comm
121member of the new process'
122.Vt "struct proc" .
123.It Va func
124The main function for this kernel process to run.
125.It Va global_procpp
126A pointer to a
127.Vt "struct proc"
128pointer that should be updated to point to the newly created process' process
129structure.
130If this variable is
131.Dv NULL ,
132then it is ignored.
133.El
134.Pp
135The
136.Fn kproc_create
137function is used to create a kernel process.
138The new process shares its address space with process 0, the
139.Nm swapper
140process,
141and runs in kernel mode only.
142The
143.Fa func
144argument specifies the function that the process should execute.
145The
146.Fa arg
147argument is an arbitrary pointer that is passed in as the only argument to
148.Fa func
149when it is called by the new process.
150The
151.Fa newpp
152pointer points to a
153.Vt "struct proc"
154pointer that is to be updated to point to the newly created process.
155If this argument is
156.Dv NULL ,
157then it is ignored.
158The
159.Fa flags
160argument specifies a set of flags as described in
161.Xr rfork 2 .
162The
163.Fa pages
164argument specifies the size of the new kernel process's stack in pages.
165If 0 is used, the default kernel stack size is allocated.
166The rest of the arguments form a
167.Xr printf 9
168argument list that is used to build the name of the new process and is stored
169in the
170.Va p_comm
171member of the new process's
172.Vt "struct proc" .
173.Pp
174The
175.Fn kproc_exit
176function is used to terminate kernel processes.
177It should be called by the main function of the kernel process rather than
178letting the main function return to its caller.
179The
180.Fa ecode
181argument specifies the exit status of the process.
182While exiting, the function
183.Xr exit1 9
184will initiate a call to
185.Xr wakeup 9
186on the process handle.
187.Pp
188The
189.Fn kproc_resume ,
190.Fn kproc_suspend ,
191and
192.Fn kproc_suspend_check
193functions are used to suspend and resume a kernel process.
194During the main loop of its execution, a kernel process that wishes to allow
195itself to be suspended should call
196.Fn kproc_suspend_check
197passing in
198.Va curproc
199as the only argument.
200This function checks to see if the kernel process has been asked to suspend.
201If it has, it will
202.Xr tsleep 9
203until it is told to resume.
204Once it has been told to resume it will return allowing execution of the
205kernel process to continue.
206The other two functions are used to notify a kernel process of a suspend or
207resume request.
208The
209.Fa p
210argument points to the
211.Vt "struct proc"
212of the kernel process to suspend or resume.
213For
214.Fn kproc_suspend ,
215the
216.Fa timo
217argument specifies a timeout to wait for the kernel process to acknowledge the
218suspend request and suspend itself.
219.Pp
220The
221.Fn kproc_shutdown
222function is meant to be registered as a shutdown event for kernel processes that
223need to be suspended voluntarily during system shutdown so as not to interfere
224with system shutdown activities.
225The actual suspension of the kernel process is done with
226.Fn kproc_suspend .
227.Pp
228The
229.Fn kproc_kthread_add
230function is much like the
231.Fn kproc_create
232function above except that if the kproc already exists,
233then only a new thread (see
234.Xr kthread 9 )
235is created on the existing process.
236The
237.Fa func
238argument specifies the function that the process should execute.
239The
240.Fa arg
241argument is an arbitrary pointer that is passed in as the only argument to
242.Fa func
243when it is called by the new process.
244The
245.Fa procptr
246pointer points to a
247.Vt "struct proc"
248pointer that is the location to be updated with the new proc pointer
249if a new process is created, or if not
250.Dv NULL ,
251must contain the process pointer for the already existing process.
252If this argument points to
253.Dv NULL ,
254then a new process is created and the field updated.
255If not NULL, the
256.Fa tdptr
257pointer points to a
258.Vt "struct thread"
259pointer that is the location to be updated with the new thread pointer.
260The
261.Fa flags
262argument specifies a set of flags as described in
263.Xr rfork 2 .
264The
265.Fa pages
266argument specifies the size of the new kernel thread's stack in pages.
267If 0 is used, the default kernel stack size is allocated.
268The procname argument is the name the new process should be given if it needs to be created.
269It is
270.Em NOT
271a printf style format specifier but a simple string.
272The rest of the arguments form a
273.Xr printf 9
274argument list that is used to build the name of the new thread and is stored
275in the
276.Va td_name
277member of the new thread's
278.Vt "struct thread" .
279.Sh RETURN VALUES
280The
281.Fn kproc_create ,
282.Fn kproc_resume ,
283and
284.Fn kproc_suspend
285functions return zero on success and non-zero on failure.
286.Sh EXAMPLES
287This example demonstrates the use of a
288.Vt "struct kproc_desc"
289and the functions
290.Fn kproc_start ,
291.Fn kproc_shutdown ,
292and
293.Fn kproc_suspend_check
294to run the
295.Nm bufdaemon
296process.
297.Bd -literal -offset indent
298static struct proc *bufdaemonproc;
299
300static struct kproc_desc buf_kp = {
301	"bufdaemon",
302	buf_daemon,
303	&bufdaemonproc
304};
305SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start,
306    &buf_kp)
307
308static void
309buf_daemon()
310{
311	...
312	/*
313	 * This process needs to be suspended prior to shutdown sync.
314	 */
315	EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown,
316	    bufdaemonproc, SHUTDOWN_PRI_LAST);
317	...
318	for (;;) {
319		kproc_suspend_check(bufdaemonproc);
320		...
321	}
322}
323.Ed
324.Sh ERRORS
325The
326.Fn kproc_resume
327and
328.Fn kproc_suspend
329functions will fail if:
330.Bl -tag -width Er
331.It Bq Er EINVAL
332The
333.Fa p
334argument does not reference a kernel process.
335.El
336.Pp
337The
338.Fn kproc_create
339function will fail if:
340.Bl -tag -width Er
341.It Bq Er EAGAIN
342The system-imposed limit on the total
343number of processes under execution would be exceeded.
344The limit is given by the
345.Xr sysctl 3
346MIB variable
347.Dv KERN_MAXPROC .
348.It Bq Er EINVAL
349The
350.Dv RFCFDG
351flag was specified in the
352.Fa flags
353parameter.
354.El
355.Sh SEE ALSO
356.Xr rfork 2 ,
357.Xr exit1 9 ,
358.Xr kthread 9 ,
359.Xr SYSINIT 9 ,
360.Xr wakeup 9
361.Sh HISTORY
362The
363.Fn kproc_start
364function first appeared in
365.Fx 2.2 .
366The
367.Fn kproc_shutdown ,
368.Fn kproc_create ,
369.Fn kproc_exit ,
370.Fn kproc_resume ,
371.Fn kproc_suspend ,
372and
373.Fn kproc_suspend_check
374functions were introduced in
375.Fx 4.0 .
376Prior to
377.Fx 5.0 ,
378the
379.Fn kproc_shutdown ,
380.Fn kproc_resume ,
381.Fn kproc_suspend ,
382and
383.Fn kproc_suspend_check
384functions were named
385.Fn shutdown_kproc ,
386.Fn resume_kproc ,
387.Fn shutdown_kproc ,
388and
389.Fn kproc_suspend_loop ,
390respectively.
391Originally they had the names
392.Fn kthread_*
393but were changed to
394.Fn kproc_*
395when real kthreads became available.