Tribblix: manual page: mac

MAC_CALLBACKS(9S) Data Structures for Drivers MAC_CALLBACKS(9S)

NAME

mac_callbacks, mac_callbacks_t - networking device driver entry points
structure

SYNOPSIS

#include <sys/mac_provider.h>

INTERFACE LEVEL

illumos DDI specific

DESCRIPTION

The mac_callbacks structure is used by GLDv3 networking device drivers
implementing and using the mac(9E) framework and interfaces.

The structure is normally allocated statically by drivers as a single
global entry. A pointer to it is passed as the m_callbacks member of
the mac_register_t structure.

TYPES

The following types define the function pointers in use in the
mac_register_t.

typedef int (*mac_getstat_t)(void *, uint_t, uint64_t *);
typedef int (*mac_start_t)(void *);
typedef void (*mac_stop_t)(void *);
typedef int (*mac_setpromisc_t)(void *, boolean_t);
typedef int (*mac_multicst_t)(void *, boolean_t, const uint8_t *);
typedef int (*mac_unicst_t)(void *, const uint8_t *);
typedef void (*mac_ioctl_t)(void *, queue_t *, mblk_t *);
typedef void (*mac_resources_t)(void *);
typedef mblk_t *(*mac_tx_t)(void *, mblk_t *);
typedef boolean_t (*mac_getcapab_t)(void *, mac_capab_t, void *);
typedef int (*mac_open_t)(void *);
typedef void (*mac_close_t)(void *);
typedef int (*mac_set_prop_t)(void *, const char *, mac_prop_id_t,
uint_t, const void *);
typedef int (*mac_get_prop_t)(void *, const char *, mac_prop_id_t,
uint_t, void *);
typedef void (*mac_prop_info_t)(void *, const char *, mac_prop_id_t,
mac_prop_info_handle_t);

STRUCTURE MEMBERS

uint_t mc_callbacks; /* Denotes which callbacks are set */
mac_getstat_t mc_getstat; /* Get the value of a statistic */
mac_start_t mc_start; /* Start the device */
mac_stop_t mc_stop; /* Stop the device */
mac_setpromisc_t mc_setpromisc; /* Enable or disable promiscuous mode */
mac_multicst_t mc_multicst; /* Enable or disable a multicast addr */
mac_unicst_t mc_unicst; /* Set the unicast MAC address */
mac_tx_t mc_tx; /* Transmit a packet */
void *mc_reserved; /* Reserved, do not use */
mac_ioctl_t mc_ioctl; /* Process an unknown ioctl */
mac_getcapab_t mc_getcapab; /* Get capability information */
mac_open_t mc_open; /* Open the device */
mac_close_t mc_close; /* Close the device */
mac_set_prop_t mc_setprop; /* Set a device property */
mac_get_prop_t mc_getprop; /* Get a device property */
mac_prop_info_t mc_propinfo; /* Get property information */

The mc_callbacks member is used to denote which of a series of optional
callbacks are present. This method allows additional members to be
added to the mac_callbacks_t structure while maintaining ABI
compatibility with existing modules. If a member is not mentioned
below, then it is a part of the base version of the structure and
device drivers do not need to set anything to indicate that it is
present. The mc_callbacks member should be set to the bitwise
inclusive OR of the following pre-processor values:

MC_IOCTL Indicates that the mc_ioctl structure member has
been set.

MC_GETCAPAB Indicates that the mc_getcapab structure member has
been set.

MC_OPEN Indicates that the mc_open structure member has
been set.

MC_CLOSE Indicates that the mc_close structure member has
been set.

MC_SETPROP Indicates that the mc_setprop structure member has
been set.

MC_GETPROP Indicates that the mc_getprop structure member has
been set.

MC_PROPINFO Indicates that the mc_propinfo structure member has
been set.

MC_PROPERTIES
Indicates that the mc_getprop, mc_propinfo, and
mc_setprop structure members have been set.

The mc_getstat function defines an entry point used to receive
statistics about the device. A list of statistics that it is required
to support is available in mac(9E). For more information on the
requirements of the function, see mc_getstat(9E).

The mc_start member defines an entry point that is used to start the
device. For more information on the requirements of the function, see
mc_start(9E).

The mc_stop member defines an entry point that is used to stop the
device. It is the opposite of the mc_start member. For more
information on the requirements of the function, see mc_stop(9E).

The mc_setpromisc member is used to enable and disable promiscuous mode
on the device. For more information on the requirements of the
function, see mc_setpromisc(9E).

The mc_multicst member is used to enable or disable multicast addresses
in the device's filters. For more information on the requirements of
the function, see mc_multicst(9E).

The mc_unicst member is used to set the primary unicast MAC address of
the device. For more information on the requirements of the function,
see mc_unicst(9E).

The mc_tx member is used to transmit a single message on the wire. For
more information on the requirements of the function, see mc_tx(9E).

The mc_ioctl member is used to process device specific ioctls. The MAC
framework does not define any ioctls that devices should handle;
however, there may be private ioctls for this device. This entry point
is optional. For it to be considered, the MC_IOCTL value must be
present in the mc_callbacks member. For more information on the
requirements of the function, see mc_ioctl(9E).

The mc_getcapab member is used to determine device capabilities. Each
capability has its own data and semantics associated with it. A list
of capabilities is provided in mac(9E). This entry point is optional.
For it to be used, the MC_GETCAPAB value must be present in the
mc_callbacks member. For more information on the requirements of the
function, see mc_getcapab(9E).

The mc_open member is used to provide specific actions to take when the
device is opened. Note that most device drivers will not have a need
to implement this. It is not required for this function to be
implemented for this device to be used with dlpi(4P). This entry point
is optional. For it to be used, the MC_OPEN value must be present in
the mc_callbacks member. For more information on the requirements of
the function, see mc_open(9E).

The mc_close member is used to provide specific actions to take when
the device is closed. Note that most device drivers will not have a
need to implement this. It is not required for this function to be
implemented for this device to be used with dlpi(4P). This entry point
is optional. For it to be used, the MC_CLOSE value must be present in
the mc_callbacks member. For more information on the requirements of
the function, see mc_close(9E).

The mc_getprop member is used to get the current value of a property
from the device. A list of properties, their sizes, and their
interpretation is available in mac(9E). This entry point is optional.
For it to be used, the MC_GETPROP value must be present in the
mc_callbacks member. For more information on the requirements of the
function, see mc_getprop(9E).

The mc_setprop member is used to set the value of a device property. A
list of properties, their sizes, and their interpretation is available
in mac(9E). This entry point is optional. For it to be used, the
MC_SETPROP value must be present in the mc_callbacks member. For more
information on the requirements of the function, see mc_setprop(9E).

The mc_propinfo member is used to obtain metadata about a property such
as its default value, whether or not it is writable, and more. A list
of properties, their sizes, and their interpretation is available in
mac(9E). This entry point is optional. For it to be used, the
MC_PROPINFO value must be present in the mc_callbacks member. For more
information on the requirements of the function, see mc_propinfo(9E).

Required Members

Many members in the structure are optional; however, the following
members must be set or a call to mac_register(9F) will fail.

+o mc_getstat

+o mc_start

+o mc_stop

+o mc_setpromisc

+o mc_multicst

+o mc_tx

+o mc_unicst

Devices which implement the MAC_CAPAB_RINGS capability for receive
rings must not implement the mc_unicst entry point. Devices which
implement the MAC_CAPAB_RINGS capability for transmit rings must not
implement the mc_tx entry points. For more information about the
capability, please see mac_capab_rings(9E).

Generally, a device that implements one of mc_getprop, mc_setprop, or
mc_propinfo will want to implement all three endpoints to ensure that
the property is fully integrated into user land utilities such as
dladm(8).