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