xref: /freebsd/share/man/man9/SYSINIT.9 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)
1.\" Copyright (c) 2003 Hiten M. Pandya
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.Dd December 1, 2010
26.Dt SYSINIT 9
27.Os
28.Sh NAME
29.Nm SYSINIT ,
30.Nm SYSUNINIT
31.Nd a framework for dynamic kernel initialization
32.Sh SYNOPSIS
33.In sys/param.h
34.In sys/kernel.h
35.Fn SYSINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident"
36.Fn SYSUNINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident"
37.Sh DESCRIPTION
38.Nm
39is a mechanism for scheduling the execution of initialization and teardown
40routines.
41This is similar to init and fini routines with the addition of explicit
42ordering metadata.
43It allows runtime ordering of subsystem initialization in the kernel as well
44as kernel modules (KLDs).
45.Pp
46The
47.Fn SYSINIT
48macro creates a
49.Vt struct sysinit
50and stores it in a startup linker set.
51The
52.Vt struct sysinit
53type as well as the subsystem identifier constants
54.Pq Dv SI_SUB_*
55and initialization ordering constants
56.Pq Dv SI_ORDER_*
57are defined in
58.In sys/kernel.h :
59.Bd -literal
60struct sysinit {
61	enum sysinit_sub_id subsystem;	/* subsystem identifier*/
62	enum sysinit_elem_order	order;	/* init order within subsystem*/
63	sysinit_cfunc_t func;		/* function             */
64	const void	*udata;		/* multiplexer/argument */
65};
66.Ed
67.Pp
68The
69.Fn SYSINIT
70macro takes a
71.Fa uniquifier
72argument to identify the particular function dispatch data,
73the
74.Fa subsystem
75type of startup interface, the subsystem element
76.Fa order
77of initialization within the subsystem, the
78.Fa func
79function to call,
80and the data specified in
81.Fa ident
82argument to pass the function.
83.Pp
84The
85.Fn SYSUNINIT
86macro behaves similarly to the
87.Fn SYSINIT
88macro except that it adds the data to a shutdown linker set.
89.Pp
90The startup linker set for the kernel is scanned during boot to build a
91sorted list of initialization routines.
92The initialization routines are then executed in the sorted order.
93The
94.Fa subsystem
95is used as the primary key and is sorted in ascending order.
96The
97.Fa order
98is used as the secondary key and is sorted in ascending order.
99The relative order of two routines that have the same
100.Fa subsystem
101and
102.Fa order
103is undefined.
104.Pp
105The startup linker sets for modules that are loaded together with the kernel
106by the boot loader are scanned during the
107.Dv SI_SUB_KLD
108subsystem initialization.
109These modules' initialization routines are sorted and merged into the kernel's
110list of startup routines and are executed during boot along with the kernel's
111initialization routines.
112Note that this has the effect that any initialization routines in a kernel
113module that are scheduled earlier than
114.Dv SI_SUB_KLD
115are not executed until after
116.Dv SI_SUB_KLD
117during boot.
118.Pp
119The startup linker set for a kernel module loaded at runtime via
120.Xr kldload 2
121is scanned, sorted, and executed when the module is loaded.
122.Pp
123The shutdown linker set for a kernel module is scanned, sorted, and executed
124when a kernel module is unloaded.
125The teardown routines are sorted in the reverse order of the initialization
126routines.
127The teardown routines of the kernel and any loaded modules are
128.Sy not
129executed during shutdown.
130.Sh EXAMPLES
131This example shows the SYSINIT which displays the copyright notice during boot:
132.Bd -literal -offset indent
133static void
134print_caddr_t(void *data)
135{
136	printf("%s", (char *)data);
137}
138SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t,
139    copyright);
140.Ed
141.Sh SEE ALSO
142.Xr kld 4 ,
143.Xr DECLARE_MODULE 9 ,
144.Xr DEV_MODULE 9 ,
145.Xr DRIVER_MODULE 9 ,
146.Xr MTX_SYSINIT 9 ,
147.Xr SYSCALL_MODULE 9
148.Sh HISTORY
149The
150.Nm
151framework first appeared in
152.Fx 2.2 .
153.Sh AUTHORS
154.An -nosplit
155The
156.Nm
157framework was written by
158.An Terrence Lambert Aq Mt terry@FreeBSD.org .
159.Pp
160This manual page was written by
161.An Hiten Pandya Aq Mt hmp@FreeBSD.org .
162