.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd May 10, 2016
.Dt MAC_REGISTER 9S
.Os
.Sh NAME
.Nm mac_register ,
.Nm mac_register_t
.Nd networking device driver registration structure
.Sh SYNOPSIS
.In sys/mac_provider.h
.In sys/mac_ether.h
.Sh INTERFACE LEVEL
illumos DDI specific
.Sh DESCRIPTION
The
.Sy mac_register
structure is used by GLDv3 networking device drivers implementing the
.Xr mac 9E
interface.
.Pp
The structure is allocated by a call to
.Xr mac_alloc 9F
after which the various structure members should be set. Once they have
been set, the structure can be used by a GLDv3 device driver to register
with the MAC framework by calling the
.Xr mac_register 9F
function. Once
.Xr mac_register 9F
has been called, the structure can be freed through a call to
.Xr mac_free 9F .
.Sh STRUCTURE MEMBERS
.Bd -literal -offset indent
uint_t                  m_version;
const char              *m_type_ident;
void                    *m_driver;
dev_info_t              *m_dip;
uint_t                  m_instance;
uint8_t                 *m_src_addr;
uint8_t                 *m_dst_addr;
mac_callbacks_t         *m_callbacks;
uint_t                  m_min_sdu;
uint_t                  m_max_sdu;
void                    *m_pdata;
size_t                  m_pdata_size;
char                    **m_priv_props;
uint32_t                m_margin;
.Ed
.Pp
The
.Sy m_version
member is set during a call to
.Xr mac_alloc 9F .
Device drivers should not modify this field.
.Pp
The
.Sy m_type_ident
member identifies the kind of networking device that this driver
represents. The following constants should be used to identify the
device type:
.Bl -tag -width Dv
.It Sy MAC_PLUGIN_IDENT_ETHER
The device driver implements IEEE 802.3 Ethernet.
.El
.Pp
The
.Sy m_driver
value is a private value that the device driver may set and will be
provided as an argument in many of the
.Xr mac 9E
callbacks. Most often this is set to the driver's soft state for a
specific instance.
.Pp
The
.Sy m_dip
member should point to the device driver's
.Sy dev_info
structure for that specific instance. This structure is provided during
the driver's
.Xr attach 9E
entry point.
.Pp
The
.Sy m_instance
member should be set to zero. The GLDv3 framework will determine the
appropriate instance.
.Pp
The
.Sy m_src_addr
member should be set to a byte array that describes the source MAC
address of the device. This is usually the default MAC address as
programmed by the device manufacturer in that instance of the device.
.Pp
The
.Sy m_dst_addr
member is an optional property and should be set to
.Dv NULL
by most device drivers. If set, this address will be the destination for
outgoing frames.
.Pp
The
.Sy m_callbacks
member contains the GLDv3 entry points implemented by the device driver.
.Xr mac
See
.Xr mac_callbacks 9S
for a full explanation of the structure, its members, and their
responsibilities. See
.Xr mac 9E
for a broader picture of how the entry points are used.
.Pp
The
.Sy m_min_sdu
property is the minimum service data unit. It represents the minimum
size packet that the device can transmit, ignoring its own headers. Thus
for an Ethernet device, this value would exclude the Ethernet header and
any VLAN headers. If this is set to zero, then that means that either
the MAC protocol does not require a minimum size or that the device
driver and hardware will ensure that any minimum size is taken care of.
.Pp
The
.Sy m_max_sdu
property is the maximum service data unit. It represents the maximum
size packet that the device can transmit, ignoring its own headers. For
an Ethernet based device, this would exclude the size of the Ethernet
header and a VLAN headers. This value is often called the maximum
transmission unit (MTU).
.Pp
The
.Sy m_pdata
member is used for data specific to the type specified in the
.Sy m_type_ident
member. For all devices of type
.Sy MAC_PLUGIN_IDENT_ETHER ,
this should be set to
.Dv NULL .
.Pp
The
.Sy m_pdata_size
member indicates the size of the member
.Sy m_pdata .
For all devices of type
.Sy MAC_PLUGIN_IDENT_ETHER ,
this should be set to 0.
.Pp
The
.Sy m_priv_props
member is an optional member that lists device-specific properties.
These properties will be queried through functions like
.Xr mc_getprop 9E ,
.Xr mc_propinfo 9E ,
and
.Xr mc_setprop 9E .
If the driver does not have any private properties, it should be set to
.Dv NULL .
Otherwise, it should be set to a NULL-terminated array of character
strings where each entry is the name of a distinct property. See
.Xr mac 9E
for more information on private properties.
.Pp
The
.Sy m_margin
property
indicates the amount of additional bytes of information that may be
included beyond the basic MAC header. For example, with an Ethernet
device, if the hardware supports a VLAN tag, then this property would be
set to the size of a VLAN tag, indicating that it supported the
additional bytes in a single packet beyond the Ethernet header and the
.Sy m_max_sdu .
.Sh SEE ALSO
.Xr attach 9E ,
.Xr mac 9E ,
.Xr mac_alloc 9F ,
.Xr mac_free 9F ,
.Xr mac_register 9F ,
.Xr mac_callbacks 9S