From nobody@FreeBSD.org  Fri Mar 20 19:07:25 2009
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 42909106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 20 Mar 2009 19:07:25 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 169CB8FC12
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 20 Mar 2009 19:07:25 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n2KJ7OSw074223
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 20 Mar 2009 19:07:24 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id n2KJ7O3U074222;
	Fri, 20 Mar 2009 19:07:24 GMT
	(envelope-from nobody)
Message-Id: <200903201907.n2KJ7O3U074222@www.freebsd.org>
Date: Fri, 20 Mar 2009 19:07:24 GMT
From: John Baldwin <jhb@FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org
Subject: No manpage for SYSINIT and SYSUNINIT
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         132884
>Category:       docs
>Synopsis:       [request] No manpage for SYSINIT and SYSUNINIT
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Mar 20 19:10:01 UTC 2009
>Closed-Date:    Mon Dec 06 15:19:43 UTC 2010
>Last-Modified:  Mon Dec  6 15:20:13 UTC 2010
>Originator:     John Baldwin
>Release:        8.0-CURRENT
>Organization:
>Environment:
>Description:
Currently there is not a section 9 manpage for the SYSINIT() and SYSUNINIT() macros.
>How-To-Repeat:

>Fix:


>Release-Note:
>Audit-Trail:

From: pluknet <pluknet@gmail.com>
To: John Baldwin <jhb@freebsd.org>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/132884: No manpage for SYSINIT and SYSUNINIT
Date: Sat, 21 Mar 2009 10:56:38 +0300

 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

From: Sergey Kandaurov <pluknet@gmail.com>
To: bug-followup@FreeBSD.org, jhb@FreeBSD.org
Cc:  
Subject: Re: docs/132884: [request] No manpage for SYSINIT and SYSUNINIT
Date: Wed, 1 Dec 2010 20:56:37 +0300

 --0016364ed5ded590d004965d0684
 Content-Type: text/plain; charset=ISO-8859-1
 
 What about this one?
 It's extended from what was found at ~hmp,
 parts taken from the arch book.
 
 --0016364ed5ded590d004965d0684
 Content-Type: text/plain; charset=US-ASCII; name="SYSINIT.9.txt"
 Content-Disposition: attachment; filename="SYSINIT.9.txt"
 Content-Transfer-Encoding: base64
 X-Attachment-Id: f_gh6iowx60
 
 LlwiIENvcHlyaWdodCAoYykgMjAwMyBIaXRlbiBNLiBQYW5keWEKLlwiIEFsbCByaWdodHMgcmVz
 ZXJ2ZWQuCi5cIgouXCIgUmVkaXN0cmlidXRpb24gYW5kIHVzZSBpbiBzb3VyY2UgYW5kIGJpbmFy
 eSBmb3Jtcywgd2l0aCBvciB3aXRob3V0Ci5cIiBtb2RpZmljYXRpb24sIGFyZSBwZXJtaXR0ZWQg
 cHJvdmlkZWQgdGhhdCB0aGUgZm9sbG93aW5nIGNvbmRpdGlvbnMKLlwiIGFyZSBtZXQ6Ci5cIiAx
 LiBSZWRpc3RyaWJ1dGlvbnMgb2Ygc291cmNlIGNvZGUgbXVzdCByZXRhaW4gdGhlIGFib3ZlIGNv
 cHlyaWdodAouXCIgICAgbm90aWNlLCB0aGlzIGxpc3Qgb2YgY29uZGl0aW9ucyBhbmQgdGhlIGZv
 bGxvd2luZyBkaXNjbGFpbWVyLgouXCIgMi4gUmVkaXN0cmlidXRpb25zIGluIGJpbmFyeSBmb3Jt
 IG11c3QgcmVwcm9kdWNlIHRoZSBhYm92ZSBjb3B5cmlnaHQKLlwiICAgIG5vdGljZSwgdGhpcyBs
 aXN0IG9mIGNvbmRpdGlvbnMgYW5kIHRoZSBmb2xsb3dpbmcgZGlzY2xhaW1lciBpbiB0aGUKLlwi
 ICAgIGRvY3VtZW50YXRpb24gYW5kL29yIG90aGVyIG1hdGVyaWFscyBwcm92aWRlZCB3aXRoIHRo
 ZSBkaXN0cmlidXRpb24uCi5cIgouXCIgVEhJUyBTT0ZUV0FSRSBJUyBQUk9WSURFRCBCWSBUSEUg
 QVVUSE9SIEFORCBDT05UUklCVVRPUlMgYGBBUyBJUycnIEFORAouXCIgQU5ZIEVYUFJFU1MgT1Ig
 SU1QTElFRCBXQVJSQU5USUVTLCBJTkNMVURJTkcsIEJVVCBOT1QgTElNSVRFRCBUTywgVEhFCi5c
 IiBJTVBMSUVEIFdBUlJBTlRJRVMgT0YgTUVSQ0hBTlRBQklMSVRZIEFORCBGSVRORVNTIEZPUiBB
 IFBBUlRJQ1VMQVIgUFVSUE9TRQouXCIgQVJFIERJU0NMQUlNRUQuICBJTiBOTyBFVkVOVCBTSEFM
 TCBUSEUgQVVUSE9SIE9SIENPTlRSSUJVVE9SUyBCRSBMSUFCTEUKLlwiIEZPUiBBTlkgRElSRUNU
 LCBJTkRJUkVDVCwgSU5DSURFTlRBTCwgU1BFQ0lBTCwgRVhFTVBMQVJZLCBPUiBDT05TRVFVRU5U
 SUFMCi5cIiBEQU1BR0VTIChJTkNMVURJTkcsIEJVVCBOT1QgTElNSVRFRCBUTywgUFJPQ1VSRU1F
 TlQgT0YgU1VCU1RJVFVURSBHT09EUwouXCIgT1IgU0VSVklDRVM7IExPU1MgT0YgVVNFLCBEQVRB
 LCBPUiBQUk9GSVRTOyBPUiBCVVNJTkVTUyBJTlRFUlJVUFRJT04pCi5cIiBIT1dFVkVSIENBVVNF
 RCBBTkQgT04gQU5ZIFRIRU9SWSBPRiBMSUFCSUxJVFksIFdIRVRIRVIgSU4gQ09OVFJBQ1QsIFNU
 UklDVAouXCIgTElBQklMSVRZLCBPUiBUT1JUIChJTkNMVURJTkcgTkVHTElHRU5DRSBPUiBPVEhF
 UldJU0UpIEFSSVNJTkcgSU4gQU5ZIFdBWQouXCIgT1VUIE9GIFRIRSBVU0UgT0YgVEhJUyBTT0ZU
 V0FSRSwgRVZFTiBJRiBBRFZJU0VEIE9GIFRIRSBQT1NTSUJJTElUWSBPRgouXCIgU1VDSCBEQU1B
 R0UuCi5cIgouXCIgJEZyZWVCU0QkCi5cIgouRGQgRGVjZW1iZXIgMSwgMjAxMAouRHQgU1lTSU5J
 VCA5Ci5PcwouU2ggTkFNRQouTm0gU1lTSU5JVCAsCi5ObSBTWVNVTklOSVQgCi5OZCBhIGZyYW1l
 d29yayBmb3IgZHluYW1pYyBrZXJuZWwgaW5pdGlhbGl6YXRpb24KLlNoIFNZTk9QU0lTCi5JbiBz
 eXMvcGFyYW0uaAouSW4gc3lzL2tlcm5lbC5oCi5GbiBTWVNJTklUICJ1bmlxdWlmaWVyIiAiZW51
 bSBzeXNpbml0X3N1Yl9pZCBzdWJzeXN0ZW0iICJlbnVtIHN5c2luaXRfZWxlbV9vcmRlciBvcmRl
 ciIgInN5c2luaXRfY2Z1bmNfdCBmdW5jIiAiY29uc3Qgdm9pZCAqaWRlbnQiCi5GbiBTWVNVTklO
 SVQgInVuaXF1aWZpZXIiICJlbnVtIHN5c2luaXRfc3ViX2lkIHN1YnN5c3RlbSIgImVudW0gc3lz
 aW5pdF9lbGVtX29yZGVyIG9yZGVyIiAic3lzaW5pdF9jZnVuY190IGZ1bmMiICJjb25zdCB2b2lk
 ICppZGVudCIKLlNoIERFU0NSSVBUSU9OCi5ObQppcyBhIG1lY2hhbmlzbSB3aGljaCBpcyB1c2Vk
 IGluIHRoZSBkeW5hbWljIGluaXRpYWxpemF0aW9uIG9mIHRoZSBrZXJuZWwuCkl0IGFsbG93cyBy
 ZW9yZGVyaW5nIG9mIHN1YnN5c3RlbXMgYW5kIHRvIHNlcGVyYXRlbHkgY29tcGlsZSwgbGluayBh
 bmQKaW5pdGlhbGl6ZSBrZXJuZWwgbW9kdWxlcyAoS0xEcykuCi5QcApUaGUKLkZuIFNZU0lOSVQK
 bWFjcm8gY3JlYXRlcyB0aGUgbmVjZXNzYXJ5IGRhdGEgaW4KLk5tCnN0YXJ0dXAgZGF0YSBzZXQK
 LlZ0IHN0cnVjdCBzeXNpbml0CnRvIHNvcnQgYW5kIGRpc3BhdGNoIGEgZnVuY3Rpb24gYXQgc3lz
 dGVtCnN0YXJ0dXAgYW5kIG1vZHVsZSBsb2FkLCBhcyBkZWZpbmVkIGJ5Ci5JbiBzeXMva2VybmVs
 LmggOgouQmQgLWxpdGVyYWwKc3RydWN0IHN5c2luaXQgewoJZW51bSBzeXNpbml0X3N1Yl9pZCBz
 dWJzeXN0ZW07CS8qIHN1YnN5c3RlbSBpZGVudGlmaWVyKi8KCWVudW0gc3lzaW5pdF9lbGVtX29y
 ZGVyCW9yZGVyOwkvKiBpbml0IG9yZGVyIHdpdGhpbiBzdWJzeXN0ZW0qLwoJc3lzaW5pdF9jZnVu
 Y190IGZ1bmM7CQkvKiBmdW5jdGlvbiAgICAgICAgICAgICAqLwoJY29uc3Qgdm9pZAkqdWRhdGE7
 CQkvKiBtdWx0aXBsZXhlci9hcmd1bWVudCAqLwp9OwouRWQKLlBwClRoZQouRm4gU1lTSU5JVApt
 YWNybyB0YWtlcyBhCi5QYSB1bmlxdWlmaWVyCmFyZ3VtZW50IHRvIGlkZW50aWZ5IHRoZSBwYXJ0
 aWN1bGFyIGZ1bmN0aW9uIGRpc3BhdGNoIGRhdGEsCnRoZQouUGEgc3Vic3lzdGVtCnR5cGUgb2Yg
 c3RhcnR1cCBpbnRlcmZhY2UsIHRoZSBzdWJzeXN0ZW0gZWxlbWVudAouUGEgb3JkZXIKb2YgaW5p
 dGlhbGl6YXRpb24gd2l0aGluIHRoZSBzdWJzeXN0ZW0sIHRoZQouUGEgZnVuYwpmdW5jdGlvbiB0
 byBjYWxsLAphbmQgdGhlIGRhdGEgc3BlY2lmaWVkIGluCi5QYSBpZGVudAphcmd1bWVudCB0byBw
 YXNzIHRoZSBmdW5jdGlvbi4KLlBwClRoZQouRm4gU1lTVU5JTklUCm1hY3JvIGJlaGF2ZXMgc2lt
 aWxhcmx5IHRvIHRoZQouRm4gU1lTSU5JVAptYWNybyBleGNlcHQgdGhhdCBpdCBhZGRzIHRoZSBk
 YXRhIHRvIGNvcnJlc3BvbmRpbmcgc2h1dGRvd24gZGF0YSBzZXQuCi5TaCBFWEFNUExFUwpUaGlz
 IGV4YW1wbGUgc2hvd3MgYSBTWVNJTklUIHRoYXQgbmVlZHMgdG8gYmUgcnVuIGp1c3QgYmFyZWx5
 IGJlZm9yZQp0aGUgU1lTSU5JVCdzIHRoYXQgaGFuZGxlIHR1bmluZyBrZXJuZWwgcGFyYW1ldGVy
 czoKLkJkIC1saXRlcmFsIC1vZmZzZXQgaW5kZW50CnN0YXRpYyB2b2lkCm1wdGFibGVfcmVnaXN0
 ZXIodm9pZCAqZHVtbXkgX191bnVzZWQpCnsKCiAgICBhcGljX3JlZ2lzdGVyX2VudW1lcmF0b3Io
 Jm1wdGFibGVfZW51bWVyYXRvcik7Cn0KU1lTSU5JVChtcHRhYmxlX3JlZ2lzdGVyLCBTSV9TVUJf
 VFVOQUJMRVMgLSAxLCBTSV9PUkRFUl9GSVJTVCwKICAgIG1wdGFibGVfcmVnaXN0ZXIsIE5VTEwp
 OwouRWQKLlNoIERJQUdOT1NUSUNTCkJlaGF2aW91ciBpcyB1bmRlZmluZWQgaWYgaW52YWxpZCBh
 cmd1bWVudHMgYXJlIHBhc3NlZCB0byB0aGUgYWJvdmUKbWFjcm9zLgouU2ggU0VFIEFMU08KLlhy
 IGtsZCA0ICwKLlhyIERFQ0xBUkVfTU9EVUxFIDkgLAouWHIgREVWX01PRFVMRSA5ICwKLlhyIERS
 SVZFUl9NT0RVTEUgOSAsCi5YciBNVFhfU1lTSU5JVCA5ICwKLlhyIFNZU0NBTExfTU9EVUxFIDkK
 LlNoIEhJU1RPUlkKVGhlCi5ObQpmcmFtZXdvcmsgZmlyc3QgYXBwZWFyZWQgaW4KLkZ4IDIuMiAu
 Ci5TaCBBVVRIT1JTCi5BbiAtbm9zcGxpdApUaGUKLk5tCmZyYW1ld29yayB3YXMgd3JpdHRlbiBi
 eQouQW4gVGVycmVuY2UgTGFtYmVydCBBcSB0ZXJyeUBGcmVlQlNELm9yZyAuCi5QcApUaGlzIG1h
 bnVhbCBwYWdlIHdhcyB3cml0dGVuIGJ5Ci5BbiBIaXRlbiBQYW5keWEgQXEgaG1wQEZyZWVCU0Qu
 b3JnIC4K
 --0016364ed5ded590d004965d0684--

From: John Baldwin <jhb@freebsd.org>
To: Sergey Kandaurov <pluknet@gmail.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/132884: [request] No manpage for SYSINIT and SYSUNINIT
Date: Wed, 1 Dec 2010 17:24:50 -0500

 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
State-Changed-From-To: open->closed 
State-Changed-By: jhb 
State-Changed-When: Mon Dec 6 15:19:23 UTC 2010 
State-Changed-Why:  
Manpage committed to HEAD. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=132884 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@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@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"
 
>Unformatted:
