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