illumos: manual page: mc

MC_GETCAPAB(9E) Driver Entry Points MC_GETCAPAB(9E)

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