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 September 24, 2004 29.Dt KTHREAD 9 30.Os 31.Sh NAME 32.Nm kthread_start , 33.Nm kthread_shutdown , 34.Nm kthread_add , 35.Nm kthread_exit , 36.Nm kthread_resume , 37.Nm kthread_suspend , 38.Nm kthread_suspend_check 39.Nd kernel threads 40.Pp 41.Em PROCESSES . 42.Sh SYNOPSIS 43.In sys/kthread.h 44.Ft void 45.Fn kthread_start "const void *udata" 46.Ft void 47.Fn kthread_shutdown "void *arg" "int howto" 48.Ft int 49.Fn kthread_add "void (*func)(void *)" "void *arg" "struct proc *procp" "struct thread **newtdpp" "int flags" "int pages" "const char *fmt" "..." 50.Ft void 51.Fn kthread_exit "void" 52.Ft int 53.Fn kthread_resume "struct thread *td" 54.Ft int 55.Fn kthread_suspend "struct thread *td" "int timo" 56.Ft void 57.Fn kthread_suspend_check "struct thread *td" 58.Sh DESCRIPTION 59The function 60.Fn kthread_start 61is used to start 62.Dq internal 63daemons such as bufdaemon, pagedaemon, vmdaemon, and the syncer and is intended 64to be called from 65.Xr SYSINIT 9 . 66The 67.Fa udata 68argument is actually a pointer to a 69.Li struct kthread_desc 70which describes the kernel thread that should be created: 71.Bd -literal -offset indent 72struct kthread_desc { 73 char *arg0; 74 void (*func)(void); 75 struct thread **global_threadpp; 76}; 77.Ed 78.Pp 79The structure members are used by 80.Fn kthread_start 81as follows: 82.Bl -tag -width "global_threadpp" -offset indent 83.It Va arg0 84String to be used for the name of the thread. 85This string will be copied into the 86.Va td_name 87member of the new threads' 88.Li struct thread . 89.It Va func 90The main function for this kernel process to run. 91.It Va global_threadpp 92A pointer to a 93.Li struct thread 94pointer that should be updated to point to the newly created thread' thread 95structure. 96If this variable is 97.Dv NULL , 98then it is ignored. The thread will be a subthread of proc0 (PID 0). 99.El 100.Pp 101The 102.Fn kthread_add 103function is used to create a kernel thread. 104The new thread runs in kernel mode only. It is added to the 105process specified by the 106.Fa procp 107argument, or if that is NULL, to proc0. 108The 109.Fa func 110argument specifies the function that the thread should execute. 111The 112.Fa arg 113argument is an arbitrary pointer that is passed in as the only argument to 114.Fa func 115when it is called by the new process. 116The 117.Fa newtdp 118pointer points to a 119.Li struct thread 120pointer that is to be updated to point to the newly created thread. 121If this argument is 122.Dv NULL , 123then it is ignored. 124The 125.Fa flags 126argument specifies a set of flags as described in 127.Xr rfork 2 . 128The 129.Fa pages 130argument specifies the size of the new kernel thread's stack in pages. 131If 0 is used, the default kernel stack size is allocated. 132The rest of the arguments form a 133.Xr printf 9 134argument list that is used to build the name of the new thread and is stored 135in the 136.Va td_name 137member of the new thread's 138.Li struct thread . 139.Pp 140The 141.Fn kthread_exit 142function is used to terminate kernel threads. 143It should be called by the main function of the kernel thread rather than 144letting the main function return to its caller. 145The 146.Pp 147The 148.Fn kthread_resume , 149.Fn kthread_suspend , 150and 151.Fn kthread_suspend_check 152functions are used to suspend and resume a kernel thread. 153During the main loop of its execution, a kernel thread that wishes to allow 154itself to be suspended should call 155.Fn kthread_suspend_check 156passing in 157.Va curthread 158as the only argument. 159This function checks to see if the kernel thread has been asked to suspend. 160If it has, it will 161.Xr tsleep 9 162until it is told to resume. 163Once it has been told to resume it will return allowing execution of the 164kernel thread to continue. 165The other two functions are used to notify a kernel thread of a suspend or 166resume request. 167The 168.Fa td 169argument points to the 170.Li struct thread 171of the kernel thread to suspend or resume. 172For 173.Fn kthread_suspend , 174the 175.Fa timo 176argument specifies a timeout to wait for the kernel thread to acknowledge the 177suspend request and suspend itself. 178.Pp 179The 180.Fn kthread_shutdown 181function is meant to be registered as a shutdown event for kernel threads that 182need to be suspended voluntarily during system shutdown so as not to interfere 183with system shutdown activities. 184The actual suspension of the kernel thread is done with 185.Fn kthread_suspend . 186.Sh RETURN VALUES 187The 188.Fn kthread_add , 189.Fn kthread_resume , 190and 191.Fn kthread_suspend 192functions return zero on success and non-zero on failure. 193.Sh EXAMPLES 194This example demonstrates the use of a 195.Li struct kthread_desc 196and the functions 197.Fn kthread_start , 198.Fn kthread_shutdown , 199and 200.Fn kthread_suspend_check 201to run the 202.Dq bufdaemon 203process. 204.Bd -literal -offset indent 205static struct thread *bufdaemonthread; 206 207static struct kthread_desc buf_kp = { 208 "bufdaemon", 209 buf_daemon, 210 &bufdaemonthread 211}; 212SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start, 213 &buf_kp) 214 215static void 216buf_daemon() 217{ 218 ... 219 /* 220 * This process needs to be suspended prior to shutdown sync. 221 */ 222 EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown, 223 bufdaemonthread, SHUTDOWN_PRI_LAST); 224 ... 225 for (;;) { 226 kthread_suspend_check(bufdaemonthread); 227 ... 228 } 229} 230.Ed 231.Sh ERRORS 232The 233.Fn kthread_resume 234and 235.Fn kthread_suspend 236functions will fail if: 237.Bl -tag -width Er 238.It Bq Er EINVAL 239The 240.Fa td 241argument does not reference a kernel thread. 242.El 243.Pp 244The 245.Fn kthread_create 246function will fail if: 247.Bl -tag -width Er 248.It Bq Er EAGAIN 249The system-imposed limit on the total 250number of processes under execution would be exceeded. 251The limit is given by the 252.Xr sysctl 3 253MIB variable 254.Dv KERN_MAXPROC . 255.It Bq Er EINVAL 256The 257.Dv RFCFDG 258flag was specified in the 259.Fa flags 260parameter. 261.El 262.Sh SEE ALSO 263.Xr rfork 2 , 264.Xr kproc 9 , 265.Xr exit1 9 , 266.Xr SYSINIT 9 , 267.Xr wakeup 9 268.Sh HISTORY 269The 270.Fn kthread_start 271function first appeared in 272.Fx 2.2 273where it created a whole process. It was converted to create threads in 274.Fx 8.0 . 275The 276.Fn kthread_shutdown , 277.Fn kthread_create , 278.Fn kthread_exit , 279.Fn kthread_resume , 280.Fn kthread_suspend , 281and 282.Fn kthread_suspend_check 283functions were introduced in 284.Fx 4.0 285and were converted to treads in 286.Fx 8.0 . 287The 288.Fn kthread_create 289call was renamed to kthread_add in 290.Fx 8.0 . 291The old functionality of creating a kernel process was renamed 292to 293.Fn kproc_create 294(and friends). 295See 296.Xr kproc 9 297Prior to 298.Fx 5.0 , 299the 300.Fn kthread_shutdown , 301.Fn kthread_resume , 302.Fn kthread_suspend , 303and 304.Fn kthread_suspend_check 305functions were named 306.Fn shutdown_kproc , 307.Fn resume_kproc , 308.Fn shutdown_kproc , 309and 310.Fn kproc_suspend_loop , 311respectively. 312