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 February 15, 2020 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_callbacks = 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 = example_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