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