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_INIT_OPS 9F 16.Os 17.Sh NAME 18.Nm mac_init_ops , 19.Nm mac_fini_ops 20.Nd initialize and finalize driver support for the MAC framework 21.Sh SYNOPSIS 22.In sys/mac_provider.h 23.Ft void 24.Fo mac_init_ops 25.Fa "struct dev_ops *ops" 26.Fa "const char *name" 27.Fc 28.Ft void 29.Fo mac_fini_ops 30.Fa "struct dev_ops *ops" 31.Fc 32.Sh INTERFACE LEVEL 33illumos DDI specific 34.Sh PARAMETERS 35.Bl -tag -width Ds 36.It Fa ops 37A pointer to the driver's 38.Xr dev_ops 9S 39structure. 40.It Fa name 41A pointer to a null-terminated string of ASCII characters that contains 42the name of the driver. 43.El 44.Sh DESCRIPTION 45The 46.Fn mac_init_ops 47and 48.Fn mac_fini_ops 49functions are used to initialize and finalize support for a device 50driver that implements the 51.Xr mac 9E 52networking device framework. 53.Pp 54The 55.Fn mac_init_ops 56function should be called during the driver's 57.Xr _init 9E 58entry point. As described in more detail in the 59.Sx Initializing MAC Support 60section of 61.Xr mac 9E , 62this must be called before the driver calls 63.Xr mod_install 9F . 64If this is not done, then the call to 65.Xr mac_register 9F 66will fail. 67.Pp 68When in the driver's 69.Xr _fini 9E 70entry point, after the call to 71.Xr mod_remove 9F 72has succeeded, then the driver must call the 73.Fn mac_fini_ops 74function to finalize support and finish releasing any resources. If the 75call to 76.Xr mod_remove 9F 77fails, then the device driver should not call 78.Fn mac_fini_ops 79and should fail the call to 80.Xr _fini 9F . 81.Pp 82In addition, if the call to 83.Xr mod_install 9F 84in the driver's 85.Xr _init 9E 86entry point fails, then the driver should also call 87.Xr mac_fini_ops 9F . 88See the example below for how this should be structured. 89.Sh CONTEXT 90The 91.Fn mac_init_ops 92function should only ever be called from the context of a driver's 93.Xr _init 9E 94entry point. 95.Pp 96The 97.Fn mac_fini_ops 98function should only ever be called from the context of a driver's 99.Xr _init 9E 100or 101.Xr _fini 9E 102entry point. 103.Sh RETURN VALUES 104The 105.Fn mac_init_ops 106and 107.Fn mac_fini_ops 108functions will always succeed. They do not have any kind of return 109value. 110.Sh EXAMPLES 111The following example shows how a driver would call 112.Xr mac_init_ops 9F 113and 114.Xr mac_fini_ops 9F 115correctly in the 116.Xr _init 9E 117and 118.Xr _fini 9E 119entry points of a driver. 120.Bd -literal 121#include <sys/modctl.h> 122#include <sys/ddi.h> 123#include <sys/sunddi.h> 124#include <sys/mac_provider.h> 125 126/* 127 * When using this, replace mydrv with the name of the actual device 128 * driver. In addition, the mydrv_ prefix that is used should be 129 * replaced with the name of the device driver 130 */ 131#define MYDRV_NAME "mydrv" 132 133/* 134 * The following dev_ops structure would need to be filled in by a 135 * proper device driver. 136 */ 137static struct dev_ops mydrv_dev_ops; 138 139static struct modldrv mydrv_modldrv = { 140 &mod_driverops, 141 MYDRV_NAME, 142 &mydrv_dev_ops 143}; 144 145static struct modlinkage mydrv_modlinkage = { 146 MODREV_1, 147 &mydrv_modldrv, 148 NULL 149}; 150 151int 152_init(void) 153{ 154 int ret; 155 156 /* Perform other needed initialization */ 157 158 mac_init_ops(&mydrv_devops, MYDRV_NAME); 159 160 ret = mod_install(&mydrv_modlinkage); 161 if (ret != DDI_SUCCESS) { 162 mac_fini_ops(&mydrv_devops); 163 /* Perform other needed finalization */ 164 } 165 166 return (ret); 167} 168 169int 170_info(struct modinfo *modinfop) 171{ 172 return (mod_info(&mydrv_modlinkage, modinfo)); 173} 174 175int 176_fini(void) 177{ 178 int ret; 179 180 ret = mod_remove(&mydrv_modlinkage); 181 if (ret == DDI_SUCCESS) { 182 mac_fini_ops(&mydrv_devops); 183 /* Perform other needed finalization */ 184 } 185 186 return (ret); 187} 188.Ed 189.Sh SEE ALSO 190.Xr _fini 9E , 191.Xr _init 9E , 192.Xr mac 9E , 193.Xr mod_install 9F , 194.Xr mod_remove 9F , 195.Xr dev_ops 9S 196