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 10, 2016 15.Dt MAC_REGISTER 9S 16.Os 17.Sh NAME 18.Nm mac_register , 19.Nm mac_register_t 20.Nd networking device driver registration structure 21.Sh SYNOPSIS 22.In sys/mac_provider.h 23.In sys/mac_ether.h 24.Sh INTERFACE LEVEL 25illumos DDI specific 26.Sh DESCRIPTION 27The 28.Sy mac_register 29structure is used by GLDv3 networking device drivers implementing the 30.Xr mac 9E 31interface. 32.Pp 33The structure is allocated by a call to 34.Xr mac_alloc 9F 35after which the various structure members should be set. 36Once they have been set, the structure can be used by a GLDv3 device driver to 37register with the MAC framework by calling the 38.Xr mac_register 9F 39function. 40Once 41.Xr mac_register 9F 42has been called, the structure can be freed through a call to 43.Xr mac_free 9F . 44.Sh STRUCTURE MEMBERS 45.Bd -literal -offset indent 46uint_t m_version; 47const char *m_type_ident; 48void *m_driver; 49dev_info_t *m_dip; 50uint_t m_instance; 51uint8_t *m_src_addr; 52uint8_t *m_dst_addr; 53mac_callbacks_t *m_callbacks; 54uint_t m_min_sdu; 55uint_t m_max_sdu; 56void *m_pdata; 57size_t m_pdata_size; 58char **m_priv_props; 59uint32_t m_margin; 60.Ed 61.Pp 62The 63.Sy m_version 64member is set during a call to 65.Xr mac_alloc 9F . 66Device drivers should not modify this field. 67.Pp 68The 69.Sy m_type_ident 70member identifies the kind of networking device that this driver 71represents. 72The following constants should be used to identify the device type: 73.Bl -tag -width Dv 74.It Sy MAC_PLUGIN_IDENT_ETHER 75The device driver implements IEEE 802.3 Ethernet. 76.El 77.Pp 78The 79.Sy m_driver 80value is a private value that the device driver may set and will be 81provided as an argument in many of the 82.Xr mac 9E 83callbacks. 84Most often this is set to the driver's soft state for a specific instance. 85.Pp 86The 87.Sy m_dip 88member should point to the device driver's 89.Sy dev_info 90structure for that specific instance. 91This structure is provided during the driver's 92.Xr attach 9E 93entry point. 94.Pp 95The 96.Sy m_instance 97member should be set to zero. 98The GLDv3 framework will determine the appropriate instance. 99.Pp 100The 101.Sy m_src_addr 102member should be set to a byte array that describes the source MAC 103address of the device. 104This is usually the default MAC address as programmed by the device manufacturer 105in that instance of the device. 106.Pp 107The 108.Sy m_dst_addr 109member is an optional property and should be set to 110.Dv NULL 111by most device drivers. 112If set, this address will be the destination for outgoing frames. 113.Pp 114The 115.Sy m_callbacks 116member contains the GLDv3 entry points implemented by the device driver. 117See 118.Xr mac_callbacks 9S 119for a full explanation of the structure, its members, and their 120responsibilities. 121See 122.Xr mac 9E 123for a broader picture of how the entry points are used. 124.Pp 125The 126.Sy m_min_sdu 127property is the minimum service data unit. 128It represents the minimum size packet that the device can transmit, ignoring its 129own headers. 130Thus for an Ethernet device, this value would exclude the Ethernet header and 131any VLAN headers. 132If this is set to zero, then that means that either the MAC protocol does not 133require a minimum size or that the device driver and hardware will ensure that 134any minimum size is taken care of. 135.Pp 136The 137.Sy m_max_sdu 138property is the maximum service data unit. 139It represents the maximum size packet that the device can transmit, ignoring its 140own headers. 141For an Ethernet based device, this would exclude the size of the Ethernet 142header and a VLAN headers. 143This value is often called the maximum transmission unit (MTU). 144.Pp 145The 146.Sy m_pdata 147member is used for data specific to the type specified in the 148.Sy m_type_ident 149member. 150For all devices of type 151.Sy MAC_PLUGIN_IDENT_ETHER , 152this should be set to 153.Dv NULL . 154.Pp 155The 156.Sy m_pdata_size 157member indicates the size of the member 158.Sy m_pdata . 159For all devices of type 160.Sy MAC_PLUGIN_IDENT_ETHER , 161this should be set to 0. 162.Pp 163The 164.Sy m_priv_props 165member is an optional member that lists device-specific properties. 166These properties will be queried through functions like 167.Xr mc_getprop 9E , 168.Xr mc_propinfo 9E , 169and 170.Xr mc_setprop 9E . 171If the driver does not have any private properties, it should be set to 172.Dv NULL . 173Otherwise, it should be set to a NULL-terminated array of character 174strings where each entry is the name of a distinct property. 175See 176.Xr mac 9E 177for more information on private properties. 178.Pp 179The 180.Sy m_margin 181property 182indicates the amount of additional bytes of information that may be 183included beyond the basic MAC header. 184For example, with an Ethernet device, if the hardware supports a VLAN tag, then 185this property would be set to the size of a VLAN tag, indicating that it 186supported the additional bytes in a single packet beyond the Ethernet header and 187the 188.Sy m_max_sdu . 189.Sh SEE ALSO 190.Xr attach 9E , 191.Xr mac 9E , 192.Xr mac_alloc 9F , 193.Xr mac_free 9F , 194.Xr mac_register 9F , 195.Xr mac_callbacks 9S 196