NAME

mc_getcapab — get device capabilities

SYNOPSIS

#include <sys/mac_provider.h>

boolean_t
prefix_m_getcapab(void *driver, mac_capab_t capab, void *cap_data);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

driver: A pointer to the driver's private data that was passed in via the m_pdata member of the mac_register(9S) structure to the mac_register(9F) function.
capab: A value which indicates the capability being asked about. For a full list of capabilities, see the CAPABILITIES section of mac(9E).
cap_data: Capability specific data that may need to be filled in. The type of data used is listed in the CAPABILITIES section of mac(9E).

DESCRIPTION

The mc_getcapab() entry point is called to determine whether or not a device supports a specific capability. The capability in question is specified in capab and the list of possible capabilities is listed in the CAPABILITIES section of mac(9E).

Capabilities are generally only queried once for a given device. An instance of a device cannot change whether or not it supports a given capability after it has been queried by the system.

Each capability has its own specific kind of data that a device driver needs to fill in as part of declaring that it supports a given capability. That data is present in cap_data. The device driver should cast cap_data to the appropriate structure and fill it in. The structures to use for a given capability are all listed in the CAPABILITIES section of mac(9E).

The return value is used to indicate whether or not a device driver supports the given capability. If it does, then the device driver should return B_TRUE after filling in cap_data. Otherwise, whenever it encounters an unsupported or unknown capability, it should return B_FALSE. Many device drivers employ switch statements and return B_FALSE from their default case statement. The system will present unknown capabilities to device drivers and they must properly return B_FALSE.

The driver has access to its soft state by casting the driver argument to the specific structure. The device driver is responsible for any necessary locking.

Many capabilities are related to features of hardware. However, all hardware and firmware has the possibility of having bugs. It is recommended that any capability that is supported have some form of tunable, whether in the form of a MAC_PROP_PRIVATE driver-specific property and/or a driver.conf(5) property to disable it. This way when problems are discovered in the field, they can be worked around without requiring initial changes to the device driver.

CONTEXT

This function is generally only called from kernel context.

RETURN VALUES

If the device driver supports the specified capability capab, then it should return B_TRUE. Otherwise, it should return B_FALSE.

EXAMPLES

The following example shows how a driver might structure its mc_getcapab() entry point.

#include <sys/types.h>
#include <sys/mac_provider.h>

/*
 * Note, this example merely shows the structure of the function. For
 * the purpose of this example, we assume that we have a device which
 * has members that indicate whether the various capabilities have been
 * enabled and that they are read-only after the driver has had its
 * mc_start(9E) entry point called.
 */

#define	EXAMPLE_LSO_MAX		65535

static boolean_t
example_m_getcapab(void *arg, mac_capab_t cap, void *cap_data)
{
	example_t *ep = arg;

	switch (cap) {
	case MAC_CAPAB_HCKSUM: {
		uint32_t *txflags = cap_data;

		/*
		 * The actual flags used here should be replaced with
		 * what the device actually supports. If the device
		 * doesn't support checksums, then this case statement
		 * shouldn't exist.
		 */
		*txflags = 0;
		if (ep->ep_tx_hcksum_enable == B_TRUE)
			*txflags = HCKSUM_IPHDRCKSUM;
		break;
	}

	case MAC_CAPAB_LSO: {
		mac_capab_lso_t *lso = cap_data;

		if (ep->ep_lso_enable == B_TRUE) {
			lso->lso_flags = LSO_TX_BASIC_TCP_IPV4;
			lso->lso_basic_tcp_ipv4.lso_max = EXAMPLE_LSO_MAX;
		} else {
			return (B_FALSE);
		}
		break;
	}

	default:
		return (B_FALSE);
	}

	return (B_TRUE);
}