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 SLIST_ENTRY(sysinit) next; /* singly-linked list */ 64 sysinit_cfunc_t func; /* function */ 65 const void *udata; /* multiplexer/argument */ 66}; 67.Ed 68.Pp 69The 70.Fn SYSINIT 71macro takes a 72.Fa uniquifier 73argument to identify the particular function dispatch data, 74the 75.Fa subsystem 76type of startup interface, the subsystem element 77.Fa order 78of initialization within the subsystem, the 79.Fa func 80function to call, 81and the data specified in 82.Fa ident 83argument to pass the function. 84.Pp 85The 86.Fn SYSUNINIT 87macro behaves similarly to the 88.Fn SYSINIT 89macro except that it adds the data to a shutdown linker set. 90.Pp 91The startup linker set for the kernel is scanned during boot to build a 92sorted list of initialization routines. 93The initialization routines are then executed in the sorted order. 94The 95.Fa subsystem 96is used as the primary key and is sorted in ascending order. 97The 98.Fa order 99is used as the secondary key and is sorted in ascending order. 100The relative order of two routines that have the same 101.Fa subsystem 102and 103.Fa order 104is undefined. 105.Pp 106The startup linker sets for modules that are loaded together with the kernel 107by the boot loader are scanned during the 108.Dv SI_SUB_KLD 109subsystem initialization. 110These modules' initialization routines are sorted and merged into the kernel's 111list of startup routines and are executed during boot along with the kernel's 112initialization routines. 113Note that this has the effect that any initialization routines in a kernel 114module that are scheduled earlier than 115.Dv SI_SUB_KLD 116are not executed until after 117.Dv SI_SUB_KLD 118during boot. 119.Pp 120The startup linker set for a kernel module loaded at runtime via 121.Xr kldload 2 122is scanned, sorted, and executed when the module is loaded. 123.Pp 124The shutdown linker set for a kernel module is scanned, sorted, and executed 125when a kernel module is unloaded. 126The teardown routines are sorted in the reverse order of the initialization 127routines. 128The teardown routines of the kernel and any loaded modules are 129.Sy not 130executed during shutdown. 131.Sh EXAMPLES 132This example shows the SYSINIT which displays the copyright notice during boot: 133.Bd -literal -offset indent 134static void 135print_caddr_t(void *data) 136{ 137 printf("%s", (char *)data); 138} 139SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, 140 copyright); 141.Ed 142.Sh SEE ALSO 143.Xr kld 4 , 144.Xr DECLARE_MODULE 9 , 145.Xr DEV_MODULE 9 , 146.Xr DRIVER_MODULE 9 , 147.Xr MTX_SYSINIT 9 , 148.Xr SYSCALL_MODULE 9 149.Sh HISTORY 150The 151.Nm 152framework first appeared in 153.Fx 2.2 . 154.Sh AUTHORS 155.An -nosplit 156The 157.Nm 158framework was written by 159.An Terrence Lambert Aq Mt terry@FreeBSD.org . 160.Pp 161This manual page was written by 162.An Hiten Pandya Aq Mt hmp@FreeBSD.org . 163