12309 errors in section 9e of the manual
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 November 15, 2016 15 .Dt MC_GETPROP 9E 16 .Os 17 .Sh NAME 18 .Nm mc_getprop 19 .Nd get device properties 20 .Sh SYNOPSIS 21 .In sys/mac_provider.h 22 .Ft int 23 .Fo prefix_m_getprop 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 "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 can store the property. 53 .El 54 .Sh DESCRIPTION 55 The 56 .Fn mc_getprop 57 entry point is used to obtain the value of a given device's property and 58 place it into 59 .Fa pr_val . 60 .Pp 61 When the 62 .Fn mc_getprop 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 copy the property's value into 80 .Fa pr_val . 81 When an unknown or unsupported 82 property is encountered, generally the 83 .Sy default 84 case of the switch statement, the device driver should return an error. 85 .Pp 86 The special property 87 .Sy MAC_PROP_PRIVATE 88 indicates that this is a device driver specific private property. 89 The device driver must then look at the value of the 90 .Fa pr_name 91 argument and use 92 .Xr strcmp 9F 93 on it, comparing it to each of its private (bounded-size) properties to 94 identify which one it is. 95 .Pp 96 At this time, private properties are limited to being string based properties. 97 If other types of property values are used, they will not be rendered 98 correctly by 99 .Xr dladm 1M . 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 reading the properties. 107 .Sh CONTEXT 108 The 109 .Fn mc_getprop 110 function is generally called from 111 .Sy kernel 112 context. 113 .Sh RETURN VALUES 114 Upon successful completion, the device driver should have copied the 115 value of the property into 116 .Fa pr_val 117 and return 118 .Sy 0 . 119 Otherwise, a positive error should be returned to indicate failure. 120 .Sh EXAMPLES 121 The following example shows how a device driver might structure its 122 .Fn mc_getprop 123 entry point. 124 .Bd -literal 125 #include <sys/mac_provider.h> 126 127 /* 128 * Note, this example merely shows the structure of this function. 129 * Different devices will manage their state in different ways. Like other 130 * examples, this assumes that the device has state in a structure called 131 * example_t and that there is a lock which keeps track of that state. 132 */ 133 static char *example_priv_props[] = { 134 "_rx_intr_throttle", 135 "_tx_intr_throttle", 136 NULL 137 }; 138 139 static int 140 example_m_getprop_private(example_t *ep, const char *pr_name, uint_t pr_valsize, 141 void *pr_val) 142 { 143 uint32_t val; 144 145 ASSERT(MUTEX_HELD(&ep->ep_lock)); 146 if (strcmp(pr_name, example_priv_props[0] == 0) { 147 val = ep->ep_rx_itr; 148 } else if (strcmp(pr_name, exampe_priv_props[1] == 0) { 149 val = ep->ep_tx_itr; 150 } else { 151 return (ENOTSUP); 152 } 153 154 /* 155 * Due to issues in the GLDv3, these must be returned as string 156 * properties. 157 */ 158 if (snprintf(pr_val, pr_valsize, "%d", val) >= pr_valsize) 159 return (EOVERFLOW); 160 161 return (0); 162 } 163 164 static int 165 example_m_getprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, 166 uint_t pr_valsize, void *pr_val) 167 { 168 int ret = 0; 169 uint64_t speed; 170 example_t *ep = arg; 171 172 mutex_enter(&ep->ep_lock); 173 174 /* 175 * This only handles a subset of the properties that exist on the 176 * system. A proper driver will need to handle more. See mac(9E) for a 177 * full property list. 178 */ 179 switch (pr_num) { 180 case MAC_PROP_DUPLEX: 181 if (pr_valsize < sizeof (link_duplex_t)) { 182 ret = EOVERFLOW; 183 break; 184 } 185 bcopy(ep->ep_link_duplex, pr_val, sizeof (link_duplex_t)); 186 case MAC_PROP_SPEED: 187 if (pr_valsize < sizeof (uint64_t)) { 188 ret = EOVERFLOW; 189 break; 190 } 191 /* 192 * The link speed is stored in Mbits/s in this driver and is 193 * expected in bits/s. 194 */ 195 speed = ep->ep_link_speed * 1000000ULL; 196 bcopy(&speed, pr_val, sizeof (speed)); 197 break; 198 case MAC_PROP_MTU: 199 if (pr_valsize < sizeof (uint32_t)) { 200 ret = EOVERFLOW; 201 break; 202 } 203 bcopy(&ep->ep_mtu, pr_val, sizeof (speed)); 204 break; 205 case MAC_PROP_PRIVATE: 206 ret = example_m_getprop_private(ep, pr_name, pr_valsize, 207 pr_val); 208 break; 209 default: 210 ret = ENOTSUP; 211 break; 212 } 213 214 mutex_exit(&ep->ep_lock); 215 216 return (ret); 217 } 218 .Ed 219 .Sh ERRORS 220 The device driver may return one of the following errors. 221 While this list is not intended to be exhaustive, it is recommended to use one 222 of these if possible. 223 .Bl -tag -width Er 224 .It Er ENOTSUP 225 This error should be used whenever an unknown or unsupported property is 226 encountered. 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 .El 232 .Sh SEE ALSO 233 .Xr mac 9E , 234 .Xr mac_register 9F , 235 .Xr strcmp 9F , 236 .Xr mac_register 9S --- EOF ---