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