usr/src/man/man9e/_fini.9e

   1 '\" te
   2 .\"  Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH _FINI 9E "Jan 22, 2002"
   7 .SH NAME
   8 _fini, _info, _init \- loadable module configuration entry points
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/modctl.h>
  13
  14
  15
  16 \fBint\fR \fB_fini\fR(void)
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fB_info\fR(\fBstruct modinfo *\fR\fImodinfop\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fB_init\fR(void)
  27 .fi
  28
  29 .SH INTERFACE LEVEL
  30 .sp
  31 .LP
  32 Solaris DDI specific (Solaris DDI). These entry points are required. You must
  33 write them.
  34 .SH PARAMETERS
  35 .SS "_info(\|)"
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fImodinfop\fR \fR
  40 .ad
  41 .RS 13n
  42 A pointer to an opaque \fBmodinfo\fR structure.
  43 .RE
  44
  45 .SH DESCRIPTION
  46 .sp
  47 .LP
  48 \fB_init()\fR initializes a loadable module. It is called before any other
  49 routine in a loadable module. \fB_init()\fR returns the value returned by
  50 \fBmod_install\fR(9F). The module may optionally perform some other work before
  51 the \fBmod_install\fR(9F) call is performed. If the module has done some setup
  52 before the \fBmod_install\fR(9F) function is called, then it should be prepared
  53 to undo that setup if \fBmod_install\fR(9F) returns an error.
  54 .sp
  55 .LP
  56 \fB_info()\fR returns information about a loadable module. \fB_info()\fR
  57 returns the value returned by \fBmod_info\fR(9F).
  58 .sp
  59 .LP
  60 \fB_fini()\fR prepares a loadable module for unloading. It is called when the
  61 system wants to unload a module. If the module determines that it can be
  62 unloaded, then \fB_fini()\fR returns the value returned by
  63 \fBmod_remove\fR(9F). Upon successful return from \fB_fini()\fR no other
  64 routine in the module will be called before \fB_init()\fR is called.
  65 .SH RETURN VALUES
  66 .sp
  67 .LP
  68 \fB_init()\fR should return the appropriate error number if there is an error,
  69 otherwise it should return the return value from \fBmod_install\fR(9F).
  70 .sp
  71 .LP
  72 \fB_info()\fR should return the return value from \fBmod_info\fR(9F)
  73 .sp
  74 .LP
  75 \fB_fini()\fR should return the return value from \fBmod_remove\fR(9F).
  76 \fB_fini()\fR is permitted to return \fBEBUSY\fR prior to calling
  77 \fBmod_remove\fR(9F) if the driver should not be unloaded. Driver global
  78 resources, such as mutexes and calls to \fBddi_soft_state_fini\fR(9F), should
  79 only be destroyed in \fB_fini()\fR after \fBmod_remove()\fR returns
  80 successfully.
  81 .SH EXAMPLES
  82 .LP
  83 \fBExample 1 \fRInitializing and Freeing a Mutex
  84 .sp
  85 .LP
  86 The following example demonstrates how to initialize and free a
  87 \fBmutex\fR(9F).
  88
  89 .sp
  90 .in +2
  91 .nf
  92 #include <sys/modctl.h>
  93 #include <sys/ddi.h>
  94 #include <sys/sunddi.h>
  95 static struct dev_ops  drv_ops;
  96 /*
  97  * Module linkage information for the kernel.
  98  */
  99 static struct modldrv modldrv = {
 100      &mod_driverops,     /* Type of module.  This one is a driver */
 101     "Sample Driver",
 102     &drv_ops       /* driver ops */
 103 };
 104
 105 static struct modlinkage modlinkage = {
 106         MODREV_1,
 107         &modldrv,
 108         NULL
 109 };
 110
 111
 112 /*
 113  * Global driver mutex
 114  */
 115 static kmutex_t   xx_global_mutex;
 116
 117
 118 int
 119 _init(void)
 120 {
 121         int     i;
 122
 123         /*
 124           * Initialize global mutex before mod_install'ing driver.
 125           * If mod_install() fails, must clean up mutex initialization
 126           */
 127         mutex_init(&xx_global_mutex, NULL,
 128                 MUTEX_DRIVER, (void *)NULL);
 129
 130         if ((i = mod_install(&modlinkage)) != 0) {
 131                 mutex_destroy(&xx_global_mutex);
 132         }
 133
 134         return (i);
 135 }
 136
 137 int
 138 _info(struct modinfo *modinfop)
 139 {
 140         return (mod_info(&modlinkage, modinfop));
 141 }
 142
 143
 144 int
 145 _fini(void)
 146 {
 147         int       i;
 148
 149         /*
 150           * If mod_remove() is successful, we destroy our global mutex
 151           */
 152         if ((i = mod_remove(&modlinkage)) == 0) {
 153                  mutex_destroy(&xx_global_mutex);
 154         }
 155         return (i);
 156 }
 157 .fi
 158 .in -2
 159
 160 .SH SEE ALSO
 161 .sp
 162 .LP
 163 \fBadd_drv\fR(1M), \fBmod_info\fR(9F), \fBmod_install\fR(9F),
 164 \fBmod_remove\fR(9F), \fBmutex\fR(9F), \fBmodldrv\fR(9S), \fBmodlinkage\fR(9S),
 165 \fBmodlstrmod\fR(9S)
 166 .sp
 167 .LP
 168 \fIWriting Device Drivers\fR
 169 .SH WARNINGS
 170 .sp
 171 .LP
 172 Do not change the structures referred to by the \fBmodlinkage\fR structure
 173 after the call to \fBmod_install()\fR, as the system may copy or change them.
 174 .SH NOTES
 175 .sp
 176 .LP
 177 Even though the identifiers \fB_fini()\fR, \fB_info()\fR, and \fB_init()\fR
 178 appear to be declared as globals, their scope is restricted by the kernel to
 179 the module that they are defined in.
 180 .SH BUGS
 181 .sp
 182 .LP
 183 On some implementations \fB_info()\fR may be called before \fB_init()\fR.