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. 59As described in more detail in the 60.Sx Initializing MAC Support 61section of 62.Xr mac 9E , 63this must be called before the driver calls 64.Xr mod_install 9F . 65If this is not done, then the call to 66.Xr mac_register 9F 67will fail. 68.Pp 69When in the driver's 70.Xr _fini 9E 71entry point, after the call to 72.Xr mod_remove 9F 73has succeeded, then the driver must call the 74.Fn mac_fini_ops 75function to finalize support and finish releasing any resources. 76If the call to 77.Xr mod_remove 9F 78fails, then the device driver should not call 79.Fn mac_fini_ops 80and should fail the call to 81.Xr _fini 9E . 82.Pp 83In addition, if the call to 84.Xr mod_install 9F 85in the driver's 86.Xr _init 9E 87entry point fails, then the driver should also call 88.Fn mac_fini_ops . 89See the example below for how this should be structured. 90.Sh CONTEXT 91The 92.Fn mac_init_ops 93function should only ever be called from the context of a driver's 94.Xr _init 9E 95entry point. 96.Pp 97The 98.Fn mac_fini_ops 99function should only ever be called from the context of a driver's 100.Xr _init 9E 101or 102.Xr _fini 9E 103entry point. 104.Sh RETURN VALUES 105The 106.Fn mac_init_ops 107and 108.Fn mac_fini_ops 109functions will always succeed. 110They do not have any kind of return value. 111.Sh EXAMPLES 112The following example shows how a driver would call 113.Fn mac_init_ops 114and 115.Fn mac_fini_ops 116correctly in the 117.Xr _init 9E 118and 119.Xr _fini 9E 120entry points of a driver. 121.Bd -literal 122#include <sys/modctl.h> 123#include <sys/ddi.h> 124#include <sys/sunddi.h> 125#include <sys/mac_provider.h> 126 127/* 128 * When using this, replace mydrv with the name of the actual device 129 * driver. In addition, the mydrv_ prefix that is used should be 130 * replaced with the name of the device driver 131 */ 132#define MYDRV_NAME "mydrv" 133 134/* 135 * The following dev_ops structure would need to be filled in by a 136 * proper device driver. 137 */ 138static struct dev_ops mydrv_dev_ops; 139 140static struct modldrv mydrv_modldrv = { 141 &mod_driverops, 142 MYDRV_NAME, 143 &mydrv_dev_ops 144}; 145 146static struct modlinkage mydrv_modlinkage = { 147 MODREV_1, 148 &mydrv_modldrv, 149 NULL 150}; 151 152int 153_init(void) 154{ 155 int ret; 156 157 /* Perform other needed initialization */ 158 159 mac_init_ops(&mydrv_devops, MYDRV_NAME); 160 161 ret = mod_install(&mydrv_modlinkage); 162 if (ret != DDI_SUCCESS) { 163 mac_fini_ops(&mydrv_devops); 164 /* Perform other needed finalization */ 165 } 166 167 return (ret); 168} 169 170int 171_info(struct modinfo *modinfop) 172{ 173 return (mod_info(&mydrv_modlinkage, modinfo)); 174} 175 176int 177_fini(void) 178{ 179 int ret; 180 181 ret = mod_remove(&mydrv_modlinkage); 182 if (ret == DDI_SUCCESS) { 183 mac_fini_ops(&mydrv_devops); 184 /* Perform other needed finalization */ 185 } 186 187 return (ret); 188} 189.Ed 190.Sh SEE ALSO 191.Xr _fini 9E , 192.Xr _init 9E , 193.Xr mac 9E , 194.Xr mod_install 9F , 195.Xr mod_remove 9F , 196.Xr dev_ops 9S 197