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

mac_callbacks, mac_callbacks_t — networking device driver entry points structure

#include <sys/mac_provider.h>

illumos DDI specific

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

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

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:

Indicates that the mc_ioctl structure member has been set.
Indicates that the mc_getcapab structure member has been set.
Indicates that the mc_open structure member has been set.
Indicates that the mc_close structure member has been set.
Indicates that the mc_setprop structure member has been set.
Indicates that the mc_getprop structure member has been set.
Indicates that the mc_propinfo structure member has been set.
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).

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

  • mc_getstat
  • mc_start
  • mc_stop
  • mc_setpromisc
  • mc_multicst
  • mc_tx
  • 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).

dlpi(4P), dladm(8), mac(9E), mac_capab_rings(9E), mc_close(9E), mc_getcapab(9E), mc_getprop(9E), mc_getstat(9E), mc_ioctl(9E), mc_multicst(9E), mc_open(9E), mc_propinfo(9E), mc_setpromisc(9E), mc_setprop(9E), mc_start(9E), mc_stop(9E), mc_tx(9E), mc_unicst(9E), mac_register(9F), mac_register(9S)

July 2, 2022 OmniOS