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