share/man/man9f/mac_register.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 (c) 2017, Joyent, Inc.
  13 .\"
  14 .Dd September 22, 2017
  15 .Dt MAC_REGISTER 9F
  16 .Os
  17 .Sh NAME
  18 .Nm mac_register ,
  19 .Nm mac_unregister
  20 .Nd register and unregister a device driver from the MAC framework
  21 .Sh SYNOPSIS
  22 .In sys/mac_provider.h
  23 .Ft int
  24 .Fo mac_register
  25 .Fa "mac_register_t *mregp"
  26 .Fa "mac_handle_t *mhp"
  27 .Fc
  28 .Ft int
  29 .Fo mac_unregister
  30 .Fa "mac_handle_t mh"
  31 .Fc
  32 .Sh INTERFACE LEVEL
  33 illumos DDI specific
  34 .Sh PARAMETERS
  35 .Bl -tag -width Fa
  36 .It Fa mregp
  37 A pointer to a
  38 .Xr mac_register 9S
  39 structure allocated by calling
  40 .Xr mac_alloc 9F
  41 and filled in by the device driver.
  42 .It Fa mhp
  43 A pointer to a driver-backed handle to the MAC framework.
  44 .It Fa mh
  45 The driver-backed handle to the MAC framework.
  46 .El
  47 .Sh DESCRIPTION
  48 The
  49 .Fn mac_register
  50 function is used to register an instance of a device driver with the
  51 .Xr mac 9E
  52 framework.
  53 Upon successfully calling the
  54 .Fn mac_register
  55 function, the device will start having its
  56 .Xr mac_callbacks 9S
  57 entry points called.
  58 The device driver should call this function during it's
  59 .Xr attach 9E
  60 entry point after the device has been configured and is set up.
  61 For a more detailed explanation of the exact steps that the device driver
  62 should take and where in the sequence of a driver's
  63 .Xr attach 9E
  64 entry point this function should be called, see the
  65 .Sx Registering with MAC
  66 section of
  67 .Xr mac 9E .
  68 .Pp
  69 The driver should provide a pointer to a
  70 .Ft mac_handle_t
  71 structure as the second argument to the
  72 .Fn mac_register
  73 function.
  74 This handle will be used when the device driver needs to interact with the
  75 framework in various ways throughout its life.
  76 It is also where the driver gets the
  77 .Fa mh
  78 argument for calling the
  79 .Fn mac_unregister
  80 function.
  81 It is recommended that the device driver keep the handle around in its soft
  82 state structure for a given instance.
  83 .Pp
  84 If the call to the
  85 .Fn mac_register
  86 function fails, the device driver should unwind its
  87 .Xr attach 9E
  88 entry point, tear down everything that it initialized, and ultimately
  89 return an error from its
  90 .Xr attach 9E
  91 entry point.
  92 .Pp
  93 If the
  94 .Xr attach 9E
  95 routine fails for some reason after the call to the
  96 .Fn mac_register
  97 function has succeeded, then the driver should call the
  98 .Fn mac_unregister
  99 function as part of unwinding all of its state.
 100 .Pp
 101 When a driver is in its
 102 .Xr detach 9E
 103 entry point, it should call the
 104 .Fn mac_unregister
 105 function immediately after draining any of its transmit and receive
 106 resources that might have been given to the rest of the operating system
 107 through DMA binding.
 108 See the
 109 .Sx MBLKS AND DMA
 110 section of
 111 .Xr mac 9E
 112 for more information.
 113 This should be done before the driver does any tearing down.
 114 The call to the
 115 .Fn mac_unregister
 116 function may fail.
 117 This may happen because the networking stack is still using the device.
 118 In such a case, the driver should fail the call to
 119 .Xr detach 9E
 120 and return
 121 .Sy DDI_FAILURE .
 122 .Sh CONTEXT
 123 The
 124 .Fn mac_register
 125 function is generally only called from a driver's
 126 .Xr attach 9E
 127 entry point.
 128 The
 129 .Fn mac_unregister
 130 function is generally only called from a driver's
 131 .Xr attach 9E
 132 and
 133 .Xr detach 9E
 134 entry point.
 135 However, both functions may be called from either
 136 .Sy user
 137 or
 138 .Sy kernel
 139 context.
 140 .Sh RETURN VALUES
 141 Upon successful completion, the
 142 .Fn mac_register
 143 and
 144 .Fn mac_unregister
 145 functions both return
 146 .Sy 0 .
 147 Otherwise, they return an error number.
 148 .Sh EXAMPLES
 149 The following example shows how a device driver might call the
 150 .Fn mac_register
 151 function.
 152 .Bd -literal
 153 #include <sys/mac_provider.h>
 154 #include <sys/mac_ether.h>
 155
 156 /*
 157  * The call to mac_register(9F) generally comes from the context of
 158  * attach(9E). This function encapsulates setting up and initializing
 159  * the mac_register_t structure and should be assumed to be called from
 160  * attach.
 161  *
 162  * The exact set of callbacks and private properties will vary based
 163  * upon the driver.
 164  */
 165
 166 static char *example_priv_props[] = {
 167         "_rx_intr_throttle",
 168         "_tx_intr_throttle",
 169         NULL
 170 };
 171
 172 static mac_callbacks_t example_m_callbacks = {
 173         .mc_callbacsk = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO |
 174             MC_IOCTL,
 175         .mc_start = example_m_start,
 176         .mc_stop = example_m_stop,
 177         .mc_setpromisc = example_m_setpromisc,
 178         .mc_multicst = example_m_multicst,
 179         .mc_unicst = example_m_unicst,
 180         .mc_tx = example_m_tx,
 181         .mc_ioctl = example_m_ioctl,
 182         .mc_getcapab = example_m_getcapab,
 183         .mc_getprop = example_m_getprop,
 184         .mc_setprop = example_m_setprop,
 185         .mc_propinfo = example_m_propinfo
 186 };
 187
 188 static boolean_t
 189 example_register_mac(example_t *ep)
 190 {
 191         int status;
 192         mac_register_t *mac;
 193
 194         mac = mac_alloc(MAC_VERSION);
 195         if (mac == NULL)
 196                 return (B_FALSE);
 197
 198         mac->m_type_ident = MAC_PLUGIN_IDENT_ETHER;
 199         mac->m_driver = ep;
 200         mac->m_dip = ep->ep_dev_info;
 201         mac->m_src_addr = ep->ep_mac_addr;
 202         mac->m_callbacks = &example_m_callbacks;
 203         mac->m_min_sdu = 0;
 204         mac->m_max_sdu = ep->ep_sdu;
 205         mac->m_margin = VLAN_TAGSZ;
 206         mac->m_priv_props = exmple_priv_props;
 207
 208         status = mac_register(mac, &ep->ep_mac_hdl);
 209         mac_free(mac);
 210
 211         return (status == 0);
 212 }
 213 .Ed
 214 .Sh ERRORS
 215 The
 216 .Fn mac_register
 217 function may fail if:
 218 .Bl -tag -width Er
 219 .It EEXIST
 220 A driver with the same name and instance already exists.
 221 .It EINVAL
 222 There was something invalid with the device's registration information.
 223 Some of the following reasons may apply, this list is not exhaustive:
 224 .Bl -bullet
 225 .It
 226 The
 227 .Xr mac_init_ops 9F
 228 function was not called.
 229 .It
 230 The specified mac plugin does not exist.
 231 .It
 232 An invalid minor number was used.
 233 .It
 234 The default unicast source address was incorrect.
 235 .It
 236 The plugin specific private data was incorrect or missing.
 237 .It
 238 Plugin specific data was provided when none is required.
 239 .It
 240 Required callback functions are not specified.
 241 .It
 242 The system was unable to properly create minor nodes.
 243 .El
 244 .It ENOSPC
 245 The
 246 .Xr mac 9E
 247 framework was unable to allocate a minor number for the device as they
 248 have all been exhausted.
 249 .El
 250 .Pp
 251 The
 252 .Fn mac_unregister
 253 function will fail if:
 254 .Bl -tag -width Er
 255 .It Er EBUSY
 256 The device is still in use.
 257 .It Er ENOTEMPTY
 258 The flow table is not empty.
 259 .El
 260 .Pp
 261 Note the set of errors for both the
 262 .Fn mac_regster
 263 and
 264 .Fn mac_unregister
 265 functions are not set in stone and may be expanded in future revisions.
 266 In general, all errors should be handled by the device driver in similar
 267 ways for these functions.
 268 .Sh SEE ALSO
 269 .Xr attach 9E ,
 270 .Xr detach 9E ,
 271 .Xr mac 9E ,
 272 .Xr mac_alloc 9F ,
 273 .Xr mac_init_ops 9F ,
 274 .Xr mac_callbacks 9S ,
 275 .Xr mac_register 9S