/share/man/man9/kthread.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 349 lines · 347 code · 2 blank · 0 comment · 0 complexity · 657cbd576dbc333ba70b6cf49d4ea66f MD5 · raw file

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