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 January 26, 2009 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.Sh SYNOPSIS 41.In sys/kthread.h 42.Ft void 43.Fn kthread_start "const void *udata" 44.Ft void 45.Fn kthread_shutdown "void *arg" "int howto" 46.Ft void 47.Fn kthread_exit "void" 48.Ft int 49.Fn kthread_resume "struct thread *td" 50.Ft int 51.Fn kthread_suspend "struct thread *td" "int timo" 52.Ft void 53.Fn kthread_suspend_check "struct thread *td" 54.In sys/unistd.h 55.Ft int 56.Fo kthread_add 57.Fa "void (*func)(void *)" "void *arg" "struct proc *procp" 58.Fa "struct thread **newtdpp" "int flags" "int pages" 59.Fa "const char *fmt" ... 60.Fc 61.Ft int 62.Fo kproc_kthread_add 63.Fa "void (*func)(void *)" "void *arg" 64.Fa "struct proc **procptr" "struct thread **tdptr" 65.Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." 66.Fc 67.Sh DESCRIPTION 68In 69.Fx 8.0 , 70the older family of 71.Fn kthread_* 9 72functions was renamed to be the 73.Fn kproc_* 9 74family of functions, 75as they were previously misnamed 76and actually produced kernel processes. 77This new family of 78.Fn kthread_* 9 79functions was added to produce 80.Em real 81kernel threads. 82See the 83.Xr kproc 9 84man page for more information on the renamed 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 kthread_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 kthread_desc" 104which describes the kernel thread that should be created: 105.Bd -literal -offset indent 106struct kthread_desc { 107 char *arg0; 108 void (*func)(void); 109 struct thread **global_threadpp; 110}; 111.Ed 112.Pp 113The structure members are used by 114.Fn kthread_start 115as follows: 116.Bl -tag -width ".Va global_threadpp" -offset indent 117.It Va arg0 118String to be used for the name of the thread. 119This string will be copied into the 120.Va td_name 121member of the new threads' 122.Vt "struct thread" . 123.It Va func 124The main function for this kernel thread to run. 125.It Va global_threadpp 126A pointer to a 127.Vt "struct thread" 128pointer that should be updated to point to the newly created thread's 129.Vt thread 130structure. 131If this variable is 132.Dv NULL , 133then it is ignored. 134The thread will be a subthread of 135.Va proc0 136(PID 0). 137.El 138.Pp 139The 140.Fn kthread_add 141function is used to create a kernel thread. 142The new thread runs in kernel mode only. 143It is added to the process specified by the 144.Fa procp 145argument, or if that is 146.Dv NULL , 147to 148.Va proc0 . 149The 150.Fa func 151argument specifies the function that the thread should execute. 152The 153.Fa arg 154argument is an arbitrary pointer that is passed in as the only argument to 155.Fa func 156when it is called by the new thread. 157The 158.Fa newtdpp 159pointer points to a 160.Vt "struct thread" 161pointer that is to be updated to point to the newly created thread. 162If this argument is 163.Dv NULL , 164then it is ignored. 165The 166.Fa flags 167argument may be set to 168.Dv RFSTOPPED 169to leave the thread in a stopped state. 170The caller must call 171.Fn sched_add 172to start the thread. 173The 174.Fa pages 175argument specifies the size of the new kernel thread's stack in pages. 176If 0 is used, the default kernel stack size is allocated. 177The rest of the arguments form a 178.Xr printf 9 179argument list that is used to build the name of the new thread and is stored 180in the 181.Va td_name 182member of the new thread's 183.Vt "struct thread" . 184.Pp 185The 186.Fn kproc_kthread_add 187function is much like the 188.Fn kthread_add 189function above except that if the kproc does not already 190exist, it is created. 191This function is better documented in the 192.Xr kproc 9 193manual page. 194.Pp 195The 196.Fn kthread_exit 197function is used to terminate kernel threads. 198It should be called by the main function of the kernel thread rather than 199letting the main function return to its caller. 200.\" XXX "int ecode" argument isn't documented. 201.Pp 202The 203.Fn kthread_resume , 204.Fn kthread_suspend , 205and 206.Fn kthread_suspend_check 207functions are used to suspend and resume a kernel thread. 208During the main loop of its execution, a kernel thread that wishes to allow 209itself to be suspended should call 210.Fn kthread_suspend_check 211passing in 212.Va curthread 213as the only argument. 214This function checks to see if the kernel thread has been asked to suspend. 215If it has, it will 216.Xr tsleep 9 217until it is told to resume. 218Once it has been told to resume it will return allowing execution of the 219kernel thread to continue. 220The other two functions are used to notify a kernel thread of a suspend or 221resume request. 222The 223.Fa td 224argument points to the 225.Vt "struct thread" 226of the kernel thread to suspend or resume. 227For 228.Fn kthread_suspend , 229the 230.Fa timo 231argument specifies a timeout to wait for the kernel thread to acknowledge the 232suspend request and suspend itself. 233.Pp 234The 235.Fn kthread_shutdown 236function is meant to be registered as a shutdown event for kernel threads that 237need to be suspended voluntarily during system shutdown so as not to interfere 238with system shutdown activities. 239The actual suspension of the kernel thread is done with 240.Fn kthread_suspend . 241.Sh RETURN VALUES 242The 243.Fn kthread_add , 244.Fn kthread_resume , 245and 246.Fn kthread_suspend 247functions return zero on success and non-zero on failure. 248.Sh EXAMPLES 249This example demonstrates the use of a 250.Vt "struct kthread_desc" 251and the functions 252.Fn kthread_start , 253.Fn kthread_shutdown , 254and 255.Fn kthread_suspend_check 256to run the 257.Nm bufdaemon 258process. 259.Bd -literal -offset indent 260static struct thread *bufdaemonthread; 261 262static struct kthread_desc buf_kp = { 263 "bufdaemon", 264 buf_daemon, 265 &bufdaemonthread 266}; 267SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start, 268 &buf_kp) 269 270static void 271buf_daemon() 272{ 273 ... 274 /* 275 * This process needs to be suspended prior to shutdown sync. 276 */ 277 EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown, 278 bufdaemonthread, SHUTDOWN_PRI_LAST); 279 ... 280 for (;;) { 281 kthread_suspend_check(bufdaemonthread); 282 ... 283 } 284} 285.Ed 286.Sh ERRORS 287The 288.Fn kthread_resume 289and 290.Fn kthread_suspend 291functions will fail if: 292.Bl -tag -width Er 293.It Bq Er EINVAL 294The 295.Fa td 296argument does not reference a kernel thread. 297.El 298.Pp 299The 300.Fn kthread_add 301function will fail if: 302.Bl -tag -width Er 303.It Bq Er ENOMEM 304Memory for a thread's stack could not be allocated. 305.El 306.Sh SEE ALSO 307.Xr kproc 9 , 308.Xr SYSINIT 9 , 309.Xr wakeup 9 310.Sh HISTORY 311The 312.Fn kthread_start 313function first appeared in 314.Fx 2.2 315where it created a whole process. 316It was converted to create threads in 317.Fx 8.0 . 318The 319.Fn kthread_shutdown , 320.Fn kthread_exit , 321.Fn kthread_resume , 322.Fn kthread_suspend , 323and 324.Fn kthread_suspend_check 325functions were introduced in 326.Fx 4.0 327and were converted to threads in 328.Fx 8.0 . 329The 330.Fn kthread_create 331call was renamed to 332.Fn kthread_add 333in 334.Fx 8.0 . 335The old functionality of creating a kernel process was renamed 336to 337.Xr kproc_create 9 . 338Prior to 339.Fx 5.0 , 340the 341.Fn kthread_shutdown , 342.Fn kthread_resume , 343.Fn kthread_suspend , 344and 345.Fn kthread_suspend_check 346functions were named 347.Fn shutdown_kproc , 348.Fn resume_kproc , 349.Fn shutdown_kproc , 350and 351.Fn kproc_suspend_loop , 352respectively. 353