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 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.Sx 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. Otherwise, it should 79update 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. The 88device 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. Some devices may opt to 96not allow a property that is designated as read/write to be set. When 97such a property is encountered, the driver should return the appropriate 98error. 99.Pp 100The device 101driver can access its device soft state by casting the 102.Fa device 103pointer to the appropriate structure. As this may be called while other 104operations are ongoing, the device driver should employ the appropriate 105locking while writing the properties. 106.Sh RETURN VALUES 107Upon successful completion, the device driver should have copied the 108value of the property into 109.Fa pr_val 110and return 111.Sy 0 . 112Otherwise, a positive error should be returned to indicate failure. 113.Sh EXAMPLES 114The following examples shows how a device driver might structure its 115.Fn mc_setporp 116entry point. 117.Bd -literal 118#include <sys/mac_provider.h> 119 120/* 121 * Note, this example merely shows the structure of this function. 122 * Different devices will manage their state in different ways. Like other 123 * examples, this assumes that the device has state in a structure called 124 * example_t and that there is a lock which keeps track of that state. 125 * 126 * For the purpose of this example, we assume that this device supports 100 Mb, 127 * 1 GB, and 10 Gb full duplex speeds. 128 */ 129 130static int 131exmple_m_setprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, 132 uint_t pr_valsize, const void *pr_val) 133{ 134 uint32_t new_mtu; 135 int ret = 0; 136 example_t *ep = arg; 137 138 mutex_enter(&ep->ep_lock); 139 switch (pr_num) { 140 /* 141 * These represent properties that can never be changed, regardless of 142 * the type of PHY on the device (copper, fiber, etc.) 143 */ 144 case MAC_PROP_DUPLEX: 145 case MAC_PROP_SPEED: 146 case MAC_PROP_STATUS: 147 case MAC_PROP_ADV_100FDX_CAP: 148 case MAC_PROP_ADV_1000FDX_CAP: 149 case MAC_PROP_ADV_10GFDX_CAP: 150 ret = ENOTSUP; 151 break; 152 153 /* 154 * These EN properties are used to control the advertised speeds of the 155 * device. For this example, we assume that this device does not have a 156 * copper phy, at which point auto-negotiation and the speeds in 157 * question cannot be changed. These are called out separately as they 158 * should be controllable for copper based devices or it may need to be 159 * conditional depending on the type of phy present. 160 */ 161 case MAC_PROP_EN_100FDX_CAP: 162 case MAC_PROP_EN_1000FDX_CAP: 163 case MAC_PROP_EN_10GFDX_CAP: 164 case MAC_PROP_AUTONEG: 165 ret = ENOTSUP; 166 break; 167 168 case MAC_PROP_MTU: 169 if (pr_valsize < sizeof (uint32_t)) { 170 ret = EOVERFLOW; 171 break; 172 } 173 bcopy(&new_mtu, pr_val, sizeof (uint32_t)); 174 175 if (new_mtu < ep->ep_min_mtu || 176 new_mtu > ep->ep_max_mtu) { 177 ret = EINVAL; 178 break; 179 } 180 181 /* 182 * We first ask MAC to update the MTU before we do anything. 183 * This may fail. It returns zero on success. The 184 * example_update_mtu function does device specific updates to 185 * ensure that the MTU on the device is updated and any internal 186 * data structures are up to date. 187 */ 188 ret = mac_maxdsu_update(&ep->ep_mac_hdl, new_mtu); 189 if (ret == 0) { 190 example_update_mtu(ep, new_mtu); 191 } 192 break; 193 194 /* 195 * Devices may have their own private properties. If they do, they 196 * should not return ENOTSUP, but instead see if it's a property they 197 * recognize and handle it similar to those above. If it doesn't 198 * recognize the name, then it should return ENOTSUP. 199 */ 200 case MAC_PROP_PRIVATE: 201 ret = ENOTSUP; 202 break; 203 204 default: 205 ret = ENOTSUP; 206 break; 207 } 208 mutex_exit(&ep->ep_lock); 209 210 return (ret); 211} 212.Ed 213.Sh ERRORS 214The device driver may return one of the following errors. While this list 215is not intended to be exhaustive, it is recommended to use one of these 216if possible. 217.Bl -tag -width Er 218.It Er EINVAL 219The contents of 220.Fa pr_val 221are outside the valid range for the property. 222.It Er ENOTSUP 223This error should be used whenever an unknown or unsupported property is 224encountered. It should also be used when the property is not writable. 225.It Er EOVERFLOW 226This error should be used when 227.Fa pr_valsize 228is smaller than the required size for a given value. 229.It Er EBUSY 230This error should be used when a property can't be set because the 231device has started. Note that device driver writers are encouraged to design 232device drivers such that this error is not possible. 233.It Er ECANCELLED 234The device is in a state that does not allow it to handle data; for 235example, it's suspended. 236.El 237.Sh SEE ALSO 238.Xr mac 9E , 239.Xr mac_register 9F , 240.Xr strcmp 9F , 241.Xr mac_register 9S 242