docs/132884: commit references a PR
dfilter service
dfilter at FreeBSD.ORG
Mon Dec 6 15:20:15 UTC 2010
The following reply was made to PR docs/132884; it has been noted by GNATS.
From: dfilter at FreeBSD.ORG (dfilter service)
To: bug-followup at FreeBSD.org
Cc:
Subject: Re: docs/132884: commit references a PR
Date: Mon, 6 Dec 2010 15:19:08 +0000 (UTC)
Author: jhb
Date: Mon Dec 6 15:19:03 2010
New Revision: 216232
URL: http://svn.freebsd.org/changeset/base/216232
Log:
Add a manpage for SYSINIT() and SYSUNINIT().
PR: docs/132884
Submitted by: pluknet, hmp
Added:
head/share/man/man9/SYSINIT.9 (contents, props changed)
Modified:
head/share/man/man9/Makefile
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Mon Dec 6 15:15:27 2010 (r216231)
+++ head/share/man/man9/Makefile Mon Dec 6 15:19:03 2010 (r216232)
@@ -244,6 +244,7 @@ MAN= accept_filter.9 \
sysctl.9 \
sysctl_add_oid.9 \
sysctl_ctx_init.9 \
+ SYSINIT.9 \
taskqueue.9 \
thread_exit.9 \
time.9 \
@@ -1211,6 +1212,7 @@ MLINKS+=sysctl_ctx_init.9 sysctl_ctx_ent
sysctl_ctx_init.9 sysctl_ctx_entry_del.9 \
sysctl_ctx_init.9 sysctl_ctx_entry_find.9 \
sysctl_ctx_init.9 sysctl_ctx_free.9
+MLINKS+=SYSINIT.9 SYSUNINIT.9
MLINKS+=taskqueue.9 TASK_INIT.9 \
taskqueue.9 taskqueue_cancel.9 \
taskqueue.9 taskqueue_create.9 \
Added: head/share/man/man9/SYSINIT.9
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man9/SYSINIT.9 Mon Dec 6 15:19:03 2010 (r216232)
@@ -0,0 +1,163 @@
+.\" Copyright (c) 2003 Hiten M. Pandya
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 1, 2010
+.Dt SYSINIT 9
+.Os
+.Sh NAME
+.Nm SYSINIT ,
+.Nm SYSUNINIT
+.Nd a framework for dynamic kernel initialization
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/kernel.h
+.Fn SYSINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident"
+.Fn SYSUNINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident"
+.Sh DESCRIPTION
+.Nm
+is a mechanism for scheduling the execution of initialization and teardown
+routines.
+This is similar to init and fini routines with the addition of explicit
+ordering metadata.
+It allows runtime ordering of subsystem initialization in the kernel as well
+as kernel modules (KLDs).
+.Pp
+The
+.Fn SYSINIT
+macro creates a
+.Vt struct sysinit
+and stores it in a startup linker set.
+The
+.Vt struct sysinit
+type as well as the subsystem identifier constants
+.Pq Dv SI_SUB_*
+and initialization ordering constants
+.Pq Dv SI_ORDER_*
+are defined in
+.In sys/kernel.h :
+.Bd -literal
+struct sysinit {
+ enum sysinit_sub_id subsystem; /* subsystem identifier*/
+ enum sysinit_elem_order order; /* init order within subsystem*/
+ sysinit_cfunc_t func; /* function */
+ const void *udata; /* multiplexer/argument */
+};
+.Ed
+.Pp
+The
+.Fn SYSINIT
+macro takes a
+.Fa uniquifier
+argument to identify the particular function dispatch data,
+the
+.Fa subsystem
+type of startup interface, the subsystem element
+.Fa order
+of initialization within the subsystem, the
+.Fa func
+function to call,
+and the data specified in
+.Fa ident
+argument to pass the function.
+.Pp
+The
+.Fn SYSUNINIT
+macro behaves similarly to the
+.Fn SYSINIT
+macro except that it adds the data to a shutdown linker set.
+.Pp
+The startup linker set for the kernel is scanned during boot to build a
+sorted list of initialization routines.
+The initialization routines are then executed in the sorted order.
+The
+.Fa subsystem
+is used as the primary key and is sorted in ascending order.
+The
+.Fa order
+is used as the secondary key and is sorted in ascending order.
+The relative order of two routines that have the same
+.Fa subsystem
+and
+.Fa order
+is undefined.
+.Pp
+The startup linker sets for modules that are loaded together with the kernel
+by the boot loader are scanned during the
+.Dv SI_SUB_KLD
+subsystem initialization.
+These modules' initialization routines are sorted and merged into the kernel's
+list of startup routines and are executed during boot along with the kernel's
+initialization routines.
+Note that this has the effect that any initialization routines in a kernel
+module that are scheduled earlier than
+.Dv SI_SUB_KLD
+are not executed until after
+.Dv SI_SUB_KLD
+during boot.
+.Pp
+The startup linker set for a kernel module loaded at runtime via
+.Xr kldload 2
+is scanned, sorted, and executed when the module is loaded.
+.Pp
+The shutdown linker set for a kernel module is scanned, sorted, and executed
+when a kernel module is unloaded.
+The teardown routines are sorted in the reverse order of the initialization
+routines.
+The teardown routines of the kernel and any loaded modules are
+.Sy not
+executed during shutdown.
+.Sh EXAMPLES
+This example shows the SYSINIT which displays the copyright notice during boot:
+.Bd -literal -offset indent
+static void
+print_caddr_t(void *data)
+{
+ printf("%s", (char *)data);
+}
+SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t,
+ copyright);
+.Ed
+.Sh SEE ALSO
+.Xr kld 4 ,
+.Xr DECLARE_MODULE 9 ,
+.Xr DEV_MODULE 9 ,
+.Xr DRIVER_MODULE 9 ,
+.Xr MTX_SYSINIT 9 ,
+.Xr SYSCALL_MODULE 9
+.Sh HISTORY
+The
+.Nm
+framework first appeared in
+.Fx 2.2 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+framework was written by
+.An Terrence Lambert Aq terry at FreeBSD.org .
+.Pp
+This manual page was written by
+.An Hiten Pandya Aq hmp at FreeBSD.org .
_______________________________________________
svn-src-all at freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscribe at freebsd.org"
More information about the freebsd-doc
mailing list