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.\" Copyright 2023 Peter Tribble 15.\" 16.Dd July 17, 2023 17.Dt MAC_FILTER 9E 18.Os 19.Sh NAME 20.Nm mac_filter , 21.Nm mgi_addmac , 22.Nm mgi_remmac , 23.Nm mgi_addvlan , 24.Nm mgi_remvlan 25.Nd add and remove filters from MAC groups 26.Sh SYNOPSIS 27.In sys/mac_provider.h 28.Ft int 29.Fo prefix_ring_add_mac 30.Fa "mac_group_driver_t driver" 31.Fa "const uint8_t *mac" 32.Fc 33.Ft int 34.Fo prefix_ring_rem_mac 35.Fa "mac_group_driver_t driver" 36.Fa "const uint8_t *mac" 37.Fc 38.Ft int 39.Fo prefix_ring_add_vlan 40.Fa "mac_group_driver_t driver" 41.Fa "uint16_t vlan" 42.Fc 43.Ft int 44.Fo prefix_ring_rem_vlan 45.Fa "mac_group_driver_t driver" 46.Fa "uint16_t vlan" 47.Fc 48.Sh INTERFACE LEVEL 49.Sy Uncommitted - 50This interface is still evolving. 51API and ABI stability is not guaranteed. 52.Sh PARAMETERS 53.Bl -tag -width Fa 54.It Fa driver 55A pointer to the ring's private data that was passed in via the 56.Vt mgi_driver 57member of the 58.Xr mac_group_info 9S 59structure as part of the 60.Xr mr_gget 9E 61entry point. 62.It Fa mac 63A pointer to an array of bytes that contains the unicast address to add 64or remove from a filter. 65It is guaranteed to be at least as long, in bytes, as the MAC plugin's 66address length. 67For Ethernet devices that length is six bytes, 68.Dv ETHERADDRL . 69.It Fa vlan 70The numeric value of the VLAN that should be added or removed from a 71filter. 72.El 73.Sh DESCRIPTION 74The 75.Fn mac_filter 76family of entry points are used to add and remove various classes of 77filters from a device. 78For more information on the filters, see the 79.Sy Filters 80section of 81.Xr mac_capab_rings 9E 82and the discussion around setting these members in 83.Xr mac_group_info 9S . 84.Pp 85The 86.Fa driver 87argument indicates which group the request to add or remove a filter is 88being requested on. 89.Pp 90The filter addition operations, 91.Fn mgi_addmac , 92.Fn mgi_addvlan , 93and 94.Fn mgi_addmvf , 95all instruct the system to add a filter to the specified group. 96The filter should not target any specific ring in the group. 97If multiple rings are present, then the driver should ensure that the 98hardware balances incoming traffic amongst all of the rings through a 99consistent hashing mechanism such as receive side scaling. 100.Pp 101The 102.Fn mgi_addmac 103entry point instructs the driver to add the MAC address specified in 104.Fa mac 105to the filter list for the group. 106The MAC address should always be a unicast MAC address; however, the 107driver is encouraged to verify that before adding it. 108.Pp 109The 110.Fn mgi_remmac 111should remove the MAC address specified in 112.Fa mac 113from the filter list for the group. 114.Pp 115The 116.Fn mgi_addvlan 117entry point instructs the driver to add the VLAN specified in 118.Fa vlan 119to the filter list for the group. 120The 121.Fn mgi_remvlan 122entry point instructs the driver to remove the VLAN specified in 123.Fa vlan 124from the filter list for the group. 125.Ss Stacking Filters 126Multiple filters of the same class should always be treated as a 127logical-OR. 128The frame may match any of the filters in a given class to be accepted. 129Filters of different classes should always be treated as a logical-AND. 130The frame must match a filter in all programmed classes to be accepted. 131For more information, see the 132.Sy Filters 133section of 134.Xr mac_capab_rings 9E . 135.Sh RETURN VALUES 136Upon successful completion, the driver should ensure that the filter has 137been added or removed and return 138.Sy 0 . 139Otherwise, it should return the appropriate error number. 140.Sh ERRORS 141The device driver may return one of the following errors. 142While this list is not intended to be exhaustive, it is recommended to use one 143of these if possible. 144.Bl -tag -width Er 145.It Er EEXIST 146The requested filter has already been programmed into the device. 147.It Er EINVAL 148The address 149.Fa mac 150is not a valid unicast address. 151The VLAN 152.Fa vlan 153is not a valid VLAN identifier. 154.It Er EIO 155The driver encountered a device or transport error while trying to 156update the device's state. 157.It Er ENOENT 158The driver was asked to remove a filter which was not currently 159programmed. 160.It Er ENOTSUP 161The driver does not support this specific function. 162This should only be used on specific hardware 163.Pq generally devices from cloud providers 164where neither promiscuous mode nor filters will allow 165the filter to operate. 166.It Er ENOSPC 167The driver has run out of available hardware filters. 168.El 169.Sh SEE ALSO 170.Xr mac 9E , 171.Xr mac_capab_rings 9E , 172.Xr mr_gget 9E , 173.Xr mac_group_info 9S 174