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. 42It is guaranteed to be at least a number of bytes long equal to the length of 43the MAC plugin's address length. 44For Ethernet devices that length is six bytes, 45.Sy ETHERADDRL . 46.El 47.Sh DESCRIPTION 48The 49.Fn mc_unicst 50entry point is used by the GLDv3 to indicate that the device driver 51should update the primary MAC address of the device. 52In the basic mode of operation, this entry point is required and the device has 53a single primary MAC address. 54If multiple MAC addresses are required, the device will be placed into 55promiscuous mode. 56This call should overwrite the existing MAC address that is programmed into the 57device. 58.Pp 59As noted in the 60.Sx PARAMETERS 61section, the 62.Fa mac 63array is guaranteed to be at least as many bytes as is required to 64specify an address; however, it should be assumed to be no longer than 65that value. 66.Pp 67The device driver can optionally assert that the address is in the 68valid form for a unicast address and then program the device. 69The device driver can access its device soft state by casting the 70.Fa device 71pointer to the appropriate structure. 72As this may be called while other operations are ongoing, the device driver 73should employ the appropriate locking while updating the data. 74.Pp 75It is recommended that device drivers always maintain a copy of the 76current unicast address in its soft state so that way it can recover 77from various device reset and errors or handle requests to suspend and 78resume the device that may result in device registers being cleared. 79.Pp 80Some devices support multiple MAC address filters. 81The 82.Fn mc_unicst 83entry point only supports a single MAC address. 84In this case, devices should only use a single MAC address and replace that MAC 85address. 86Support for using more than a single MAC address filter will be provided 87by future interfaces. 88.Sh RETURN VALUES 89Upon successful completion, the device driver should have updated its 90unicast filter and return 91.Sy 0 . 92Otherwise, the MAC address should remain unchanged and the driver should 93return an appropriate error number. 94.Sh ERRORS 95The device driver may return one of the following errors. 96While this list is not intended to be exhaustive, it is recommended to use one 97of these if possible. 98.Bl -tag -width Er 99.It Er EINVAL 100The address 101.Fa mac 102is not a valid unicast address. 103.It Er EIO 104The driver encountered a device or transport error while trying to 105update the device's state. 106.El 107.Sh SEE ALSO 108.Xr mac 9E , 109.Xr mac_register 9F , 110.Xr mac_register 9S 111