mac(9F) Kernel Functions for Drivers mac(9F)NAME
mac, mac_alloc, mac_free, mac_register, mac_unregister, mac_tx_update,
mac_link_update, mac_rx, mac_init_ops, mac_fini_ops - MAC driver ser‐
vice routines
SYNOPSIS
#include <sys/mac_provider.h>
mac_register_t *mac_alloc(uint_t version);
void mac_free(mac_register_t *mregp);
int mac_register(mac_register_t *mregp, mac_handle_t *mhp);
int mac_unregister(mac_handle_t mh);
void mac_tx_update(mac_handle_t mh);
void mac_link_update(mac_handle_t mh, link_state_t new_state);
void mac_rx(mac_handle_t mh, void *reserved, mblk_t *mp_chain);
void mac_init_ops(struct dev_ops *ops, const char *name);
void mac_fini_ops(struct dev_ops *ops);
PARAMETERS
version MAC version
mh MAC handle
mhp pointer to a MAC handle
mregp pointer to a mac_register_t(9S) structure
reserved reserved argument
mp_chain chain of message blocks containing a received packet
new_state media link state
ops device operations structure
name device driver name
INTERFACE LEVEL
Solaris architecture specific (Solaris DDI)
DESCRIPTION
The mac_alloc() function allocates a new mac_register(9S) structure and
returns a pointer to it. The allocated structure may contain some MAC-
private elements. These private elements are initialized by the MAC
layer before mac_alloc() returns, and the other elements of the struc‐
ture are initialized to 0. The device driver must initialize the struc‐
ture members as described by mac_register before passing a pointer to
the structure to mac_register. The version argument should be set to
MAC_VERSION_V1.
The mac_free() function frees a mac_register structure previously allo‐
cated by mac_alloc().
The mac_register() function is called from the device driver's
attach(9E) entry point, and is used to register the MAC-based device
driver with the MAC layer. The mac_register() entry point is passed an
instance of the mac_registerstructure previously allocated by
mac_alloc().
On success, mac_register() returns 0 and sets mhp to point to a new MAC
handle corresponding to the new MAC instance. This MAC handle is subse‐
quently passed by the driver to the framework as an argument to other
MAC routines such as the ones described here. The attach() entry point
of the driver should return DDI_SUCCESS in this case. On failure,
mac_register() returns a non-zero error as described by Intro(2). The
attach() entry point of the driver should return DDI_FAILURE in this
case.
The mac_unregister() function is called by the driver from its
detach(9E) entry point to unregister the instance from the MAC layer.
It should pass the MAC handle which was previously obtained from
mac_register(). mac_unregister() returns 0 on success, in which case
the driver's detach() entry point should return DDI_SUCCESS. mac_unreg‐
ister() returns a non-zero error as described by Intro(2) on failure.
In this case the driver's detach() entry point should return DDI_FAIL‐
URE.
The mac_tx_update() function should be called by the driver to resched‐
ule stalled outbound packets. Whenever the driver's mc_tx(9E) has
returned a non-empty chain of packets, it must later mac_tx_update() to
inform the MAC layer that it should retry the packets that previously
could not be sent. mac_tx_update() should be called as soon as possible
after resources are again available, to ensure that MAC resumes passing
outbound packets to the driver's mc_tx() entry point.
The mac_link_update() function is called by the device driver to notify
the MAC layer of changes in the media link state. The new_state argu‐
ment must be set to one of the following:
LINK_STATE_UP The media link is up.
LINK_STATE_DOWN The media link is down.
LINK_STATE_UNKNOWN The media link is unknown.
The mac_rx() function is called by the driver's interrupt handler to
pass a chain of one or more packets to the MAC layer. Packets of a
chain are linked with the b_next pointer. The driver should avoid hold‐
ing mutex or other locks during the call to mac_rx(). In particular,
locks that could be taken by a transmit thread may not be held during a
call to mac_rx().
The mac_init_ops() function must be invoked from the _init(9E) entry
point of the device driver before a call to mod_install(9F). It is
passed a pointer to the device driver's operations structure, and the
name of the device driver.
The mac_fini_ops() function must be called from _fini(9E) before the
driver is unloaded after invoking mod_remove(9F), or before returning
from _init() in the case of an error returned by mod_install().
RETURN VALUES
The mac_alloc() function returns a pointer to a new mac_register(9S)
structure.
The mac_register() and mac_unregister() functions return a non-zero
error, as defined by Intro(2).
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWhea │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOIntro(2), attributes(5), attach(9E), detach(9E), _fini(9E), _init(9E),
mac(9E), mc_tx(9E), mod_install(9F), mod_remove(9F), dev_ops(9S),
mac_register(9S)SunOS 5.10 26 Mar 2010 mac(9F)
