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