usr/src/man/man9f/mac_init_ops.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd May 31, 2016
  15 .Dt MAC_INIT_OPS 9F
  16 .Os
  17 .Sh NAME
  18 .Nm mac_init_ops ,
  19 .Nm mac_fini_ops
  20 .Nd initialize and finalize driver support for the MAC framework
  21 .Sh SYNOPSIS
  22 .In sys/mac_provider.h
  23 .Ft void
  24 .Fo mac_init_ops
  25 .Fa "struct dev_ops *ops"
  26 .Fa "const char *name"
  27 .Fc
  28 .Ft void
  29 .Fo mac_fini_ops
  30 .Fa "struct dev_ops *ops"
  31 .Fc
  32 .Sh INTERFACE LEVEL
  33 illumos DDI specific
  34 .Sh PARAMETERS
  35 .Bl -tag -width Ds
  36 .It Fa ops
  37 A pointer to the driver's
  38 .Xr dev_ops 9S
  39 structure.
  40 .It Fa name
  41 A pointer to a null-terminated string of ASCII characters that contains
  42 the name of the driver.
  43 .El
  44 .Sh DESCRIPTION
  45 The
  46 .Fn mac_init_ops
  47 and
  48 .Fn mac_fini_ops
  49 functions are used to initialize and finalize support for a device
  50 driver that implements the
  51 .Xr mac 9E
  52 networking device framework.
  53 .Pp
  54 The
  55 .Fn mac_init_ops
  56 function should be called during the driver's
  57 .Xr _init 9E
  58 entry point.
  59 As described in more detail in the
  60 .Sx Initializing MAC Support
  61 section of
  62 .Xr mac 9E ,
  63 this must be called before the driver calls
  64 .Xr mod_install 9F .
  65 If this is not done, then the call to
  66 .Xr mac_register 9F
  67 will fail.
  68 .Pp
  69 When in the driver's
  70 .Xr _fini 9E
  71 entry point, after the call to
  72 .Xr mod_remove 9F
  73 has succeeded, then the driver must call the
  74 .Fn mac_fini_ops
  75 function to finalize support and finish releasing any resources.
  76 If the call to
  77 .Xr mod_remove 9F
  78 fails, then the device driver should not call
  79 .Fn mac_fini_ops
  80 and should fail the call to
  81 .Xr _fini 9E .
  82 .Pp
  83 In addition, if the call to
  84 .Xr mod_install 9F
  85 in the driver's
  86 .Xr _init 9E
  87 entry point fails, then the driver should also call
  88 .Fn mac_fini_ops .
  89 See the example below for how this should be structured.
  90 .Sh CONTEXT
  91 The
  92 .Fn mac_init_ops
  93 function should only ever be called from the context of a driver's
  94 .Xr _init 9E
  95 entry point.
  96 .Pp
  97 The
  98 .Fn mac_fini_ops
  99 function should only ever be called from the context of a driver's
 100 .Xr _init 9E
 101 or
 102 .Xr _fini 9E
 103 entry point.
 104 .Sh RETURN VALUES
 105 The
 106 .Fn mac_init_ops
 107 and
 108 .Fn mac_fini_ops
 109 functions will always succeed.
 110 They do not have any kind of return value.
 111 .Sh EXAMPLES
 112 The following example shows how a driver would call
 113 .Fn mac_init_ops
 114 and
 115 .Fn mac_fini_ops
 116 correctly in the
 117 .Xr _init 9E
 118 and
 119 .Xr _fini 9E
 120 entry points of a driver.
 121 .Bd -literal
 122 #include <sys/modctl.h>
 123 #include <sys/ddi.h>
 124 #include <sys/sunddi.h>
 125 #include <sys/mac_provider.h>
 126
 127 /*
 128  * When using this, replace mydrv with the name of the actual device
 129  * driver. In addition, the mydrv_ prefix that is used should be
 130  * replaced with the name of the device driver
 131  */
 132 #define MYDRV_NAME      "mydrv"
 133
 134 /*
 135  * The following dev_ops structure would need to be filled in by a
 136  * proper device driver.
 137  */
 138 static struct dev_ops   mydrv_dev_ops;
 139
 140 static struct modldrv mydrv_modldrv = {
 141         &mod_driverops,
 142         MYDRV_NAME,
 143         &mydrv_dev_ops
 144 };
 145
 146 static struct modlinkage mydrv_modlinkage = {
 147         MODREV_1,
 148         &mydrv_modldrv,
 149         NULL
 150 };
 151
 152 int
 153 _init(void)
 154 {
 155         int ret;
 156
 157         /* Perform other needed initialization */
 158
 159         mac_init_ops(&mydrv_devops, MYDRV_NAME);
 160
 161         ret = mod_install(&mydrv_modlinkage);
 162         if (ret != DDI_SUCCESS) {
 163                 mac_fini_ops(&mydrv_devops);
 164                 /* Perform other needed finalization */
 165         }
 166
 167         return (ret);
 168 }
 169
 170 int
 171 _info(struct modinfo *modinfop)
 172 {
 173         return (mod_info(&mydrv_modlinkage, modinfo));
 174 }
 175
 176 int
 177 _fini(void)
 178 {
 179         int ret;
 180
 181         ret = mod_remove(&mydrv_modlinkage);
 182         if (ret == DDI_SUCCESS) {
 183                 mac_fini_ops(&mydrv_devops);
 184                 /* Perform other needed finalization */
 185         }
 186
 187         return (ret);
 188 }
 189 .Ed
 190 .Sh SEE ALSO
 191 .Xr _fini 9E ,
 192 .Xr _init 9E ,
 193 .Xr mac 9E ,
 194 .Xr mod_install 9F ,
 195 .Xr mod_remove 9F ,
 196 .Xr dev_ops 9S