xref: /freebsd/share/man/man9/SYSINIT.9 (revision 8d20be1e22095c27faf8fe8b2f0d089739cc742e)
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.\" $FreeBSD$
26.\"
27.Dd December 1, 2010
28.Dt SYSINIT 9
29.Os
30.Sh NAME
31.Nm SYSINIT ,
32.Nm SYSUNINIT
33.Nd a framework for dynamic kernel initialization
34.Sh SYNOPSIS
35.In sys/param.h
36.In sys/kernel.h
37.Fn SYSINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident"
38.Fn SYSUNINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident"
39.Sh DESCRIPTION
40.Nm
41is a mechanism for scheduling the execution of initialization and teardown
42routines.
43This is similar to init and fini routines with the addition of explicit
44ordering metadata.
45It allows runtime ordering of subsystem initialization in the kernel as well
46as kernel modules (KLDs).
47.Pp
48The
49.Fn SYSINIT
50macro creates a
51.Vt struct sysinit
52and stores it in a startup linker set.
53The
54.Vt struct sysinit
55type as well as the subsystem identifier constants
56.Pq Dv SI_SUB_*
57and initialization ordering constants
58.Pq Dv SI_ORDER_*
59are defined in
60.In sys/kernel.h :
61.Bd -literal
62struct sysinit {
63	enum sysinit_sub_id subsystem;	/* subsystem identifier*/
64	enum sysinit_elem_order	order;	/* init order within subsystem*/
65	sysinit_cfunc_t func;		/* function             */
66	const void	*udata;		/* multiplexer/argument */
67};
68.Ed
69.Pp
70The
71.Fn SYSINIT
72macro takes a
73.Fa uniquifier
74argument to identify the particular function dispatch data,
75the
76.Fa subsystem
77type of startup interface, the subsystem element
78.Fa order
79of initialization within the subsystem, the
80.Fa func
81function to call,
82and the data specified in
83.Fa ident
84argument to pass the function.
85.Pp
86The
87.Fn SYSUNINIT
88macro behaves similarly to the
89.Fn SYSINIT
90macro except that it adds the data to a shutdown linker set.
91.Pp
92The startup linker set for the kernel is scanned during boot to build a
93sorted list of initialization routines.
94The initialization routines are then executed in the sorted order.
95The
96.Fa subsystem
97is used as the primary key and is sorted in ascending order.
98The
99.Fa order
100is used as the secondary key and is sorted in ascending order.
101The relative order of two routines that have the same
102.Fa subsystem
103and
104.Fa order
105is undefined.
106.Pp
107The startup linker sets for modules that are loaded together with the kernel
108by the boot loader are scanned during the
109.Dv SI_SUB_KLD
110subsystem initialization.
111These modules' initialization routines are sorted and merged into the kernel's
112list of startup routines and are executed during boot along with the kernel's
113initialization routines.
114Note that this has the effect that any initialization routines in a kernel
115module that are scheduled earlier than
116.Dv SI_SUB_KLD
117are not executed until after
118.Dv SI_SUB_KLD
119during boot.
120.Pp
121The startup linker set for a kernel module loaded at runtime via
122.Xr kldload 2
123is scanned, sorted, and executed when the module is loaded.
124.Pp
125The shutdown linker set for a kernel module is scanned, sorted, and executed
126when a kernel module is unloaded.
127The teardown routines are sorted in the reverse order of the initialization
128routines.
129The teardown routines of the kernel and any loaded modules are
130.Sy not
131executed during shutdown.
132.Sh EXAMPLES
133This example shows the SYSINIT which displays the copyright notice during boot:
134.Bd -literal -offset indent
135static void
136print_caddr_t(void *data)
137{
138	printf("%s", (char *)data);
139}
140SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t,
141    copyright);
142.Ed
143.Sh SEE ALSO
144.Xr kld 4 ,
145.Xr DECLARE_MODULE 9 ,
146.Xr DEV_MODULE 9 ,
147.Xr DRIVER_MODULE 9 ,
148.Xr MTX_SYSINIT 9 ,
149.Xr SYSCALL_MODULE 9
150.Sh HISTORY
151The
152.Nm
153framework first appeared in
154.Fx 2.2 .
155.Sh AUTHORS
156.An -nosplit
157The
158.Nm
159framework was written by
160.An Terrence Lambert Aq terry@FreeBSD.org .
161.Pp
162This manual page was written by
163.An Hiten Pandya Aq hmp@FreeBSD.org .
164