xref: /illumos-gate/usr/src/man/man9f/mac_alloc.9f (revision 8c732929)
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*8c732929SRobert Mustacchi.\" Copyright 2019 Joyent, Inc.
1352d2369aSRobert Mustacchi.\"
14*8c732929SRobert Mustacchi.Dd July 22, 2019
1552d2369aSRobert Mustacchi.Dt MAC_ALLOC 9F
1652d2369aSRobert Mustacchi.Os
1752d2369aSRobert Mustacchi.Sh NAME
1852d2369aSRobert Mustacchi.Nm mac_alloc ,
1952d2369aSRobert Mustacchi.Nm mac_free
2052d2369aSRobert Mustacchi.Nd allocate and free mac registration structures
2152d2369aSRobert Mustacchi.Sh SYNOPSIS
2252d2369aSRobert Mustacchi.In sys/mac_provider.h
2352d2369aSRobert Mustacchi.Ft "mac_register_t *"
2452d2369aSRobert Mustacchi.Fo mac_alloc
2552d2369aSRobert Mustacchi.Fa "uint_t mac_version"
2652d2369aSRobert Mustacchi.Fc
2752d2369aSRobert Mustacchi.Ft void
2852d2369aSRobert Mustacchi.Fo mac_free
2952d2369aSRobert Mustacchi.Fa "mac_register_t *mregp"
3052d2369aSRobert Mustacchi.Fc
3152d2369aSRobert Mustacchi.Sh INTERFACE LEVEL
3252d2369aSRobert Mustacchiillumos DDI specific
3352d2369aSRobert Mustacchi.Sh PARAMETERS
3452d2369aSRobert Mustacchi.Bl -tag -width Fa
3552d2369aSRobert Mustacchi.It Fa mac_version
3652d2369aSRobert MustacchiAn integer corresponding to the version of the MAC interface that the
3752d2369aSRobert Mustacchidevice driver was built against.
3852d2369aSRobert Mustacchi.It Fa mregp
3952d2369aSRobert MustacchiA pointer to an allocated mac_register_t structure that was obtained
4052d2369aSRobert Mustacchifrom calling the
4152d2369aSRobert Mustacchi.Fn mac_alloc
4252d2369aSRobert Mustacchifunction.
4352d2369aSRobert Mustacchi.El
4452d2369aSRobert Mustacchi.Sh DESCRIPTION
4552d2369aSRobert MustacchiThe
4652d2369aSRobert Mustacchi.Fn mac_alloc
4752d2369aSRobert Mustacchiand
4852d2369aSRobert Mustacchi.Fn mac_free
4952d2369aSRobert Mustacchiroutines are used to allocate and free the structures used to register a
5052d2369aSRobert Mustacchidevice driver with
5152d2369aSRobert Mustacchi.Xr mac 9E .
5252d2369aSRobert MustacchiThe device driver should call
5352d2369aSRobert Mustacchi.Fn mac_alloc
5452d2369aSRobert Mustacchiwith the value of
5552d2369aSRobert Mustacchi.Dv MAC_VERSION
5652d2369aSRobert Mustacchito indicate the current version of the MAC framework that it supports.
5752d2369aSRobert MustacchiThe device driver will be returned an instance of a
5852d2369aSRobert Mustacchi.Xr mac_register 9S
5952d2369aSRobert Mustacchistructure which it can then use to call
6052d2369aSRobert Mustacchi.Xr mac_register 9F .
6152d2369aSRobert MustacchiFor more information on the order of events, see the
6252d2369aSRobert Mustacchi.Sx Initializing MAC Support
6352d2369aSRobert Mustacchisection of
6452d2369aSRobert Mustacchi.Xr mac 9E .
6552d2369aSRobert Mustacchi.Pp
6652d2369aSRobert MustacchiWhen the driver is done with the
6752d2369aSRobert Mustacchi.Xr mac_register 9S
6852d2369aSRobert Mustacchistructure, it must call the
69c66b8046SYuri Pankov.Fn mac_free
70*8c732929SRobert Mustacchifunction to release any memory associated with the handle.
71*8c732929SRobert Mustacchi.Pp
72*8c732929SRobert MustacchiAfter the driver has called
73*8c732929SRobert Mustacchi.Xr mac_register 9F
74*8c732929SRobert Mustacchiduring its
75*8c732929SRobert Mustacchi.Xr attach 9E
76*8c732929SRobert Mustacchientry point, the
77*8c732929SRobert Mustacchi.Xr mac_register 9S
78*8c732929SRobert Mustacchistructure is no longer needed and can be freed.
7952d2369aSRobert Mustacchi.Sh CONTEXT
8052d2369aSRobert MustacchiThe
8152d2369aSRobert Mustacchi.Fn mac_alloc
8252d2369aSRobert Mustacchiand
8352d2369aSRobert Mustacchi.Fn mac_free
8452d2369aSRobert Mustacchiroutines are generally called from the context of a device driver's
8552d2369aSRobert Mustacchi.Xr attach 9E
8652d2369aSRobert Mustacchientry point; however, they may be called from both
8752d2369aSRobert Mustacchi.Sy user
8852d2369aSRobert Mustacchiand
8952d2369aSRobert Mustacchi.Sy kernel
9052d2369aSRobert Mustacchicontext.
9152d2369aSRobert Mustacchi.Sh RETURN VALUES
9252d2369aSRobert MustacchiUpon successful completion, the
93*8c732929SRobert Mustacchi.Fn mac_alloc
9452d2369aSRobert Mustacchifunction will return a pointer to an allocated
9552d2369aSRobert Mustacchi.Sy mac_register_t
9672d3dbb9SYuri Pankovstructure that can be filled in by the driver.
9772d3dbb9SYuri PankovOtherwise,
9852d2369aSRobert Mustacchi.Dv NULL
9972d3dbb9SYuri Pankovis returned to indicate that the structure could not be allocated.
10072d3dbb9SYuri PankovThe most common cause for this is that the value of
10152d2369aSRobert Mustacchi.Fa mac_version
10252d2369aSRobert Mustacchiis not supported by the kernel.
10352d2369aSRobert Mustacchi.Sh SEE ALSO
10452d2369aSRobert Mustacchi.Xr attach 9E ,
10552d2369aSRobert Mustacchi.Xr mac 9E ,
10652d2369aSRobert Mustacchi.Xr mac_register 9F ,
10752d2369aSRobert Mustacchi.Xr mac_register 9S
108