illumos: manual page: mc

MC_MULTICST(9E) Driver Entry Points MC_MULTICST(9E)

NAME

mc_multicst - add or remove multicast address from device filter

SYNOPSIS

#include <sys/mac_provider.h>

int
prefix_m_multicst(void *driver, boolean_t add, const uint8_t *mac);

INTERFACE LEVEL

illumos DDI Specific

PARAMETERS

driver A pointer to the driver's private data that was passed in via
the m_pdata member of the mac_register(9S) structure to the
mac_register(9F) function.

add A boolean value that indicates whether the device driver
should add the specified address to its filter list or remove
it.

mac A pointer to an array of bytes that contains the new
multicast address being added or removed. It is guaranteed
to be at least a number of bytes long equal to the length of
the MAC plugin's address length. For Ethernet devices that
length is six bytes, ETHERADDRL.

DESCRIPTION

The mc_multicst() entry point is used to program a device driver's
multicast filters. For more background on filter management, see the MAC
Address Filter Management section in mac(9E).

The device driver can optionally sanity check mac by making sure that it's
both a valid multicast address and by checking whether or not it's already
programmed the address. Based on the value of add, the driver should
either add the specified address, mac, or remove it from its filter tables.
The device driver is not responsible for any form of reference counting on
these requests: that is maintained by the broader framework.

The device driver can access its own device soft state by casting the
device pointer. The device driver should employ the appropriate locking
while updating and manipulating its filter tables and its own records. It
is recommended that device drivers always maintain a copy of the addresses
programmed into the device's filter tables so that they can more easily
recover from various device resets and errors, or handle requests to
suspend and resume the device that may result in the device registers being
cleared.

RETURN VALUES

Upon successful completion, the device driver should return 0. Otherwise,
the driver should return a positive error number to indicate why the
request failed.

EXAMPLES

The following example shows how a device driver might structure its
mc_multicst() entry point.

#include <sys/mac_provider.h>

/*
* Note, this example merely shows the structure of this function.
* Different devices will have different ways to manage the set of
* multicast MAC addresses that they can program into their filters and
* they have different ways of keeping track of them. Like other
* examples, this assumes that there is a lock which protects this data.
* In this case we assume we have an array of structures that is used to
* track each multicast entry and a count of valid entries.
*/

#define EXAMPLE_NMULTICAST_ADDRS 100

static int
example_multicast_add(example_t *ep, const uint8_t *mac_addr)
{
int i, ret;

mutex_enter(&ep->ep_lock);
for (i = 0; i < ep->ep_nmcast_addrs; i++) {
if (bcmp(ep->ep_nmcast_addrs[i].ema_addr, mac_addr,
ETHERADDRL) == 0) {
/*
* The address is alread in our list, so we can
* return and say we're done.
*/
mutex_exit(&ep->ep_lock);
return (0);
}
}

/*
* We need to add this multicast address to a filter, make sure
* we have enough space to do so.
*/
if (ep->ep_nmcast_addrs >= EXAMPLE_NMULTICAST_ADDRS) {
mutex_exit(&ep->ep_lock);
return (ENOSPC);
}

/*
* Program the device before we add it to our list. Assume zero
* means success.
*/
ret = example_program_add_mcast_filter(ep, mac_addr);
if (ret == 0) {
bcopy(mac_addr,
ep->ep_nmcast_addrs[ep->ep_nmcast_addrs].ema_addr,
ETHERADDRL);
ep->ep_nmcast_addrs++;
}

mutex_exit(&ep->ep_lock);

return (ret);
}

static int
example_multicast_remove(example_t *ep, const uint8_t *mac_addr)
{
int i, ret;
boolean_t found = B_FALSE;

mutex_enter(&ep->ep_lock);
for (i = 0; i < ep->ep_nmcast_addrs; i++) {
if (bcmp(ep->ep_mcast_addrs[i].ema_addr, mac_addr,
ETHERADDRL) == 0) {
found = B_TRUE;
break;
}
}

if (found == B_FALSE) {
mutex_exit(&ep->ep_lock);
return (ENOENT);
}

/*
* Assume that a return value of zero indicates that the removal
* was successful. Note that i still has the index of this
* entry.
*/
ret = example_program_rem_mcast_filter(ep, mac_addr);
if (ret == 0) {
int last = ep->ep_nmcast_addrs - 1;
if (i != last) {
bcopy(ep->ep_mcast_addrs[last].ema_addr,
ep->ep_mcast_addrs[i].ema_addr,
ETHERADDRL);
}
bzero(ep->ep_mcast_addrs[last].ema_addr,
ETHERADDRL);
VERIFY(ep->ep_nmcast_addrs > 0);
ep->ep_nmcast_addrs--;
}

mutex_exit(&ep->ep_lock);
return (ret);
}

static int
example_m_multicst(void *arg, boolean_t add, const uint8_t *mac_addr)
{
example_t *ep = arg;

/*
* We sanity check that we've been given a multicast address.
*/
if ((mac_addr[0] & 0x01) == 0)
return (EINVAL);

if (add)
return (example_multicast_add(ep, mac_addr);
else
return (example_multicast_remove(ep, mac_addr));
}

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.

EINVAL The address mac is not a valid unicast address.

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

ENOENT The device driver was asked to remove a multicast
address that it does not have.

ENOSPC The driver was asked to add a multicast address;
however, it has no more filter slots available to
program the entry.