Bug 132884

2009/3/20 John Baldwin <jhb@freebsd.org>:
>
>>Number:         132884
>>Category:       docs
>>Synopsis:       No manpage for SYSINIT and SYSUNINIT
>>Confidential:   no
>>Severity:       non-critical
>>Priority:       low
>>Responsible:    freebsd-doc
>>State:          open
>>Quarter:
>>Keywords:
>>Date-Required:
>>Class:          doc-bug
>>Submitter-Id:   current-users
>>Arrival-Date:   Fri Mar 20 19:10:01 UTC 2009
>>Closed-Date:
>>Last-Modified:
>>Originator:     John Baldwin
>>Release:        8.0-CURRENT
>>Organization:
>>Environment:
>>Description:
> Currently there is not a section 9 manpage for the SYSINIT() and SYSUNINIT() macros.

Btw, there is a nice chapter in arch-, which could be used as base for
this man page.

-- 
wbr,
pluknet

What about this one?
It's extended from what was found at ~hmp,
parts taken from the arch book.

Comment 3 John Baldwin 2010-12-01 22:24:50 UTC

On Wednesday, December 01, 2010 12:56:37 pm Sergey Kandaurov wrote:
> What about this one?
> It's extended from what was found at ~hmp,
> parts taken from the arch book.

I think this looks fairly good, but I hacked on it some to adjust some wording 
I thought was awkward.  I also used .Fa instead of .Pa for macro arguments and 
expanded the text to note things like the sorting order and to add more detail 
on when these functions are executed (and when they aren't).  I also picked an
MI example (and one that doesn't use the bad form of SI_SUB_FOO - 1).

.\" 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@FreeBSD.org .
.Pp
This manual page was written by
.An Hiten Pandya Aq hmp@FreeBSD.org .


-- 
John Baldwin

Comment 4 dfilter service 2010-12-06 15:19:08 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@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Hiten Pandya Aq hmp@FreeBSD.org .
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscribe@freebsd.org"

Comment 5 John Baldwin 2010-12-06 15:19:23 UTC

State Changed
From-To: open->closed

Manpage committed to HEAD.