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 31, 2016 15.Dt MC_UNICST 9E 16.Os 17.Sh NAME 18.Nm mc_unicst 19.Nd set device unicast address 20.Sh SYNOPSIS 21.In sys/mac_provider.h 22.Ft int 23.Fo prefix_m_unicst 24.Fa "void *driver" 25.Fa "const uint8_t *mac" 26.Fc 27.Sh INTERFACE LEVEL 28illumos DDI specific 29.Sh PARAMETERS 30.Bl -tag -width Fa 31.It Fa driver 32A pointer to the driver's private data that was passed in via the 33.Sy m_pdata 34member of the 35.Xr mac_register 9S 36structure to the 37.Xr mac_register 9F 38function. 39.It Fa mac 40A pointer to an array of bytes that contains the new unicast address of 41the device. It is guaranteed to be at least a number of bytes long equal 42to the length of the MAC plugin's address length. For Ethernet devices that 43length is six bytes, 44.Sy ETHERADDRL . 45.El 46.Sh DESCRIPTION 47The 48.Fn mc_unicst 49entry point is used by the GLDv3 to indicate that the device driver 50should update the primary MAC address of the device. In the basic mode 51of operation, this entry point is required and the device has a single 52primary MAC address. If multiple MAC addresses are required, the 53device will be placed into promiscuous mode. This call should overwrite 54the existing MAC address that is programmed into the device. 55.Pp 56As noted in the 57.Sx PARAMETERS 58section, the 59.Fa mac 60array is guaranteed to be at least as many bytes as is required to 61specify an address; however, it should be assumed to be no longer than 62that value. 63.Pp 64The device driver can optionally assert that the address is in the 65valid form for a unicast address and then program the device. The device 66driver can access its device soft state by casting the 67.Fa device 68pointer to the appropriate structure. As this may be called while other 69operations are ongoing, the device driver should employ the appropriate 70locking while updating the data. 71.Pp 72It is recommended that device drivers always maintain a copy of the 73current unicast address in its soft state so that way it can recover 74from various device reset and errors or handle requests to suspend and 75resume the device that may result in device registers being cleared. 76.Pp 77Some devices support multiple MAC address filters. The 78.Fn mc_unicst 79entry point only supports a single MAC address. In this case, devices 80should only use a single MAC address and replace that MAC address. 81Support for using more than a single MAC address filter will be provided 82by future interfaces. 83.Sh RETURN VALUES 84Upon successful completion, the device driver should have updated its 85unicast filter and return 86.Sy 0 . 87Otherwise, the MAC address should remain unchanged and the driver should 88return an appropriate error number. 89.Sh ERRORS 90The device driver may return one of the following errors. While this list 91is not intended to be exhaustive, it is recommended to use one of these 92if possible. 93.Bl -tag -width Er 94.It Er EINVAL 95The address 96.Fa mac 97is not a valid unicast address. 98.It Er EIO 99The driver encountered a device or transport error while trying to 100update the device's state. 101.El 102.Sh SEE ALSO 103.Xr mac 9E , 104.Xr mac_register 9F , 105.Xr mac_register 9S 106