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