Tribblix: manual page: mac

MAC_REGISTER(9F) Kernel Functions for Drivers MAC_REGISTER(9F)

NAME

mac_register, mac_unregister - register and unregister a device driver
from the MAC framework

SYNOPSIS

#include <sys/mac_provider.h>

int
mac_register(mac_register_t *mregp, mac_handle_t *mhp);

int
mac_unregister(mac_handle_t mh);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

mregp A pointer to a mac_register(9S) structure allocated by
calling mac_alloc(9F) and filled in by the device driver.

mhp A pointer to a driver-backed handle to the MAC framework.

mh The driver-backed handle to the MAC framework.

DESCRIPTION

The mac_register() function is used to register an instance of a device
driver with the mac(9E) framework. Upon successfully calling the
mac_register() function, the device will start having its
mac_callbacks(9S) entry points called. The device driver should call
this function during it's attach(9E) entry point after the device has
been configured and is set up. For a more detailed explanation of the
exact steps that the device driver should take and where in the
sequence of a driver's attach(9E) entry point this function should be
called, see the Registering with MAC section of mac(9E).

The driver should provide a pointer to a mac_handle_t structure as the
second argument to the mac_register() function. This handle will be
used when the device driver needs to interact with the framework in
various ways throughout its life. It is also where the driver gets the
mh argument for calling the mac_unregister() function. It is
recommended that the device driver keep the handle around in its soft
state structure for a given instance.

If the call to the mac_register() function fails, the device driver
should unwind its attach(9E) entry point, tear down everything that it
initialized, and ultimately return an error from its attach(9E) entry
point.

If the attach(9E) routine fails for some reason after the call to the
mac_register() function has succeeded, then the driver should call the
mac_unregister() function as part of unwinding all of its state.

When a driver is in its detach(9E) entry point, it should call the
mac_unregister() function immediately after draining any of its
transmit and receive resources that might have been given to the rest
of the operating system through DMA binding. See the MBLKS AND DMA
section of mac(9E) for more information. This should be done before
the driver does any tearing down. The call to the mac_unregister()
function may fail. This may happen because the networking stack is
still using the device. In such a case, the driver should fail the
call to detach(9E) and return DDI_FAILURE.

CONTEXT

The mac_register() function is generally only called from a driver's
attach(9E) entry point. The mac_unregister() function is generally
only called from a driver's attach(9E) and detach(9E) entry point.
However, both functions may be called from either user or kernel
context.

RETURN VALUES

Upon successful completion, the mac_register() and mac_unregister()
functions both return 0. Otherwise, they return an error number.

EXAMPLES

The following example shows how a device driver might call the
mac_register() function.

#include <sys/mac_provider.h>
#include <sys/mac_ether.h>

/*
* The call to mac_register(9F) generally comes from the context of
* attach(9E). This function encapsulates setting up and initializing
* the mac_register_t structure and should be assumed to be called from
* attach.
*
* The exact set of callbacks and private properties will vary based
* upon the driver.
*/

static char *example_priv_props[] = {
"_rx_intr_throttle",
"_tx_intr_throttle",
NULL
};

static mac_callbacks_t example_m_callbacks = {
.mc_callbacks = MC_GETCAPAB | MC_SETPROP | MC_GETPROP | MC_PROPINFO |
MC_IOCTL,
.mc_start = example_m_start,
.mc_stop = example_m_stop,
.mc_setpromisc = example_m_setpromisc,
.mc_multicst = example_m_multicst,
.mc_unicst = example_m_unicst,
.mc_tx = example_m_tx,
.mc_ioctl = example_m_ioctl,
.mc_getcapab = example_m_getcapab,
.mc_getprop = example_m_getprop,
.mc_setprop = example_m_setprop,
.mc_propinfo = example_m_propinfo
};

static boolean_t
example_register_mac(example_t *ep)
{
int status;
mac_register_t *mac;

mac = mac_alloc(MAC_VERSION);
if (mac == NULL)
return (B_FALSE);

mac->m_type_ident = MAC_PLUGIN_IDENT_ETHER;
mac->m_driver = ep;
mac->m_dip = ep->ep_dev_info;
mac->m_src_addr = ep->ep_mac_addr;
mac->m_callbacks = &example_m_callbacks;
mac->m_min_sdu = 0;
mac->m_max_sdu = ep->ep_sdu;
mac->m_margin = VLAN_TAGSZ;
mac->m_priv_props = example_priv_props;

status = mac_register(mac, &ep->ep_mac_hdl);
mac_free(mac);

return (status == 0);
}

ERRORS

The mac_register() function may fail if:

EEXIST A driver with the same name and instance already
exists.

EINVAL There was something invalid with the device's
registration information. Some of the following
reasons may apply, this list is not exhaustive:

+o The mac_init_ops(9F) function was not called.

+o The specified mac plugin does not exist.

+o An invalid minor number was used.

+o The default unicast source address was
incorrect.

+o The plugin specific private data was incorrect
or missing.

+o Plugin specific data was provided when none is
required.

+o Required callback functions are not specified.

+o The system was unable to properly create minor
nodes.

ENOSPC The mac(9E) framework was unable to allocate a minor
number for the device as they have all been
exhausted.

The mac_unregister() function will fail if:

EBUSY The device is still in use.

ENOTEMPTY The flow table is not empty.

Note the set of errors for both the mac_register() and mac_unregister()
functions are not set in stone and may be expanded in future revisions.
In general, all errors should be handled by the device driver in
similar ways for these functions.