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 February 15, 2020 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 31illumos DDI specific 32.Sh PARAMETERS 33.Bl -tag -width Fa 34.It Fa driver 35A pointer to the driver's private data that was passed in via the 36.Sy m_pdata 37member of the 38.Xr mac_register 9S 39structure to the 40.Xr mac_register 9F 41function. 42.It Fa pr_name 43A null-terminated string that contains the name of the property. 44.It Fa pr_num 45A constant that is used to identify the property. 46.It Fa pr_valsize 47A value that indicates the size in bytes of 48.Fa pr_val . 49.It Fa pr_val 50A pointer to a 51.Fa pr_valsize 52byte buffer that contains the new value of the property. 53.El 54.Sh DESCRIPTION 55The 56.Fn mc_setprop 57entry point is used to set the value of a given device's property from 58the copy stored in 59.Fa pr_val . 60.Pp 61When the 62.Fn mc_setprop 63entry point is called, the driver needs to first identify the property. 64The set of possible properties and their meaning is listed in the 65.Sy PROPERTIES 66section of 67.Xr mac 9E . 68It should identify the property based on the value of 69.Fa pr_num . 70Most drivers will use a 71.Sy switch 72statement and for any property that it supports it should then check if 73the value in 74.Fa pr_valsize 75is sufficient for the property, comparing it to the minimum size 76listed for the property in 77.Xr mac 9E . 78If it is not, then it should return an error. 79Otherwise, it should update the property based on the value in 80.Fa pr_val . 81When an unknown or unsupported property is encountered, generally the 82.Sy default 83case of the switch statement, the device driver should return an error. 84.Pp 85The special property 86.Sy MAC_PROP_PRIVATE 87indicates that this is a device driver specific private property. 88The device driver must then look at the value of the 89.Fa pr_name 90argument and use 91.Xr strcmp 9F 92on it, comparing it to each of its private properties to identify which 93one it is. 94.Pp 95Not all properties are supposed to be writable. 96Some devices may opt to not allow a property that is designated as read/write to 97be set. 98When such a property is encountered, the driver should return the appropriate 99error. 100.Pp 101The device 102driver can access its device soft state by casting the 103.Fa device 104pointer to the appropriate structure. 105As this may be called while other operations are ongoing, the device driver 106should employ the appropriate locking while writing the properties. 107.Sh RETURN VALUES 108Upon successful completion, the device driver should have copied the 109value of the property into 110.Fa pr_val 111and return 112.Sy 0 . 113Otherwise, a positive error should be returned to indicate failure. 114.Sh EXAMPLES 115The following examples shows how a device driver might structure its 116.Fn mc_setprop 117entry 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 131static int 132example_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 215The device driver may return one of the following errors. 216While this list is not intended to be exhaustive, it is recommended to use one 217of these if possible. 218.Bl -tag -width Er 219.It Er EINVAL 220The contents of 221.Fa pr_val 222are outside the valid range for the property. 223.It Er ENOTSUP 224This error should be used whenever an unknown or unsupported property is 225encountered. 226It should also be used when the property is not writable. 227.It Er EOVERFLOW 228This error should be used when 229.Fa pr_valsize 230is smaller than the required size for a given value. 231.It Er EBUSY 232This error should be used when a property can't be set because the 233device has started. 234Note that device driver writers are encouraged to design device drivers such 235that this error is not possible. 236.It Er ECANCELLED 237The device is in a state that does not allow it to handle data; 238for 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 245