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 33illumos DDI specific 34.Sh PARAMETERS 35.Bl -tag -width Fa 36.It Fa mregp 37A pointer to a 38.Xr mac_register 9S 39structure allocated by calling 40.Xr mac_alloc 9F 41and filled in by the device driver. 42.It Fa mhp 43A pointer to a driver-backed handle to the MAC framework. 44.It Fa mh 45The driver-backed handle to the MAC framework. 46.El 47.Sh DESCRIPTION 48The 49.Fn mac_register 50function is used to register an instance of a device driver with the 51.Xr mac 9E 52framework. 53Upon successfully calling the 54.Fn mac_register 55function, the device will start having its 56.Xr mac_callbacks 9S 57entry points called. 58The device driver should call this function during it's 59.Xr attach 9E 60entry point after the device has been configured and is set up. 61For a more detailed explanation of the exact steps that the device driver 62should take and where in the sequence of a driver's 63.Xr attach 9E 64entry point this function should be called, see the 65.Sx Registering with MAC 66section of 67.Xr mac 9E . 68.Pp 69The driver should provide a pointer to a 70.Ft mac_handle_t 71structure as the second argument to the 72.Fn mac_register 73function. 74This handle will be used when the device driver needs to interact with the 75framework in various ways throughout its life. 76It is also where the driver gets the 77.Fa mh 78argument for calling the 79.Fn mac_unregister 80function. 81It is recommended that the device driver keep the handle around in its soft 82state structure for a given instance. 83.Pp 84If the call to the 85.Fn mac_register 86function fails, the device driver should unwind its 87.Xr attach 9E 88entry point, tear down everything that it initialized, and ultimately 89return an error from its 90.Xr attach 9E 91entry point. 92.Pp 93If the 94.Xr attach 9E 95routine fails for some reason after the call to the 96.Fn mac_register 97function has succeeded, then the driver should call the 98.Fn mac_unregister 99function as part of unwinding all of its state. 100.Pp 101When a driver is in its 102.Xr detach 9E 103entry point, it should call the 104.Fn mac_unregister 105function immediately after draining any of its transmit and receive 106resources that might have been given to the rest of the operating system 107through DMA binding. 108See the 109.Sx MBLKS AND DMA 110section of 111.Xr mac 9E 112for more information. 113This should be done before the driver does any tearing down. 114The call to the 115.Fn mac_unregister 116function may fail. 117This may happen because the networking stack is still using the device. 118In such a case, the driver should fail the call to 119.Xr detach 9E 120and return 121.Sy DDI_FAILURE . 122.Sh CONTEXT 123The 124.Fn mac_register 125function is generally only called from a driver's 126.Xr attach 9E 127entry point. 128The 129.Fn mac_unregister 130function is generally only called from a driver's 131.Xr attach 9E 132and 133.Xr detach 9E 134entry point. 135However, both functions may be called from either 136.Sy user 137or 138.Sy kernel 139context. 140.Sh RETURN VALUES 141Upon successful completion, the 142.Fn mac_register 143and 144.Fn mac_unregister 145functions both return 146.Sy 0 . 147Otherwise, they return an error number. 148.Sh EXAMPLES 149The following example shows how a device driver might call the 150.Fn mac_register 151function. 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 166static char *example_priv_props[] = { 167 "_rx_intr_throttle", 168 "_tx_intr_throttle", 169 NULL 170}; 171 172static 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 188static boolean_t 189example_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 215The 216.Fn mac_register 217function may fail if: 218.Bl -tag -width Er 219.It EEXIST 220A driver with the same name and instance already exists. 221.It EINVAL 222There was something invalid with the device's registration information. 223Some of the following reasons may apply, this list is not exhaustive: 224.Bl -bullet 225.It 226The 227.Xr mac_init_ops 9F 228function was not called. 229.It 230The specified mac plugin does not exist. 231.It 232An invalid minor number was used. 233.It 234The default unicast source address was incorrect. 235.It 236The plugin specific private data was incorrect or missing. 237.It 238Plugin specific data was provided when none is required. 239.It 240Required callback functions are not specified. 241.It 242The system was unable to properly create minor nodes. 243.El 244.It ENOSPC 245The 246.Xr mac 9E 247framework was unable to allocate a minor number for the device as they 248have all been exhausted. 249.El 250.Pp 251The 252.Fn mac_unregister 253function will fail if: 254.Bl -tag -width Er 255.It Er EBUSY 256The device is still in use. 257.It Er ENOTEMPTY 258The flow table is not empty. 259.El 260.Pp 261Note the set of errors for both the 262.Fn mac_regster 263and 264.Fn mac_unregister 265functions are not set in stone and may be expanded in future revisions. 266In general, all errors should be handled by the device driver in similar 267ways 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 276