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 structure are initialized to 0. The device driver must
initialize the structure 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_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 subsequently 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_unregister() returns a non-zero error as described by Intro(2) on failure.
In this case the driver's detach() entry point should return DDI_FAILURE.

The mac_tx_update() function should be called by the driver to reschedule 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 argument
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 holding 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().