1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2016 Joyent, Inc. 13.\" 14.Dd May 31, 2016 15.Dt MC_GETSTAT 9E 16.Os 17.Sh NAME 18.Nm mc_getstat 19.Nd get device statistics information 20.Sh SYNOPSIS 21.In sys/mac_provider.h 22.In sys/mac_ether.h 23.Ft int 24.Fo prefix_m_getstat 25.Fa "void *driver" 26.Fa "uint_t stat" 27.Fa "uint64_t *stat_value" 28.Fc 29.Sh INTERFACE LEVEL 30illumos DDI specific 31.Sh PARAMETERS 32.Bl -tag -width Fa 33.It Fa driver 34A pointer to the driver's private data that was passed in via the 35.Sy m_pdata 36member of the 37.Xr mac_register 9S 38structure to the 39.Xr mac_register 9F 40function. 41.It Fa stat 42The numeric identifier of a statistic. 43.It Fa stat_value 44A pointer to a 64-bit unsigned value in which the device driver should 45place the statistic. 46.El 47.Sh DESCRIPTION 48The 49.Fn mc_getstat 50entry point is used to get statistics from the device driver. 51Statistics are stored as monotonic values. 52They should only ever increase over the lifetime of a device, resetting only as 53part of the instance of a device attaching and detaching. 54When hardware has values that may overflow, it is up to the device driver to 55store them as a 64-bit quantity that does not overflow in its soft state. 56.Pp 57Most device drivers will use a 58.Sy switch 59statement, switching on the value of the statistic 60.Fa stat . 61The full list of supported statistics is available in the 62.Sx STATISTICS 63section of 64.Xr mac 9E . 65.Pp 66If a device driver recognizes the value of 67.Fa stat , 68then it should store the current 64-bit unsigned integer into 69.Fa stat_value . 70If the device driver does not support the statistic or does not 71recognize the requested statistic, then it should not set anything in 72.Fa stat_value 73and instead return 74.Er ENOTSUP . 75.Pp 76The device driver can obtain access to its soft state through the 77.Fa driver 78member. 79It should be cast to the appropriate structure. 80The device driver should employ any necessary locking to access the statistic 81members of its soft state to ensure that the data is properly serialized. 82.Sh RETURN VALUES 83Upon successful completion, the device driver should fill in 84.Fa stat_value 85and return 86.Sy 0 . 87Otherwise it should return a non-zero error number to indicate an error 88occurred. 89.Sh EXAMPLES 90The following example shows how a driver might structure its 91.Fn mc_getstat 92entry point. 93.Bd -literal 94#include <sys/mac_provider.h> 95#include <sys/mac_ether.h> 96 97/* 98 * Note, this example merely shows the structure of the function. For 99 * the purpose of this example, we assume that we have a device which 100 * has members that indicate its stats and that it has a lock which is 101 * used to serialize access to this data. 102 */ 103 104static int 105example_m_getstat(void *arg, uint_t stat, uint64_t *val) 106{ 107 example_t *ep = arg; 108 109 mutex_enter(&ep->ep_lock); 110 switch (stat) { 111 case MAC_STAT_RBYTES: 112 *val = ep->ep_stats.eps_rbytes; 113 break; 114 case MAC_STAT_OBYTES: 115 *val = ep->ep_stats.eps_obytes; 116 break; 117 case MAC_STAT_IPACKETS: 118 *val = ep->ep_stats.eps_ipackets; 119 break; 120 case MAC_STAT_OPACKETS: 121 *val = ep->ep_stats.eps_opackets; 122 break; 123 124 /* 125 * Note, there are many more stats that should be checked and 126 * filled in if supported. You should use one case statement for 127 * each stat. 128 */ 129 130 default: 131 mutex_exit(&ep->ep_lock); 132 return (ENOTSUP); 133 } 134 mutex_exit(&ep->ep_lock); 135 136 return (0); 137} 138.Ed 139.Sh ERRORS 140The device driver may return one of the following errors. 141While this list is not intended to be exhaustive, it is recommended to use one 142of these if possible. 143.Bl -tag -width Er 144.It Er ENOTSUP 145The specified statistic is unknown, unsupported, or unimplemented. 146.It Er EIO 147A transport or DMA FM related error occurred while trying to sync data 148from the device. 149.It Er ECANCELLED 150The device is not currently in a state where it can currently service 151the request. 152.El 153.Sh SEE ALSO 154.Xr mac 9E , 155.Xr mac_register 9F , 156.Xr mac_register 9S 157