share/man/man9/SYSINIT.9

   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
  41 is a mechanism for scheduling the execution of initialization and teardown
  42 routines.
  43 This is similar to init and fini routines with the addition of explicit
  44 ordering metadata.
  45 It allows runtime ordering of subsystem initialization in the kernel as well
  46 as kernel modules (KLDs).
  47 .Pp
  48 The
  49 .Fn SYSINIT
  50 macro creates a
  51 .Vt struct sysinit
  52 and stores it in a startup linker set.
  53 The
  54 .Vt struct sysinit
  55 type as well as the subsystem identifier constants
  56 .Pq Dv SI_SUB_*
  57 and initialization ordering constants
  58 .Pq Dv SI_ORDER_*
  59 are defined in
  60 .In sys/kernel.h :
  61 .Bd -literal
  62 struct 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
  70 The
  71 .Fn SYSINIT
  72 macro takes a
  73 .Fa uniquifier
  74 argument to identify the particular function dispatch data,
  75 the
  76 .Fa subsystem
  77 type of startup interface, the subsystem element
  78 .Fa order
  79 of initialization within the subsystem, the
  80 .Fa func
  81 function to call,
  82 and the data specified in
  83 .Fa ident
  84 argument to pass the function.
  85 .Pp
  86 The
  87 .Fn SYSUNINIT
  88 macro behaves similarly to the
  89 .Fn SYSINIT
  90 macro except that it adds the data to a shutdown linker set.
  91 .Pp
  92 The startup linker set for the kernel is scanned during boot to build a
  93 sorted list of initialization routines.
  94 The initialization routines are then executed in the sorted order.
  95 The
  96 .Fa subsystem
  97 is used as the primary key and is sorted in ascending order.
  98 The
  99 .Fa order
 100 is used as the secondary key and is sorted in ascending order.
 101 The relative order of two routines that have the same
 102 .Fa subsystem
 103 and
 104 .Fa order
 105 is undefined.
 106 .Pp
 107 The startup linker sets for modules that are loaded together with the kernel
 108 by the boot loader are scanned during the
 109 .Dv SI_SUB_KLD
 110 subsystem initialization.
 111 These modules' initialization routines are sorted and merged into the kernel's
 112 list of startup routines and are executed during boot along with the kernel's
 113 initialization routines.
 114 Note that this has the effect that any initialization routines in a kernel
 115 module that are scheduled earlier than
 116 .Dv SI_SUB_KLD
 117 are not executed until after
 118 .Dv SI_SUB_KLD
 119 during boot.
 120 .Pp
 121 The startup linker set for a kernel module loaded at runtime via
 122 .Xr kldload 2
 123 is scanned, sorted, and executed when the module is loaded.
 124 .Pp
 125 The shutdown linker set for a kernel module is scanned, sorted, and executed
 126 when a kernel module is unloaded.
 127 The teardown routines are sorted in the reverse order of the initialization
 128 routines.
 129 The teardown routines of the kernel and any loaded modules are
 130 .Sy not
 131 executed during shutdown.
 132 .Sh EXAMPLES
 133 This example shows the SYSINIT which displays the copyright notice during boot:
 134 .Bd -literal -offset indent
 135 static void
 136 print_caddr_t(void *data)
 137 {
 138         printf("%s", (char *)data);
 139 }
 140 SYSINIT(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
 151 The
 152 .Nm
 153 framework first appeared in
 154 .Fx 2.2 .
 155 .Sh AUTHORS
 156 .An -nosplit
 157 The
 158 .Nm
 159 framework was written by
 160 .An Terrence Lambert Aq terry@FreeBSD.org .
 161 .Pp
 162 This manual page was written by
 163 .An Hiten Pandya Aq hmp@FreeBSD.org .