, 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:

See Also

Intro(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)