usr/src/man/man9e/mc_getstat.9e

   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
  30 illumos DDI specific
  31 .Sh PARAMETERS
  32 .Bl -tag -width Fa
  33 .It Fa driver
  34 A pointer to the driver's private data that was passed in via the
  35 .Sy m_pdata
  36 member of the
  37 .Xr mac_register 9S
  38 structure to the
  39 .Xr mac_register 9F
  40 function.
  41 .It Fa stat
  42 The numeric identifier of a statistic.
  43 .It Fa stat_value
  44 A pointer to a 64-bit unsigned value in which the device driver should
  45 place the statistic.
  46 .El
  47 .Sh DESCRIPTION
  48 The
  49 .Fn mc_getstat
  50 entry point is used to get statistics from the device driver.
  51 Statistics are stored as monotonic values.
  52 They should only ever increase over the lifetime of a device, resetting only as
  53 part of the instance of a device attaching and detaching.
  54 When hardware has values that may overflow, it is up to the device driver to
  55 store them as a 64-bit quantity that does not overflow in its soft state.
  56 .Pp
  57 Most device drivers will use a
  58 .Sy switch
  59 statement, switching on the value of the statistic
  60 .Fa stat .
  61 The full list of supported statistics is available in the
  62 .Sx STATISTICS
  63 section of
  64 .Xr mac 9E .
  65 .Pp
  66 If a device driver recognizes the value of
  67 .Fa stat ,
  68 then it should store the current 64-bit unsigned integer into
  69 .Fa stat_value .
  70 If the device driver does not support the statistic or does not
  71 recognize the requested statistic, then it should not set anything in
  72 .Fa stat_value
  73 and instead return
  74 .Er ENOTSUP .
  75 .Pp
  76 The device driver can obtain access to its soft state through the
  77 .Fa driver
  78 member.
  79 It should be cast to the appropriate structure.
  80 The device driver should employ any necessary locking to access the statistic
  81 members of its soft state to ensure that the data is properly serialized.
  82 .Sh RETURN VALUES
  83 Upon successful completion, the device driver should fill in
  84 .Fa stat_value
  85 and return
  86 .Sy 0 .
  87 Otherwise it should return a non-zero error number to indicate an error
  88 occurred.
  89 .Sh EXAMPLES
  90 The following example shows how a driver might structure its
  91 .Fn mc_getstat
  92 entry 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
 104 static int
 105 example_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
 140 The device driver may return one of the following errors.
 141 While this list is not intended to be exhaustive, it is recommended to use one
 142 of these if possible.
 143 .Bl -tag -width Er
 144 .It Er ENOTSUP
 145 The specified statistic is unknown, unsupported, or unimplemented.
 146 .It Er EIO
 147 A transport or DMA FM related error occurred while trying to sync data
 148 from the device.
 149 .It Er ECANCELLED
 150 The device is not currently in a state where it can currently service
 151 the request.
 152 .El
 153 .Sh SEE ALSO
 154 .Xr mac 9E ,
 155 .Xr mac_register 9F ,
 156 .Xr mac_register 9S