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