xref: /illumos-gate/usr/src/man/man9f/mac_init_ops.9f (revision b31ca922)
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.\"
1252d2369aSRobert Mustacchi.\" Copyright 2016 Joyent, Inc.
1352d2369aSRobert Mustacchi.\"
1452d2369aSRobert Mustacchi.Dd May 31, 2016
1552d2369aSRobert Mustacchi.Dt MAC_INIT_OPS 9F
1652d2369aSRobert Mustacchi.Os
1752d2369aSRobert Mustacchi.Sh NAME
1852d2369aSRobert Mustacchi.Nm mac_init_ops ,
1952d2369aSRobert Mustacchi.Nm mac_fini_ops
2052d2369aSRobert Mustacchi.Nd initialize and finalize driver support for the MAC framework
2152d2369aSRobert Mustacchi.Sh SYNOPSIS
2252d2369aSRobert Mustacchi.In sys/mac_provider.h
2352d2369aSRobert Mustacchi.Ft void
2452d2369aSRobert Mustacchi.Fo mac_init_ops
2552d2369aSRobert Mustacchi.Fa "struct dev_ops *ops"
2652d2369aSRobert Mustacchi.Fa "const char *name"
2752d2369aSRobert Mustacchi.Fc
2852d2369aSRobert Mustacchi.Ft void
2952d2369aSRobert Mustacchi.Fo mac_fini_ops
3052d2369aSRobert Mustacchi.Fa "struct dev_ops *ops"
3152d2369aSRobert Mustacchi.Fc
3252d2369aSRobert Mustacchi.Sh INTERFACE LEVEL
3352d2369aSRobert Mustacchiillumos DDI specific
3452d2369aSRobert Mustacchi.Sh PARAMETERS
3552d2369aSRobert Mustacchi.Bl -tag -width Ds
3652d2369aSRobert Mustacchi.It Fa ops
3752d2369aSRobert MustacchiA pointer to the driver's
3852d2369aSRobert Mustacchi.Xr dev_ops 9S
3952d2369aSRobert Mustacchistructure.
4052d2369aSRobert Mustacchi.It Fa name
4152d2369aSRobert MustacchiA pointer to a null-terminated string of ASCII characters that contains
4252d2369aSRobert Mustacchithe name of the driver.
4352d2369aSRobert Mustacchi.El
4452d2369aSRobert Mustacchi.Sh DESCRIPTION
4552d2369aSRobert MustacchiThe
4652d2369aSRobert Mustacchi.Fn mac_init_ops
4752d2369aSRobert Mustacchiand
4852d2369aSRobert Mustacchi.Fn mac_fini_ops
4952d2369aSRobert Mustacchifunctions are used to initialize and finalize support for a device
5052d2369aSRobert Mustacchidriver that implements the
5152d2369aSRobert Mustacchi.Xr mac 9E
5252d2369aSRobert Mustacchinetworking device framework.
5352d2369aSRobert Mustacchi.Pp
5452d2369aSRobert MustacchiThe
5552d2369aSRobert Mustacchi.Fn mac_init_ops
5652d2369aSRobert Mustacchifunction should be called during the driver's
5752d2369aSRobert Mustacchi.Xr _init 9E
5872d3dbb9SYuri Pankoventry point.
5972d3dbb9SYuri PankovAs described in more detail in the
6052d2369aSRobert Mustacchi.Sx Initializing MAC Support
6152d2369aSRobert Mustacchisection of
6252d2369aSRobert Mustacchi.Xr mac 9E ,
6352d2369aSRobert Mustacchithis must be called before the driver calls
6452d2369aSRobert Mustacchi.Xr mod_install 9F .
6552d2369aSRobert MustacchiIf this is not done, then the call to
6652d2369aSRobert Mustacchi.Xr mac_register 9F
6752d2369aSRobert Mustacchiwill fail.
6852d2369aSRobert Mustacchi.Pp
6952d2369aSRobert MustacchiWhen in the driver's
7052d2369aSRobert Mustacchi.Xr _fini 9E
7152d2369aSRobert Mustacchientry point, after the call to
7252d2369aSRobert Mustacchi.Xr mod_remove 9F
7352d2369aSRobert Mustacchihas succeeded, then the driver must call the
7452d2369aSRobert Mustacchi.Fn mac_fini_ops
7572d3dbb9SYuri Pankovfunction to finalize support and finish releasing any resources.
7672d3dbb9SYuri PankovIf the call to
7752d2369aSRobert Mustacchi.Xr mod_remove 9F
7852d2369aSRobert Mustacchifails, then the device driver should not call
7952d2369aSRobert Mustacchi.Fn mac_fini_ops
8052d2369aSRobert Mustacchiand should fail the call to
81*b31ca922SChris Fraire.Xr _fini 9E .
8252d2369aSRobert Mustacchi.Pp
8352d2369aSRobert MustacchiIn addition, if the call to
8452d2369aSRobert Mustacchi.Xr mod_install 9F
8552d2369aSRobert Mustacchiin the driver's
8652d2369aSRobert Mustacchi.Xr _init 9E
8752d2369aSRobert Mustacchientry point fails, then the driver should also call
88c66b8046SYuri Pankov.Fn mac_fini_ops .
8952d2369aSRobert MustacchiSee the example below for how this should be structured.
9052d2369aSRobert Mustacchi.Sh CONTEXT
9152d2369aSRobert MustacchiThe
9252d2369aSRobert Mustacchi.Fn mac_init_ops
9352d2369aSRobert Mustacchifunction should only ever be called from the context of a driver's
9452d2369aSRobert Mustacchi.Xr _init 9E
9552d2369aSRobert Mustacchientry point.
9652d2369aSRobert Mustacchi.Pp
9752d2369aSRobert MustacchiThe
9852d2369aSRobert Mustacchi.Fn mac_fini_ops
9952d2369aSRobert Mustacchifunction should only ever be called from the context of a driver's
10052d2369aSRobert Mustacchi.Xr _init 9E
10152d2369aSRobert Mustacchior
10252d2369aSRobert Mustacchi.Xr _fini 9E
10352d2369aSRobert Mustacchientry point.
10452d2369aSRobert Mustacchi.Sh RETURN VALUES
10552d2369aSRobert MustacchiThe
10652d2369aSRobert Mustacchi.Fn mac_init_ops
10752d2369aSRobert Mustacchiand
10852d2369aSRobert Mustacchi.Fn mac_fini_ops
10972d3dbb9SYuri Pankovfunctions will always succeed.
11072d3dbb9SYuri PankovThey do not have any kind of return value.
11152d2369aSRobert Mustacchi.Sh EXAMPLES
11252d2369aSRobert MustacchiThe following example shows how a driver would call
113c66b8046SYuri Pankov.Fn mac_init_ops
11452d2369aSRobert Mustacchiand
115c66b8046SYuri Pankov.Fn mac_fini_ops
11652d2369aSRobert Mustacchicorrectly in the
11752d2369aSRobert Mustacchi.Xr _init 9E
11852d2369aSRobert Mustacchiand
11952d2369aSRobert Mustacchi.Xr _fini 9E
12052d2369aSRobert Mustacchientry points of a driver.
12152d2369aSRobert Mustacchi.Bd -literal
12252d2369aSRobert Mustacchi#include <sys/modctl.h>
12352d2369aSRobert Mustacchi#include <sys/ddi.h>
12452d2369aSRobert Mustacchi#include <sys/sunddi.h>
12552d2369aSRobert Mustacchi#include <sys/mac_provider.h>
12652d2369aSRobert Mustacchi
12752d2369aSRobert Mustacchi/*
12852d2369aSRobert Mustacchi * When using this, replace mydrv with the name of the actual device
12952d2369aSRobert Mustacchi * driver. In addition, the mydrv_ prefix that is used should be
13052d2369aSRobert Mustacchi * replaced with the name of the device driver
13152d2369aSRobert Mustacchi */
13252d2369aSRobert Mustacchi#define	MYDRV_NAME	"mydrv"
13352d2369aSRobert Mustacchi
13452d2369aSRobert Mustacchi/*
13552d2369aSRobert Mustacchi * The following dev_ops structure would need to be filled in by a
13652d2369aSRobert Mustacchi * proper device driver.
13752d2369aSRobert Mustacchi */
13852d2369aSRobert Mustacchistatic struct dev_ops	mydrv_dev_ops;
13952d2369aSRobert Mustacchi
14052d2369aSRobert Mustacchistatic struct modldrv mydrv_modldrv = {
14152d2369aSRobert Mustacchi	&mod_driverops,
14252d2369aSRobert Mustacchi	MYDRV_NAME,
14352d2369aSRobert Mustacchi	&mydrv_dev_ops
14452d2369aSRobert Mustacchi};
14552d2369aSRobert Mustacchi
14652d2369aSRobert Mustacchistatic struct modlinkage mydrv_modlinkage = {
14752d2369aSRobert Mustacchi	MODREV_1,
14852d2369aSRobert Mustacchi	&mydrv_modldrv,
14952d2369aSRobert Mustacchi	NULL
15052d2369aSRobert Mustacchi};
15152d2369aSRobert Mustacchi
15252d2369aSRobert Mustacchiint
15352d2369aSRobert Mustacchi_init(void)
15452d2369aSRobert Mustacchi{
15552d2369aSRobert Mustacchi	int ret;
15652d2369aSRobert Mustacchi
15752d2369aSRobert Mustacchi	/* Perform other needed initialization */
15852d2369aSRobert Mustacchi
15952d2369aSRobert Mustacchi	mac_init_ops(&mydrv_devops, MYDRV_NAME);
16052d2369aSRobert Mustacchi
16152d2369aSRobert Mustacchi	ret = mod_install(&mydrv_modlinkage);
16252d2369aSRobert Mustacchi	if (ret != DDI_SUCCESS) {
16352d2369aSRobert Mustacchi		mac_fini_ops(&mydrv_devops);
16452d2369aSRobert Mustacchi		/* Perform other needed finalization */
16552d2369aSRobert Mustacchi	}
16652d2369aSRobert Mustacchi
16752d2369aSRobert Mustacchi	return (ret);
16852d2369aSRobert Mustacchi}
16952d2369aSRobert Mustacchi
17052d2369aSRobert Mustacchiint
17152d2369aSRobert Mustacchi_info(struct modinfo *modinfop)
17252d2369aSRobert Mustacchi{
17352d2369aSRobert Mustacchi	return (mod_info(&mydrv_modlinkage, modinfo));
17452d2369aSRobert Mustacchi}
17552d2369aSRobert Mustacchi
17652d2369aSRobert Mustacchiint
17752d2369aSRobert Mustacchi_fini(void)
17852d2369aSRobert Mustacchi{
17952d2369aSRobert Mustacchi	int ret;
18052d2369aSRobert Mustacchi
18152d2369aSRobert Mustacchi	ret = mod_remove(&mydrv_modlinkage);
18252d2369aSRobert Mustacchi	if (ret == DDI_SUCCESS) {
18352d2369aSRobert Mustacchi		mac_fini_ops(&mydrv_devops);
18452d2369aSRobert Mustacchi		/* Perform other needed finalization */
18552d2369aSRobert Mustacchi	}
18652d2369aSRobert Mustacchi
18752d2369aSRobert Mustacchi	return (ret);
18852d2369aSRobert Mustacchi}
18952d2369aSRobert Mustacchi.Ed
19052d2369aSRobert Mustacchi.Sh SEE ALSO
19152d2369aSRobert Mustacchi.Xr _fini 9E ,
19252d2369aSRobert Mustacchi.Xr _init 9E ,
19352d2369aSRobert Mustacchi.Xr mac 9E ,
19452d2369aSRobert Mustacchi.Xr mod_install 9F ,
19552d2369aSRobert Mustacchi.Xr mod_remove 9F ,
19652d2369aSRobert Mustacchi.Xr dev_ops 9S
197