illumos: manual page: mac_callbacks

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 the mac(9E) interface.

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 GLDv3
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

Note, that devices which implement the GLDv3 ring capabilities must not
implement the mc_unicst and mc_tx functions. However, the ring
capabilities are still private and evolving at this time.

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).