Tribblix: manual page: mc

MC_GETSTAT(9E) Driver Entry Points MC_GETSTAT(9E)

NAME

mc_getstat - get device statistics information

SYNOPSIS

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

int
prefix_m_getstat(void *driver, uint_t stat, uint64_t *stat_value);

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.

stat The numeric identifier of a statistic.

stat_value A pointer to a 64-bit unsigned value in which the device
driver should place the statistic.

DESCRIPTION

The mc_getstat() entry point is used to get statistics from the device
driver. Statistics are stored as monotonic values. They should only
ever increase over the lifetime of a device, resetting only as part of
the instance of a device attaching and detaching. When hardware has
values that may overflow, it is up to the device driver to store them
as a 64-bit quantity that does not overflow in its soft state.

Most device drivers will use a switch statement, switching on the value
of the statistic stat. The full list of supported statistics is
available in the STATISTICS section of mac(9E).

If a device driver recognizes the value of stat, then it should store
the current 64-bit unsigned integer into stat_value. If the device
driver does not support the statistic or does not recognize the
requested statistic, then it should not set anything in stat_value and
instead return ENOTSUP.

The device driver can obtain access to its soft state through the
driver member. It should be cast to the appropriate structure. The
device driver should employ any necessary locking to access the
statistic members of its soft state to ensure that the data is properly
serialized.

RETURN VALUES

Upon successful completion, the device driver should fill in stat_value
and return 0. Otherwise it should return a non-zero error number to
indicate an error occurred.

EXAMPLES

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

#include <sys/mac_provider.h>
#include <sys/mac_ether.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 its stats and that it has a lock which is
* used to serialize access to this data.
*/

static int
example_m_getstat(void *arg, uint_t stat, uint64_t *val)
{
example_t *ep = arg;

mutex_enter(&ep->ep_lock);
switch (stat) {
case MAC_STAT_RBYTES:
*val = ep->ep_stats.eps_rbytes;
break;
case MAC_STAT_OBYTES:
*val = ep->ep_stats.eps_obytes;
break;
case MAC_STAT_IPACKETS:
*val = ep->ep_stats.eps_ipackets;
break;
case MAC_STAT_OPACKETS:
*val = ep->ep_stats.eps_opackets;
break;

/*
* Note, there are many more stats that should be checked and
* filled in if supported. You should use one case statement for
* each stat.
*/

default:
mutex_exit(&ep->ep_lock);
return (ENOTSUP);
}
mutex_exit(&ep->ep_lock);

return (0);
}

ERRORS

The device driver may return one of the following errors. While this
list is not intended to be exhaustive, it is recommended to use one of
these if possible.

ENOTSUP The specified statistic is unknown, unsupported, or
unimplemented.

EIO A transport or DMA FM related error occurred while
trying to sync data from the device.

ECANCELLED The device is not currently in a state where it can
currently service the request.