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