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