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 (c) 2017, Joyent, Inc. 13.\" Copyright 2022 Oxide Computer Company 14.\" 15.Dd July 2, 2022 16.Dt MRI_STAT 9E 17.Os 18.Sh NAME 19.Nm mri_stat 20.Nd xtatistics collection entry point for rings 21.Sh SYNOPSIS 22.In sys/mac_provider.h 23.Ft int 24.Fo prefix_ring_stat 25.Fa "mac_ring_driver_t rh" 26.Fa "uint_t stat" 27.Fa "uint64_t *val" 28.Fc 29.Sh INTERFACE LEVEL 30.Sy Uncommitted - 31This interface is still evolving. 32API and ABI stability is not guaranteed. 33.Sh PARAMETERS 34.Bl -tag -width Fa 35.It Fa rh 36A pointer to the ring's private data that was passed in via the 37.Vt mri_driver 38member of the 39.Xr mac_ring_info 9S 40structure as part of the 41.Xr mr_rget 9E 42entry point. 43.It Fa stat 44The numeric identifier of a statistic. 45.It Fa val 46A pointer to a 64-bit unsigned value into which the device driver should 47place statistic. 48.El 49.Sh DESCRIPTION 50The 51.Fn mri_stat 52entry point is called by the MAC framework to get statistics that have 53been scoped to the ring, indicated by 54.Fa rh . 55.Pp 56The set of statistics that the driver should check depends on the kind 57of ring that is in use. 58If the driver encounters an unknown statistic it should return 59.Er ENOTSUP . 60All the statistics should be values that are scoped to the ring itself. 61This is in contrast to the normal 62.Xr mc_getstat 9E 63entry point, which has statistics for the entire device. 64Other than the scoping, the statistics listed below have the same 65meaning as they do in the 66.Sx STATISTICS 67section of 68.Xr mac 9E . 69See 70.Xr mac 9E 71for more details of those statistics. 72.Pp 73Receive rings should support the following statistics: 74.Bl -bullet 75.It 76.Dv MAC_STAT_IPACKETS 77.It 78.Dv MAC_STAT_RBYTES 79.El 80.Pp 81Transmit rings should support the following statitics: 82.Bl -bullet 83.It 84.Dv MAC_STAT_OBYTES 85.It 86.Dv MAC_STAT_OPACKETS 87.El 88.Sh EXAMPLES 89The following example shows how a driver might structure its 90.Fn mri_stat 91entry point. 92.Bd -literal 93#include <sys/mac_provider.h> 94 95/* 96 * Note, this example merely shows the structure of the function. For 97 * the purpose of this example, we assume that we have a per-ring 98 * structure which has members that indicate its stats and that it has a 99 * lock which is used to serialize access to this data. 100 */ 101 102static int 103example_tx_ring_stat(mac_ring_driver_t rh, uint_t stat, uint64_t *val) 104{ 105 example_tx_ring_t *etrp = arg; 106 107 mutex_enter(&etrp->etrp_lock); 108 switch (stat) { 109 case MAC_STAT_OBYTES: 110 *val = etrp->etrp_stats.eps_obytes; 111 break; 112 case MAC_STAT_OPACKETS: 113 *val = etrp->etrp_stats.eps_opackets; 114 break; 115 default: 116 mutex_exit(&etrp->etrp_lock); 117 return (ENOTSUP); 118 } 119 mutex_exit(&etrp->etrp_lock); 120 121 return (0); 122} 123 124static int 125example_rx_ring_stat(mac_ring_driver_t rh, uint_t stat, uint64_t *val) 126{ 127 example_rx_ring_t *errp = arg; 128 129 mutex_enter(&errp->errp_lock); 130 switch (stat) { 131 case MAC_STAT_RBYTES: 132 *val = errp->errp_stats.eps_ibytes; 133 break; 134 case MAC_STAT_IPACKETS: 135 *val = errp->errp_stats.eps_ipackets; 136 break; 137 default: 138 mutex_exit(&errp->errp_lock); 139 return (ENOTSUP); 140 } 141 mutex_exit(&errp->errp_lock); 142 143 return (0); 144} 145.Ed 146.Sh ERRORS 147The device driver may return one of the following errors. 148While this list is not intended to be exhaustive, it is recommend to use 149one of these if possible. 150.Bl -tag -width Er 151.It Er ENOTSUP 152The specified statistic is unknown, unsupported, or unimplemented. 153.It Er EIO 154A transport or DMA FM related error occurred while trying to sync data 155from the device. 156.It Er ECANCELLED 157The device is not currently in a state where it can currently service 158the request. 159.El 160.Sh SEE ALSO 161.Xr mac 9E , 162.Xr mac_capab_rings 9E , 163.Xr mc_getstat 9E , 164.Xr mr_rget 9E , 165.Xr mac_ring_info 9S 166