share/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, MUTEX_DRIVER, NULL);
 128
 129         if ((i = mod_install(&modlinkage)) != 0) {
 130                 mutex_destroy(&xx_global_mutex);
 131         }
 132
 133         return (i);
 134 }
 135
 136 int
 137 _info(struct modinfo *modinfop)
 138 {
 139         return (mod_info(&modlinkage, modinfop));
 140 }
 141
 142
 143 int
 144 _fini(void)
 145 {
 146         int       i;
 147
 148         /*
 149           * If mod_remove() is successful, we destroy our global mutex
 150           */
 151         if ((i = mod_remove(&modlinkage)) == 0) {
 152                  mutex_destroy(&xx_global_mutex);
 153         }
 154         return (i);
 155 }
 156 .fi
 157 .in -2
 158
 159 .SH SEE ALSO
 160 .sp
 161 .LP
 162 \fBadd_drv\fR(8), \fBmod_info\fR(9F), \fBmod_install\fR(9F),
 163 \fBmod_remove\fR(9F), \fBmutex\fR(9F), \fBmodldrv\fR(9S), \fBmodlinkage\fR(9S),
 164 \fBmodlstrmod\fR(9S)
 165 .sp
 166 .LP
 167 \fIWriting Device Drivers\fR
 168 .SH WARNINGS
 169 .sp
 170 .LP
 171 Do not change the structures referred to by the \fBmodlinkage\fR structure
 172 after the call to \fBmod_install()\fR, as the system may copy or change them.
 173 .SH NOTES
 174 .sp
 175 .LP
 176 Even though the identifiers \fB_fini()\fR, \fB_info()\fR, and \fB_init()\fR
 177 appear to be declared as globals, their scope is restricted by the kernel to
 178 the module that they are defined in.
 179 .SH BUGS
 180 .sp
 181 .LP
 182 On some implementations \fB_info()\fR may be called before \fB_init()\fR.