From owner-freebsd-doc@FreeBSD.ORG Mon Oct 13 20:48:40 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 1F0D316A4B3 for ; Mon, 13 Oct 2003 20:48:40 -0700 (PDT) Received: from electra.cse.Buffalo.EDU (electra.cse.Buffalo.EDU [128.205.32.2]) by mx1.FreeBSD.org (Postfix) with ESMTP id AA69143F85 for ; Mon, 13 Oct 2003 20:48:38 -0700 (PDT) (envelope-from kensmith@cse.Buffalo.EDU) Received: from electra.cse.Buffalo.EDU (kensmith@localhost [127.0.0.1]) h9E3mcus020652 for ; Mon, 13 Oct 2003 23:48:38 -0400 (EDT) Received: (from kensmith@localhost) by electra.cse.Buffalo.EDU (8.12.10/8.12.9/Submit) id h9E3mcI5020651 for freebsd-doc@freebsd.org; Mon, 13 Oct 2003 23:48:38 -0400 (EDT) Date: Mon, 13 Oct 2003 23:48:38 -0400 From: Ken Smith To: freebsd-doc@freebsd.org Message-ID: <20031014034838.GA20484@electra.cse.Buffalo.EDU> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.4.1i Subject: SYSINIT() fixes for Architecture Manual X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 14 Oct 2003 03:48:40 -0000 Murray suggested I just send this here, and he'd chime in if nobody else feels like enough of an authority to say whether or not I'm lying. :-) While working on PR docs/57568 to fix the SYSINIT() examples I decided to try and clarify a little bit what SYSINIT() is/isn't used for. Can anyone say one way or another if I hit the target? Thanks. --- chapter.sgml_orig Sat Oct 11 20:07:09 2003 +++ chapter.sgml Mon Oct 13 21:23:37 2003 @@ -49,17 +49,27 @@ Sysinit uses two priorities when ordering the functions for execution. The first priority is a subsystem ID giving an - overall order Sysinit's dispatch of functions. Current predeclared - ID's are in <sys/kernel.h> in the enum + overall order for Sysinit's dispatch of functions. Current predeclared + ID's are in <sys/kernel.h> in the enum list sysinit_sub_id. The second priority used is an element order within the subsystem. Current predeclared subsystem element orders are in - <sys/kernel.h> in the enum list + <sys/kernel.h> in the enum list sysinit_elem_order. There are currently two uses for Sysinit. Function dispatch at system startup and kernel module loads, and function dispatch - at system shutdown and kernel module unload. + at system shutdown and kernel module unload. Kernel subsystems + often use system startup Sysinits to initialize data structures, + for example the process scheduling subsystem uses a Sysinit to + initialize the run queue data structures. Device drivers + should avoid using SYSINIT() directly. + Instead drivers for real devices that are part of a bus structure + should use DRIVER_MODULE() to provide a + function that detects the device and, if it is present, initializes + the device. It will do a few things specific to devices and then calls + SYSINIT() itself. For pseudo-devices, which are + not part of a bus structure, use DEV_MODULE(). @@ -72,14 +82,14 @@ Headers - <sys/kernel.h> + <sys/kernel.h> Macros SYSINIT(uniquifier, subsystem, order, func, ident) - SYSUNINIT(uniquifier, subsystem, order, func, ident) +SYSUNINIT(uniquifier, subsystem, order, func, ident) @@ -90,21 +100,22 @@ necessary sysinit data in Sysinit's startup data set for Sysinit to sort and dispatch a function at system startup and module load. SYSINIT() takes a uniquifier - that Sysinit uses identify the particular function dispatch + that Sysinit uses to identify the particular function dispatch data, the subsystem order, the subsystem element order, the function to call, and the data to pass the function. All functions must take a constant pointer argument. - For example: + + Example of a <literal>SYSINIT()</literal> - #include <sys/kernel.h> + #include <sys/kernel.h> void foo_null(void *unused) { foo_doo(); } -SYSINIT(foo_null, SI_SUB_FOO, SI_ORDER_FOO, NULL); +SYSINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_null, NULL); struct foo foo_voodoo = { FOO_VOODOO; @@ -115,26 +126,34 @@ struct foo *foo = (struct foo *)vdata; foo_data(foo); } -SYSINIT(foo_arg, SI_SUB_FOO, SI_ORDER_FOO, foo_voodoo); - +SYSINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_arg, foo_voodoo); + + + + Note that SI_SUB_FOO and + SI_ORDER_FOO need to be in the + sysinit_sub_id and + sysinit_elem_order enum's as mentioned above. + Either use existing ones or add your own to the enum's. Shutdown - The SYSUNINIT() macro behaves similarly + The SYSUNINIT() macro behaves similar to the SYSINIT() macro except that it adds the Sysinit data to Sysinit's shutdown data set. - For example: + + Example of a <literal>SYSUNINIT()</literal> - #include <sys/kernel.h> + #include <sys/kernel.h> void foo_cleanup(void *unused) { foo_kill(); } -SYSUNINIT(foo_cleanup, SI_SUB_FOO, SI_ORDER_FOO, NULL); +SYSUNINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_cleanup, NULL); struct foo_stack foo_stack = { FOO_STACK_VOODOO; @@ -143,8 +162,9 @@ void foo_flush(void *vdata) { } -SYSUNINIT(foo_flush, SI_SUB_FOO, SI_ORDER_FOO, foo_stack); - +SYSUNINIT(foo, SI_SUB_FOO, SI_ORDER_FOO, foo_flush, foo_stack); + + -- Ken Smith - From there to here, from here to | kensmith@cse.buffalo.edu there, funny things are everywhere. | - Theodore Geisel |