/share/man/man9/kproc.9

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