Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9e/mc_setprop.9e
+++ new/usr/src/man/man9e/mc_setprop.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 June 02, 2016
14 +.Dd February 15, 2020
15 15 .Dt MC_SETPROP 9E
16 16 .Os
17 17 .Sh NAME
18 18 .Nm mc_setprop
19 19 .Nd set device properties
20 20 .Sh SYNOPSIS
21 21 .In sys/mac_provider.h
22 22 .Ft int
23 23 .Fo prefix_m_setprop
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 "const 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 contains the new value of the property.
53 53 .El
54 54 .Sh DESCRIPTION
55 55 The
56 56 .Fn mc_setprop
57 57 entry point is used to set the value of a given device's property from
58 58 the copy stored in
59 59 .Fa pr_val .
60 60 .Pp
61 61 When the
62 62 .Fn mc_setprop
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 update the property based on the value in
80 80 .Fa pr_val .
81 81 When an unknown or unsupported property is encountered, generally the
82 82 .Sy default
83 83 case of the switch statement, the device driver should return an error.
84 84 .Pp
85 85 The special property
86 86 .Sy MAC_PROP_PRIVATE
87 87 indicates that this is a device driver specific private property.
88 88 The device driver must then look at the value of the
89 89 .Fa pr_name
90 90 argument and use
91 91 .Xr strcmp 9F
92 92 on it, comparing it to each of its private properties to identify which
93 93 one it is.
94 94 .Pp
95 95 Not all properties are supposed to be writable.
96 96 Some devices may opt to not allow a property that is designated as read/write to
97 97 be set.
98 98 When such a property is encountered, the driver should return the appropriate
99 99 error.
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
|
↓ open down ↓ |
81 lines elided |
↑ open up ↑ |
106 106 should employ the appropriate locking while writing the properties.
107 107 .Sh RETURN VALUES
108 108 Upon successful completion, the device driver should have copied the
109 109 value of the property into
110 110 .Fa pr_val
111 111 and return
112 112 .Sy 0 .
113 113 Otherwise, a positive error should be returned to indicate failure.
114 114 .Sh EXAMPLES
115 115 The following examples shows how a device driver might structure its
116 -.Fn mc_setporp
116 +.Fn mc_setprop
117 117 entry point.
118 118 .Bd -literal
119 119 #include <sys/mac_provider.h>
120 120
121 121 /*
122 122 * Note, this example merely shows the structure of this function.
123 123 * Different devices will manage their state in different ways. Like other
124 124 * examples, this assumes that the device has state in a structure called
125 125 * example_t and that there is a lock which keeps track of that state.
126 126 *
127 127 * For the purpose of this example, we assume that this device supports 100 Mb,
128 128 * 1 GB, and 10 Gb full duplex speeds.
129 129 */
130 130
131 131 static int
132 -exmple_m_setprop(void *arg, const char *pr_name, mac_prop_id_t pr_num,
132 +example_m_setprop(void *arg, const char *pr_name, mac_prop_id_t pr_num,
133 133 uint_t pr_valsize, const void *pr_val)
134 134 {
135 135 uint32_t new_mtu;
136 136 int ret = 0;
137 137 example_t *ep = arg;
138 138
139 139 mutex_enter(&ep->ep_lock);
140 140 switch (pr_num) {
141 141 /*
142 142 * These represent properties that can never be changed, regardless of
143 143 * the type of PHY on the device (copper, fiber, etc.)
144 144 */
145 145 case MAC_PROP_DUPLEX:
146 146 case MAC_PROP_SPEED:
147 147 case MAC_PROP_STATUS:
148 148 case MAC_PROP_ADV_100FDX_CAP:
149 149 case MAC_PROP_ADV_1000FDX_CAP:
150 150 case MAC_PROP_ADV_10GFDX_CAP:
151 151 ret = ENOTSUP;
152 152 break;
153 153
154 154 /*
155 155 * These EN properties are used to control the advertised speeds of the
156 156 * device. For this example, we assume that this device does not have a
157 157 * copper phy, at which point auto-negotiation and the speeds in
158 158 * question cannot be changed. These are called out separately as they
159 159 * should be controllable for copper based devices or it may need to be
160 160 * conditional depending on the type of phy present.
161 161 */
162 162 case MAC_PROP_EN_100FDX_CAP:
163 163 case MAC_PROP_EN_1000FDX_CAP:
164 164 case MAC_PROP_EN_10GFDX_CAP:
165 165 case MAC_PROP_AUTONEG:
166 166 ret = ENOTSUP;
167 167 break;
168 168
169 169 case MAC_PROP_MTU:
170 170 if (pr_valsize < sizeof (uint32_t)) {
171 171 ret = EOVERFLOW;
172 172 break;
173 173 }
174 174 bcopy(&new_mtu, pr_val, sizeof (uint32_t));
175 175
176 176 if (new_mtu < ep->ep_min_mtu ||
177 177 new_mtu > ep->ep_max_mtu) {
178 178 ret = EINVAL;
179 179 break;
180 180 }
181 181
182 182 /*
183 183 * We first ask MAC to update the MTU before we do anything.
184 184 * This may fail. It returns zero on success. The
185 185 * example_update_mtu function does device specific updates to
186 186 * ensure that the MTU on the device is updated and any internal
187 187 * data structures are up to date.
188 188 */
189 189 ret = mac_maxdsu_update(&ep->ep_mac_hdl, new_mtu);
190 190 if (ret == 0) {
191 191 example_update_mtu(ep, new_mtu);
192 192 }
193 193 break;
194 194
195 195 /*
196 196 * Devices may have their own private properties. If they do, they
197 197 * should not return ENOTSUP, but instead see if it's a property they
198 198 * recognize and handle it similar to those above. If it doesn't
199 199 * recognize the name, then it should return ENOTSUP.
200 200 */
201 201 case MAC_PROP_PRIVATE:
202 202 ret = ENOTSUP;
203 203 break;
204 204
205 205 default:
206 206 ret = ENOTSUP;
207 207 break;
208 208 }
209 209 mutex_exit(&ep->ep_lock);
210 210
211 211 return (ret);
212 212 }
213 213 .Ed
214 214 .Sh ERRORS
215 215 The device driver may return one of the following errors.
216 216 While this list is not intended to be exhaustive, it is recommended to use one
217 217 of these if possible.
218 218 .Bl -tag -width Er
219 219 .It Er EINVAL
220 220 The contents of
221 221 .Fa pr_val
222 222 are outside the valid range for the property.
223 223 .It Er ENOTSUP
224 224 This error should be used whenever an unknown or unsupported property is
225 225 encountered.
226 226 It should also be used when the property is not writable.
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 .It Er EBUSY
232 232 This error should be used when a property can't be set because the
233 233 device has started.
234 234 Note that device driver writers are encouraged to design device drivers such
235 235 that this error is not possible.
236 236 .It Er ECANCELLED
237 237 The device is in a state that does not allow it to handle data;
238 238 for example, it's suspended.
239 239 .El
240 240 .Sh SEE ALSO
241 241 .Xr mac 9E ,
242 242 .Xr mac_register 9F ,
243 243 .Xr strcmp 9F ,
244 244 .Xr mac_register 9S
|
↓ open down ↓ |
102 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX