man pages section 9: DDI and DKI Kernel Functions

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 service 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 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_free() function frees a mac_register structure previously allocated 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 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().

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