Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9e/mc_getprop.9e
+++ new/usr/src/man/man9e/mc_getprop.9e
1 1 .\"
2 2 .\" This file and its contents are supplied under the terms of the
3 3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
|
↓ open down ↓ |
3 lines elided |
↑ open up ↑ |
4 4 .\" You may only use this file in accordance with the terms of version
5 5 .\" 1.0 of the CDDL.
6 6 .\"
7 7 .\" A full copy of the text of the CDDL should have accompanied this
8 8 .\" source. A copy of the CDDL is also available via the Internet at
9 9 .\" http://www.illumos.org/license/CDDL.
10 10 .\"
11 11 .\"
12 12 .\" Copyright 2016 Joyent, Inc.
13 13 .\"
14 -.Dd November 15, 2016
14 +.Dd February 15, 2020
15 15 .Dt MC_GETPROP 9E
16 16 .Os
17 17 .Sh NAME
18 18 .Nm mc_getprop
19 19 .Nd get device properties
20 20 .Sh SYNOPSIS
21 21 .In sys/mac_provider.h
22 22 .Ft int
23 23 .Fo prefix_m_getprop
24 24 .Fa "void *driver"
25 25 .Fa "const char *pr_name"
26 26 .Fa "mac_prop_id_t pr_num"
27 27 .Fa "uint_t pr_valsize"
28 28 .Fa "void *pr_val"
29 29 .Fc
30 30 .Sh INTERFACE LEVEL
31 31 illumos DDI specific
32 32 .Sh PARAMETERS
33 33 .Bl -tag -width Fa
34 34 .It Fa driver
35 35 A pointer to the driver's private data that was passed in via the
36 36 .Sy m_pdata
37 37 member of the
38 38 .Xr mac_register 9S
39 39 structure to the
40 40 .Xr mac_register 9F
41 41 function.
42 42 .It Fa pr_name
43 43 A null-terminated string that contains the name of the property.
44 44 .It Fa pr_num
45 45 A constant that is used to identify the property.
46 46 .It Fa pr_valsize
47 47 A value that indicates the size in bytes of
48 48 .Fa pr_val .
49 49 .It Fa pr_val
50 50 A pointer to a
51 51 .Fa pr_valsize
52 52 byte buffer that can store the property.
53 53 .El
54 54 .Sh DESCRIPTION
55 55 The
56 56 .Fn mc_getprop
57 57 entry point is used to obtain the value of a given device's property and
58 58 place it into
59 59 .Fa pr_val .
60 60 .Pp
61 61 When the
62 62 .Fn mc_getprop
63 63 entry point is called, the driver needs to first identify the property.
64 64 The set of possible properties and their meaning is listed in the
65 65 .Sx PROPERTIES
66 66 section of
67 67 .Xr mac 9E .
68 68 It should identify the property based on the value of
69 69 .Fa pr_num .
70 70 Most drivers will use a
71 71 .Sy switch
72 72 statement and for any property that it supports it should then check if
73 73 the value in
74 74 .Fa pr_valsize
75 75 is sufficient for the property, comparing it to the minimum size
76 76 listed for the property in
77 77 .Xr mac 9E .
78 78 If it is not, then it should return an error.
79 79 Otherwise, it should copy the property's value into
80 80 .Fa pr_val .
81 81 When an unknown or unsupported
82 82 property is encountered, generally the
83 83 .Sy default
84 84 case of the switch statement, the device driver should return an error.
85 85 .Pp
86 86 The special property
87 87 .Sy MAC_PROP_PRIVATE
88 88 indicates that this is a device driver specific private property.
89 89 The device driver must then look at the value of the
90 90 .Fa pr_name
91 91 argument and use
92 92 .Xr strcmp 9F
93 93 on it, comparing it to each of its private (bounded-size) properties to
94 94 identify which one it is.
95 95 .Pp
96 96 At this time, private properties are limited to being string based properties.
97 97 If other types of property values are used, they will not be rendered
98 98 correctly by
99 99 .Xr dladm 1M .
100 100 .Pp
101 101 The device
102 102 driver can access its device soft state by casting the
103 103 .Fa device
104 104 pointer to the appropriate structure.
105 105 As this may be called while other operations are ongoing, the device driver
106 106 should employ the appropriate locking while reading the properties.
107 107 .Sh CONTEXT
108 108 The
109 109 .Fn mc_getprop
110 110 function is generally called from
111 111 .Sy kernel
112 112 context.
113 113 .Sh RETURN VALUES
114 114 Upon successful completion, the device driver should have copied the
115 115 value of the property into
116 116 .Fa pr_val
117 117 and return
118 118 .Sy 0 .
119 119 Otherwise, a positive error should be returned to indicate failure.
120 120 .Sh EXAMPLES
121 121 The following example shows how a device driver might structure its
122 122 .Fn mc_getprop
123 123 entry point.
124 124 .Bd -literal
125 125 #include <sys/mac_provider.h>
126 126
127 127 /*
128 128 * Note, this example merely shows the structure of this function.
129 129 * Different devices will manage their state in different ways. Like other
130 130 * examples, this assumes that the device has state in a structure called
131 131 * example_t and that there is a lock which keeps track of that state.
132 132 */
133 133 static char *example_priv_props[] = {
134 134 "_rx_intr_throttle",
135 135 "_tx_intr_throttle",
136 136 NULL
137 137 };
|
↓ open down ↓ |
113 lines elided |
↑ open up ↑ |
138 138
139 139 static int
140 140 example_m_getprop_private(example_t *ep, const char *pr_name, uint_t pr_valsize,
141 141 void *pr_val)
142 142 {
143 143 uint32_t val;
144 144
145 145 ASSERT(MUTEX_HELD(&ep->ep_lock));
146 146 if (strcmp(pr_name, example_priv_props[0] == 0) {
147 147 val = ep->ep_rx_itr;
148 - } else if (strcmp(pr_name, exampe_priv_props[1] == 0) {
148 + } else if (strcmp(pr_name, example_priv_props[1] == 0) {
149 149 val = ep->ep_tx_itr;
150 150 } else {
151 151 return (ENOTSUP);
152 152 }
153 153
154 154 /*
155 155 * Due to issues in the GLDv3, these must be returned as string
156 156 * properties.
157 157 */
158 158 if (snprintf(pr_val, pr_valsize, "%d", val) >= pr_valsize)
159 159 return (EOVERFLOW);
160 160
161 161 return (0);
162 162 }
163 163
164 164 static int
165 165 example_m_getprop(void *arg, const char *pr_name, mac_prop_id_t pr_num,
166 166 uint_t pr_valsize, void *pr_val)
167 167 {
168 168 int ret = 0;
169 169 uint64_t speed;
170 170 example_t *ep = arg;
171 171
172 172 mutex_enter(&ep->ep_lock);
173 173
174 174 /*
175 175 * This only handles a subset of the properties that exist on the
176 176 * system. A proper driver will need to handle more. See mac(9E) for a
177 177 * full property list.
178 178 */
179 179 switch (pr_num) {
180 180 case MAC_PROP_DUPLEX:
181 181 if (pr_valsize < sizeof (link_duplex_t)) {
182 182 ret = EOVERFLOW;
183 183 break;
184 184 }
185 185 bcopy(ep->ep_link_duplex, pr_val, sizeof (link_duplex_t));
186 186 case MAC_PROP_SPEED:
187 187 if (pr_valsize < sizeof (uint64_t)) {
188 188 ret = EOVERFLOW;
189 189 break;
190 190 }
191 191 /*
192 192 * The link speed is stored in Mbits/s in this driver and is
193 193 * expected in bits/s.
194 194 */
195 195 speed = ep->ep_link_speed * 1000000ULL;
196 196 bcopy(&speed, pr_val, sizeof (speed));
197 197 break;
198 198 case MAC_PROP_MTU:
199 199 if (pr_valsize < sizeof (uint32_t)) {
200 200 ret = EOVERFLOW;
201 201 break;
202 202 }
203 203 bcopy(&ep->ep_mtu, pr_val, sizeof (speed));
204 204 break;
205 205 case MAC_PROP_PRIVATE:
206 206 ret = example_m_getprop_private(ep, pr_name, pr_valsize,
207 207 pr_val);
208 208 break;
209 209 default:
210 210 ret = ENOTSUP;
211 211 break;
212 212 }
213 213
214 214 mutex_exit(&ep->ep_lock);
215 215
216 216 return (ret);
217 217 }
218 218 .Ed
219 219 .Sh ERRORS
220 220 The device driver may return one of the following errors.
221 221 While this list is not intended to be exhaustive, it is recommended to use one
222 222 of these if possible.
223 223 .Bl -tag -width Er
224 224 .It Er ENOTSUP
225 225 This error should be used whenever an unknown or unsupported property is
226 226 encountered.
227 227 .It Er EOVERFLOW
228 228 This error should be used when
229 229 .Fa pr_valsize
230 230 is smaller than the required size for a given value.
231 231 .El
232 232 .Sh SEE ALSO
233 233 .Xr mac 9E ,
234 234 .Xr mac_register 9F ,
235 235 .Xr strcmp 9F ,
236 236 .Xr mac_register 9S
|
↓ open down ↓ |
78 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX