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