152d2369aSRobert Mustacchi.\" 252d2369aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 352d2369aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 452d2369aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 552d2369aSRobert Mustacchi.\" 1.0 of the CDDL. 652d2369aSRobert Mustacchi.\" 752d2369aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 852d2369aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 952d2369aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1052d2369aSRobert Mustacchi.\" 1152d2369aSRobert Mustacchi.\" 12*3815c12aSRobert Mustacchi.\" Copyright (c) 2017, Joyent, Inc. 1352d2369aSRobert Mustacchi.\" 14*3815c12aSRobert Mustacchi.Dd September 22, 2017 1552d2369aSRobert Mustacchi.Dt MAC_REGISTER 9F 1652d2369aSRobert Mustacchi.Os 1752d2369aSRobert Mustacchi.Sh NAME 1852d2369aSRobert Mustacchi.Nm mac_register , 1952d2369aSRobert Mustacchi.Nm mac_unregister 2052d2369aSRobert Mustacchi.Nd register and unregister a device driver from the MAC framework 2152d2369aSRobert Mustacchi.Sh SYNOPSIS 2252d2369aSRobert Mustacchi.In sys/mac_provider.h 2352d2369aSRobert Mustacchi.Ft int 2452d2369aSRobert Mustacchi.Fo mac_register 2552d2369aSRobert Mustacchi.Fa "mac_register_t *mregp" 2652d2369aSRobert Mustacchi.Fa "mac_handle_t *mhp" 2752d2369aSRobert Mustacchi.Fc 2852d2369aSRobert Mustacchi.Ft int 2952d2369aSRobert Mustacchi.Fo mac_unregister 3052d2369aSRobert Mustacchi.Fa "mac_handle_t mh" 3152d2369aSRobert Mustacchi.Fc 3252d2369aSRobert Mustacchi.Sh INTERFACE LEVEL 3352d2369aSRobert Mustacchiillumos DDI specific 3452d2369aSRobert Mustacchi.Sh PARAMETERS 3552d2369aSRobert Mustacchi.Bl -tag -width Fa 3652d2369aSRobert Mustacchi.It Fa mregp 3752d2369aSRobert MustacchiA pointer to a 3852d2369aSRobert Mustacchi.Xr mac_register 9S 3952d2369aSRobert Mustacchistructure allocated by calling 4052d2369aSRobert Mustacchi.Xr mac_alloc 9F 4152d2369aSRobert Mustacchiand filled in by the device driver. 4252d2369aSRobert Mustacchi.It Fa mhp 4352d2369aSRobert MustacchiA pointer to a driver-backed handle to the MAC framework. 4452d2369aSRobert Mustacchi.It Fa mh 4552d2369aSRobert MustacchiThe driver-backed handle to the MAC framework. 4652d2369aSRobert Mustacchi.El 4752d2369aSRobert Mustacchi.Sh DESCRIPTION 4852d2369aSRobert MustacchiThe 4952d2369aSRobert Mustacchi.Fn mac_register 5052d2369aSRobert Mustacchifunction is used to register an instance of a device driver with the 5152d2369aSRobert Mustacchi.Xr mac 9E 5272d3dbb9SYuri Pankovframework. 5372d3dbb9SYuri PankovUpon successfully calling the 5452d2369aSRobert Mustacchi.Fn mac_register 5552d2369aSRobert Mustacchifunction, the device will start having its 5652d2369aSRobert Mustacchi.Xr mac_callbacks 9S 5772d3dbb9SYuri Pankoventry points called. 5872d3dbb9SYuri PankovThe device driver should call this function during it's 5952d2369aSRobert Mustacchi.Xr attach 9E 6072d3dbb9SYuri Pankoventry point after the device has been configured and is set up. 6172d3dbb9SYuri PankovFor a more detailed explanation of the exact steps that the device driver 6252d2369aSRobert Mustacchishould take and where in the sequence of a driver's 6352d2369aSRobert Mustacchi.Xr attach 9E 6452d2369aSRobert Mustacchientry point this function should be called, see the 6552d2369aSRobert Mustacchi.Sx Registering with MAC 6652d2369aSRobert Mustacchisection of 6752d2369aSRobert Mustacchi.Xr mac 9E . 6852d2369aSRobert Mustacchi.Pp 6952d2369aSRobert MustacchiThe driver should provide a pointer to a 7052d2369aSRobert Mustacchi.Ft mac_handle_t 7152d2369aSRobert Mustacchistructure as the second argument to the 7252d2369aSRobert Mustacchi.Fn mac_register 7372d3dbb9SYuri Pankovfunction. 7472d3dbb9SYuri PankovThis handle will be used when the device driver needs to interact with the 7572d3dbb9SYuri Pankovframework in various ways throughout its life. 7672d3dbb9SYuri PankovIt is also where the driver gets the 7752d2369aSRobert Mustacchi.Fa mh 7852d2369aSRobert Mustacchiargument for calling the 7952d2369aSRobert Mustacchi.Fn mac_unregister 8072d3dbb9SYuri Pankovfunction. 8172d3dbb9SYuri PankovIt is recommended that the device driver keep the handle around in its soft 8272d3dbb9SYuri Pankovstate structure for a given instance. 8352d2369aSRobert Mustacchi.Pp 8452d2369aSRobert MustacchiIf the call to the 8552d2369aSRobert Mustacchi.Fn mac_register 8652d2369aSRobert Mustacchifunction fails, the device driver should unwind its 8752d2369aSRobert Mustacchi.Xr attach 9E 8852d2369aSRobert Mustacchientry point, tear down everything that it initialized, and ultimately 8952d2369aSRobert Mustacchireturn an error from its 9052d2369aSRobert Mustacchi.Xr attach 9E 9152d2369aSRobert Mustacchientry point. 9252d2369aSRobert Mustacchi.Pp 9352d2369aSRobert MustacchiIf the 9452d2369aSRobert Mustacchi.Xr attach 9E 9552d2369aSRobert Mustacchiroutine fails for some reason after the call to the 9652d2369aSRobert Mustacchi.Fn mac_register 9752d2369aSRobert Mustacchifunction has succeeded, then the driver should call the 9852d2369aSRobert Mustacchi.Fn mac_unregister 9952d2369aSRobert Mustacchifunction as part of unwinding all of its state. 10052d2369aSRobert Mustacchi.Pp 10152d2369aSRobert MustacchiWhen a driver is in its 10252d2369aSRobert Mustacchi.Xr detach 9E 10352d2369aSRobert Mustacchientry point, it should call the 10452d2369aSRobert Mustacchi.Fn mac_unregister 10552d2369aSRobert Mustacchifunction immediately after draining any of its transmit and receive 10652d2369aSRobert Mustacchiresources that might have been given to the rest of the operating system 10772d3dbb9SYuri Pankovthrough DMA binding. 10872d3dbb9SYuri PankovSee the 10952d2369aSRobert Mustacchi.Sx MBLKS AND DMA 11052d2369aSRobert Mustacchisection of 11152d2369aSRobert Mustacchi.Xr mac 9E 11272d3dbb9SYuri Pankovfor more information. 11372d3dbb9SYuri PankovThis should be done before the driver does any tearing down. 11472d3dbb9SYuri PankovThe call to the 11552d2369aSRobert Mustacchi.Fn mac_unregister 11672d3dbb9SYuri Pankovfunction may fail. 11772d3dbb9SYuri PankovThis may happen because the networking stack is still using the device. 11872d3dbb9SYuri PankovIn such a case, the driver should fail the call to 11952d2369aSRobert Mustacchi.Xr detach 9E 12052d2369aSRobert Mustacchiand return 12152d2369aSRobert Mustacchi.Sy DDI_FAILURE . 12252d2369aSRobert Mustacchi.Sh CONTEXT 12352d2369aSRobert MustacchiThe 12452d2369aSRobert Mustacchi.Fn mac_register 12552d2369aSRobert Mustacchifunction is generally only called from a driver's 12652d2369aSRobert Mustacchi.Xr attach 9E 12772d3dbb9SYuri Pankoventry point. 12872d3dbb9SYuri PankovThe 12952d2369aSRobert Mustacchi.Fn mac_unregister 13052d2369aSRobert Mustacchifunction is generally only called from a driver's 13152d2369aSRobert Mustacchi.Xr attach 9E 13252d2369aSRobert Mustacchiand 13352d2369aSRobert Mustacchi.Xr detach 9E 13472d3dbb9SYuri Pankoventry point. 13572d3dbb9SYuri PankovHowever, both functions may be called from either 13652d2369aSRobert Mustacchi.Sy user 13752d2369aSRobert Mustacchior 13852d2369aSRobert Mustacchi.Sy kernel 13952d2369aSRobert Mustacchicontext. 14052d2369aSRobert Mustacchi.Sh RETURN VALUES 14152d2369aSRobert MustacchiUpon successful completion, the 14252d2369aSRobert Mustacchi.Fn mac_register 14352d2369aSRobert Mustacchiand 14452d2369aSRobert Mustacchi.Fn mac_unregister 14552d2369aSRobert Mustacchifunctions both return 14652d2369aSRobert Mustacchi.Sy 0 . 14752d2369aSRobert MustacchiOtherwise, they return an error number. 14852d2369aSRobert Mustacchi.Sh EXAMPLES 14952d2369aSRobert MustacchiThe following example shows how a device driver might call the 15052d2369aSRobert Mustacchi.Fn mac_register 15152d2369aSRobert Mustacchifunction. 15252d2369aSRobert Mustacchi.Bd -literal 15352d2369aSRobert Mustacchi#include <sys/mac_provider.h> 15452d2369aSRobert Mustacchi#include <sys/mac_ether.h> 15552d2369aSRobert Mustacchi 15652d2369aSRobert Mustacchi/* 15752d2369aSRobert Mustacchi * The call to mac_register(9F) generally comes from the context of 15852d2369aSRobert Mustacchi * attach(9E). This function encapsulates setting up and initializing 15952d2369aSRobert Mustacchi * the mac_register_t structure and should be assumed to be called from 16052d2369aSRobert Mustacchi * attach. 16152d2369aSRobert Mustacchi * 16252d2369aSRobert Mustacchi * The exact set of callbacks and private properties will vary based 16352d2369aSRobert Mustacchi * upon the driver. 16452d2369aSRobert Mustacchi */ 16552d2369aSRobert Mustacchi 16652d2369aSRobert Mustacchistatic char *example_priv_props[] = { 16752d2369aSRobert Mustacchi "_rx_intr_throttle", 16852d2369aSRobert Mustacchi "_tx_intr_throttle", 16952d2369aSRobert Mustacchi NULL 17052d2369aSRobert Mustacchi}; 17152d2369aSRobert Mustacchi 17252d2369aSRobert Mustacchistatic mac_callbacks_t example_m_callbacks = { 17352d2369aSRobert Mustacchi .mc_callbacsk = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO | 17452d2369aSRobert Mustacchi MC_IOCTL, 17552d2369aSRobert Mustacchi .mc_start = example_m_start, 17652d2369aSRobert Mustacchi .mc_stop = example_m_stop, 17752d2369aSRobert Mustacchi .mc_setpromisc = example_m_setpromisc, 17852d2369aSRobert Mustacchi .mc_multicst = example_m_multicst, 17952d2369aSRobert Mustacchi .mc_unicst = example_m_unicst, 18052d2369aSRobert Mustacchi .mc_tx = example_m_tx, 18152d2369aSRobert Mustacchi .mc_ioctl = example_m_ioctl, 18252d2369aSRobert Mustacchi .mc_getcapab = example_m_getcapab, 18352d2369aSRobert Mustacchi .mc_getprop = example_m_getprop, 18452d2369aSRobert Mustacchi .mc_setprop = example_m_setprop, 18552d2369aSRobert Mustacchi .mc_propinfo = example_m_propinfo 18652d2369aSRobert Mustacchi}; 18752d2369aSRobert Mustacchi 18852d2369aSRobert Mustacchistatic boolean_t 18952d2369aSRobert Mustacchiexample_register_mac(example_t *ep) 19052d2369aSRobert Mustacchi{ 19152d2369aSRobert Mustacchi int status; 19252d2369aSRobert Mustacchi mac_register_t *mac; 19352d2369aSRobert Mustacchi 19452d2369aSRobert Mustacchi mac = mac_alloc(MAC_VERSION); 19552d2369aSRobert Mustacchi if (mac == NULL) 19652d2369aSRobert Mustacchi return (B_FALSE); 19752d2369aSRobert Mustacchi 198*3815c12aSRobert Mustacchi mac->m_type_ident = MAC_PLUGIN_IDENT_ETHER; 19952d2369aSRobert Mustacchi mac->m_driver = ep; 20052d2369aSRobert Mustacchi mac->m_dip = ep->ep_dev_info; 20152d2369aSRobert Mustacchi mac->m_src_addr = ep->ep_mac_addr; 20252d2369aSRobert Mustacchi mac->m_callbacks = &example_m_callbacks; 20352d2369aSRobert Mustacchi mac->m_min_sdu = 0; 20452d2369aSRobert Mustacchi mac->m_max_sdu = ep->ep_sdu; 20552d2369aSRobert Mustacchi mac->m_margin = VLAN_TAGSZ; 20652d2369aSRobert Mustacchi mac->m_priv_props = exmple_priv_props; 20752d2369aSRobert Mustacchi 20852d2369aSRobert Mustacchi status = mac_register(mac, &ep->ep_mac_hdl); 20952d2369aSRobert Mustacchi mac_free(mac); 21052d2369aSRobert Mustacchi 21152d2369aSRobert Mustacchi return (status == 0); 21252d2369aSRobert Mustacchi} 21352d2369aSRobert Mustacchi.Ed 21452d2369aSRobert Mustacchi.Sh ERRORS 21552d2369aSRobert MustacchiThe 21652d2369aSRobert Mustacchi.Fn mac_register 21752d2369aSRobert Mustacchifunction may fail if: 21852d2369aSRobert Mustacchi.Bl -tag -width Er 21952d2369aSRobert Mustacchi.It EEXIST 22052d2369aSRobert MustacchiA driver with the same name and instance already exists. 22152d2369aSRobert Mustacchi.It EINVAL 22252d2369aSRobert MustacchiThere was something invalid with the device's registration information. 22352d2369aSRobert MustacchiSome of the following reasons may apply, this list is not exhaustive: 22452d2369aSRobert Mustacchi.Bl -bullet 22552d2369aSRobert Mustacchi.It 22652d2369aSRobert MustacchiThe 22752d2369aSRobert Mustacchi.Xr mac_init_ops 9F 22852d2369aSRobert Mustacchifunction was not called. 22952d2369aSRobert Mustacchi.It 23052d2369aSRobert MustacchiThe specified mac plugin does not exist. 23152d2369aSRobert Mustacchi.It 23252d2369aSRobert MustacchiAn invalid minor number was used. 23352d2369aSRobert Mustacchi.It 23452d2369aSRobert MustacchiThe default unicast source address was incorrect. 23552d2369aSRobert Mustacchi.It 23652d2369aSRobert MustacchiThe plugin specific private data was incorrect or missing. 23752d2369aSRobert Mustacchi.It 23852d2369aSRobert MustacchiPlugin specific data was provided when none is required. 23952d2369aSRobert Mustacchi.It 24052d2369aSRobert MustacchiRequired callback functions are not specified. 24152d2369aSRobert Mustacchi.It 24252d2369aSRobert MustacchiThe system was unable to properly create minor nodes. 24352d2369aSRobert Mustacchi.El 24452d2369aSRobert Mustacchi.It ENOSPC 24552d2369aSRobert MustacchiThe 24652d2369aSRobert Mustacchi.Xr mac 9E 24752d2369aSRobert Mustacchiframework was unable to allocate a minor number for the device as they 24852d2369aSRobert Mustacchihave all been exhausted. 24952d2369aSRobert Mustacchi.El 25052d2369aSRobert Mustacchi.Pp 25152d2369aSRobert MustacchiThe 25252d2369aSRobert Mustacchi.Fn mac_unregister 25352d2369aSRobert Mustacchifunction will fail if: 25452d2369aSRobert Mustacchi.Bl -tag -width Er 25552d2369aSRobert Mustacchi.It Er EBUSY 25652d2369aSRobert MustacchiThe device is still in use. 25752d2369aSRobert Mustacchi.It Er ENOTEMPTY 25852d2369aSRobert MustacchiThe flow table is not empty. 25952d2369aSRobert Mustacchi.El 26052d2369aSRobert Mustacchi.Pp 26152d2369aSRobert MustacchiNote the set of errors for both the 26252d2369aSRobert Mustacchi.Fn mac_regster 26352d2369aSRobert Mustacchiand 26452d2369aSRobert Mustacchi.Fn mac_unregister 26552d2369aSRobert Mustacchifunctions are not set in stone and may be expanded in future revisions. 26652d2369aSRobert MustacchiIn general, all errors should be handled by the device driver in similar 26752d2369aSRobert Mustacchiways for these functions. 26852d2369aSRobert Mustacchi.Sh SEE ALSO 26952d2369aSRobert Mustacchi.Xr attach 9E , 27052d2369aSRobert Mustacchi.Xr detach 9E , 27152d2369aSRobert Mustacchi.Xr mac 9E , 27252d2369aSRobert Mustacchi.Xr mac_alloc 9F , 27352d2369aSRobert Mustacchi.Xr mac_init_ops 9F , 27452d2369aSRobert Mustacchi.Xr mac_callbacks 9S , 27552d2369aSRobert Mustacchi.Xr mac_register 9S 276