Tribblix: manual page: mac

MAC_FILTER(9E) Driver Entry Points MAC_FILTER(9E)

NAME

mac_filter, mgi_addmac, mgi_remmac, mgi_addvlan, mgi_remvlan - add and
remove filters from MAC groups

SYNOPSIS

#include <sys/mac_provider.h>

int
prefix_ring_add_mac(mac_group_driver_t driver, const uint8_t *mac);

int
prefix_ring_rem_mac(mac_group_driver_t driver, const uint8_t *mac);

int
prefix_ring_add_vlan(mac_group_driver_t driver, uint16_t vlan);

int
prefix_ring_rem_vlan(mac_group_driver_t driver, uint16_t vlan);

INTERFACE LEVEL

Uncommitted - This interface is still evolving. API and ABI stability
is not guaranteed.

PARAMETERS

driver A pointer to the ring's private data that was passed in
via the mgi_driver member of the mac_group_info(9S)
structure as part of the mr_gget(9E) entry point.

mac A pointer to an array of bytes that contains the unicast
address to add or remove from a filter. It is guaranteed
to be at least as long, in bytes, as the MAC plugin's
address length. For Ethernet devices that length is six
bytes, ETHERADDRL.

vlan The numeric value of the VLAN that should be added or
removed from a filter.

DESCRIPTION

The mac_filter() family of entry points are used to add and remove
various classes of filters from a device. For more information on the
filters, see the Filters section of mac_capab_rings(9E) and the
discussion around setting these members in mac_group_info(9S).

The driver argument indicates which group the request to add or remove
a filter is being requested on.

The filter addition operations, mgi_addmac(), mgi_addvlan(), and
mgi_addmvf(), all instruct the system to add a filter to the specified
group. The filter should not target any specific ring in the group.
If multiple rings are present, then the driver should ensure that the
hardware balances incoming traffic amongst all of the rings through a
consistent hashing mechanism such as receive side scaling.

The mgi_addmac() entry point instructs the driver to add the MAC
address specified in mac to the filter list for the group. The MAC
address should always be a unicast MAC address; however, the driver is
encouraged to verify that before adding it.

The mgi_remmac() should remove the MAC address specified in mac from
the filter list for the group.

The mgi_addvlan() entry point instructs the driver to add the VLAN
specified in vlan to the filter list for the group. The mgi_remvlan()
entry point instructs the driver to remove the VLAN specified in vlan
from the filter list for the group.

Stacking Filters

Multiple filters of the same class should always be treated as a
logical-OR. The frame may match any of the filters in a given class to
be accepted. Filters of different classes should always be treated as
a logical-AND. The frame must match a filter in all programmed classes
to be accepted. For more information, see the Filters section of
mac_capab_rings(9E).

RETURN VALUES

Upon successful completion, the driver should ensure that the filter
has been added or removed and return 0. Otherwise, it should return
the appropriate error number.

ERRORS

The device driver may return one of the following errors. While this
list is not intended to be exhaustive, it is recommended to use one of
these if possible.

EEXIST The requested filter has already been programmed
into the device.

EINVAL The address mac is not a valid unicast address. The
VLAN vlan is not a valid VLAN identifier.

EIO The driver encountered a device or transport error
while trying to update the device's state.

ENOENT The driver was asked to remove a filter which was
not currently programmed.

ENOTSUP The driver does not support this specific function.
This should only be used on specific hardware
(generally devices from cloud providers) where
neither promiscuous mode nor filters will allow the
filter to operate.

ENOSPC The driver has run out of available hardware
filters.