1*52d2369aSRobert Mustacchi.\" 2*52d2369aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*52d2369aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*52d2369aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*52d2369aSRobert Mustacchi.\" 1.0 of the CDDL. 6*52d2369aSRobert Mustacchi.\" 7*52d2369aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*52d2369aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*52d2369aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*52d2369aSRobert Mustacchi.\" 11*52d2369aSRobert Mustacchi.\" 12*52d2369aSRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 13*52d2369aSRobert Mustacchi.\" 14*52d2369aSRobert Mustacchi.Dd June 02, 2016 15*52d2369aSRobert Mustacchi.Dt MC_GETPROP 9E 16*52d2369aSRobert Mustacchi.Os 17*52d2369aSRobert Mustacchi.Sh NAME 18*52d2369aSRobert Mustacchi.Nm mc_getprop 19*52d2369aSRobert Mustacchi.Nd get device properties 20*52d2369aSRobert Mustacchi.Sh SYNOPSIS 21*52d2369aSRobert Mustacchi.In sys/mac_provider.h 22*52d2369aSRobert Mustacchi.Ft int 23*52d2369aSRobert Mustacchi.Fo prefix_m_getprop 24*52d2369aSRobert Mustacchi.Fa "void *driver" 25*52d2369aSRobert Mustacchi.Fa "const char *pr_name" 26*52d2369aSRobert Mustacchi.Fa "mac_prop_id_t pr_num" 27*52d2369aSRobert Mustacchi.Fa "uint_t pr_valsize" 28*52d2369aSRobert Mustacchi.Fa "void *pr_val" 29*52d2369aSRobert Mustacchi.Fc 30*52d2369aSRobert Mustacchi.Sh INTERFACE LEVEL 31*52d2369aSRobert Mustacchiillumos DDI specific 32*52d2369aSRobert Mustacchi.Sh PARAMETERS 33*52d2369aSRobert Mustacchi.Bl -tag -width Fa 34*52d2369aSRobert Mustacchi.It Fa driver 35*52d2369aSRobert MustacchiA pointer to the driver's private data that was passed in via the 36*52d2369aSRobert Mustacchi.Sy m_pdata 37*52d2369aSRobert Mustacchimember of the 38*52d2369aSRobert Mustacchi.Xr mac_register 9S 39*52d2369aSRobert Mustacchistructure to the 40*52d2369aSRobert Mustacchi.Xr mac_register 9F 41*52d2369aSRobert Mustacchifunction. 42*52d2369aSRobert Mustacchi.It Fa pr_name 43*52d2369aSRobert MustacchiA null-terminated string that contains the name of the property. 44*52d2369aSRobert Mustacchi.It Fa pr_num 45*52d2369aSRobert MustacchiA constant that is used to identify the property. 46*52d2369aSRobert Mustacchi.It Fa pr_valsize 47*52d2369aSRobert MustacchiA value that indicates the size in bytes of 48*52d2369aSRobert Mustacchi.Fa pr_val . 49*52d2369aSRobert Mustacchi.It Fa pr_val 50*52d2369aSRobert MustacchiA pointer to a 51*52d2369aSRobert Mustacchi.Fa pr_valsize 52*52d2369aSRobert Mustacchibyte buffer that can store the property. 53*52d2369aSRobert Mustacchi.El 54*52d2369aSRobert Mustacchi.Sh DESCRIPTION 55*52d2369aSRobert MustacchiThe 56*52d2369aSRobert Mustacchi.Fn mc_getprop 57*52d2369aSRobert Mustacchientry point is used to obtain the value of a given device's property and 58*52d2369aSRobert Mustacchiplace it into 59*52d2369aSRobert Mustacchi.Fa pr_val . 60*52d2369aSRobert Mustacchi.Pp 61*52d2369aSRobert MustacchiWhen the 62*52d2369aSRobert Mustacchi.Fn mc_getprop 63*52d2369aSRobert Mustacchientry point is called, the driver needs to first identify the property. 64*52d2369aSRobert MustacchiThe set of possible properties and their meaning is listed in the 65*52d2369aSRobert Mustacchi.Sx PROPERTIES 66*52d2369aSRobert Mustacchisection of 67*52d2369aSRobert Mustacchi.Xr mac 9E . 68*52d2369aSRobert MustacchiIt should identify the property based on the value of 69*52d2369aSRobert Mustacchi.Fa pr_num . 70*52d2369aSRobert MustacchiMost drivers will use a 71*52d2369aSRobert Mustacchi.Sy switch 72*52d2369aSRobert Mustacchistatement and for any property that it supports it should then check if 73*52d2369aSRobert Mustacchithe value in 74*52d2369aSRobert Mustacchi.Fa pr_valsize 75*52d2369aSRobert Mustacchiis sufficient for the property, comparing it to the minimum size 76*52d2369aSRobert Mustacchilisted for the property in 77*52d2369aSRobert Mustacchi.Xr mac 9E . 78*52d2369aSRobert MustacchiIf it is not, then it should return an error. Otherwise, it should copy 79*52d2369aSRobert Mustacchithe property's value into 80*52d2369aSRobert Mustacchi.Fa pr_val . 81*52d2369aSRobert MustacchiWhen an unknown or unsupported 82*52d2369aSRobert Mustacchiproperty is encountered, generally the 83*52d2369aSRobert Mustacchi.Sy default 84*52d2369aSRobert Mustacchicase of the switch statement, the device driver should return an error. 85*52d2369aSRobert Mustacchi.Pp 86*52d2369aSRobert MustacchiThe special property 87*52d2369aSRobert Mustacchi.Sy MAC_PROP_PRIVATE 88*52d2369aSRobert Mustacchiindicates that this is a device driver specific private property. The 89*52d2369aSRobert Mustacchidevice driver must then look at the value of the 90*52d2369aSRobert Mustacchi.Fa pr_name 91*52d2369aSRobert Mustacchiargument and use 92*52d2369aSRobert Mustacchi.Xr strcmp 9F 93*52d2369aSRobert Mustacchion it, comparing it to each of its private (bounded-size) properties to 94*52d2369aSRobert Mustacchiidentify which one it is. 95*52d2369aSRobert Mustacchi.Pp 96*52d2369aSRobert MustacchiThe device 97*52d2369aSRobert Mustacchidriver can access its device soft state by casting the 98*52d2369aSRobert Mustacchi.Fa device 99*52d2369aSRobert Mustacchipointer to the appropriate structure. As this may be called while other 100*52d2369aSRobert Mustacchioperations are ongoing, the device driver should employ the appropriate 101*52d2369aSRobert Mustacchilocking while reading the properties. 102*52d2369aSRobert Mustacchi.Sh CONTEXT 103*52d2369aSRobert MustacchiThe 104*52d2369aSRobert Mustacchi.Fn mc_getprop 105*52d2369aSRobert Mustacchifunction is generally called from 106*52d2369aSRobert Mustacchi.Sy kernel 107*52d2369aSRobert Mustacchicontext. 108*52d2369aSRobert Mustacchi.Sh RETURN VALUES 109*52d2369aSRobert MustacchiUpon successful completion, the device driver should have copied the 110*52d2369aSRobert Mustacchivalue of the property into 111*52d2369aSRobert Mustacchi.Fa pr_val 112*52d2369aSRobert Mustacchiand return 113*52d2369aSRobert Mustacchi.Sy 0 . 114*52d2369aSRobert MustacchiOtherwise, a positive error should be returned to indicate failure. 115*52d2369aSRobert Mustacchi.Sh EXAMPLES 116*52d2369aSRobert MustacchiThe following example shows how a device driver might structure its 117*52d2369aSRobert Mustacchi.Fn mc_getprop 118*52d2369aSRobert Mustacchientry point. 119*52d2369aSRobert Mustacchi.Bd -literal 120*52d2369aSRobert Mustacchi#include <sys/mac_provider.h> 121*52d2369aSRobert Mustacchi 122*52d2369aSRobert Mustacchi/* 123*52d2369aSRobert Mustacchi * Note, this example merely shows the structure of this function. 124*52d2369aSRobert Mustacchi * Different devices will manage their state in different ways. Like other 125*52d2369aSRobert Mustacchi * examples, this assumes that the device has state in a structure called 126*52d2369aSRobert Mustacchi * example_t and that there is a lock which keeps track of that state. 127*52d2369aSRobert Mustacchi */ 128*52d2369aSRobert Mustacchistatic char *example_priv_props[] = { 129*52d2369aSRobert Mustacchi "_rx_intr_throttle", 130*52d2369aSRobert Mustacchi "_tx_intr_throttle", 131*52d2369aSRobert Mustacchi NULL 132*52d2369aSRobert Mustacchi}; 133*52d2369aSRobert Mustacchi 134*52d2369aSRobert Mustacchistatic int 135*52d2369aSRobert Mustacchiexample_m_getprop_private(example_t *ep, const char *pr_name, uint_t pr_valsize, 136*52d2369aSRobert Mustacchi void *pr_val) 137*52d2369aSRobert Mustacchi{ 138*52d2369aSRobert Mustacchi uint32_t val; 139*52d2369aSRobert Mustacchi 140*52d2369aSRobert Mustacchi ASSERT(MUTEX_HELD(&ep->ep_lock)); 141*52d2369aSRobert Mustacchi if (strcmp(pr_name, example_priv_props[0] == 0) { 142*52d2369aSRobert Mustacchi val = ep->ep_rx_itr; 143*52d2369aSRobert Mustacchi } else if (strcmp(pr_name, exampe_priv_props[1] == 0) { 144*52d2369aSRobert Mustacchi val = ep->ep_tx_itr; 145*52d2369aSRobert Mustacchi } else { 146*52d2369aSRobert Mustacchi return (ENOTSUP); 147*52d2369aSRobert Mustacchi } 148*52d2369aSRobert Mustacchi 149*52d2369aSRobert Mustacchi /* 150*52d2369aSRobert Mustacchi * Due to issues in the GLDv3, these must be returned as string 151*52d2369aSRobert Mustacchi * properties. 152*52d2369aSRobert Mustacchi */ 153*52d2369aSRobert Mustacchi if (snprintf(pr_val, pr_valsize, "%d", val) >= pr_valsize) 154*52d2369aSRobert Mustacchi return (EOVERFLOW); 155*52d2369aSRobert Mustacchi 156*52d2369aSRobert Mustacchi return (0); 157*52d2369aSRobert Mustacchi} 158*52d2369aSRobert Mustacchi 159*52d2369aSRobert Mustacchistatic int 160*52d2369aSRobert Mustacchiexample_m_getprop(void *arg, const char *pr_name, mac_prop_id_t pr_num, 161*52d2369aSRobert Mustacchi uint_t pr_valsize, void *pr_val) 162*52d2369aSRobert Mustacchi{ 163*52d2369aSRobert Mustacchi int ret = 0; 164*52d2369aSRobert Mustacchi uint64_t speed; 165*52d2369aSRobert Mustacchi example_t *ep = arg; 166*52d2369aSRobert Mustacchi 167*52d2369aSRobert Mustacchi mutex_enter(&ep->ep_lock); 168*52d2369aSRobert Mustacchi 169*52d2369aSRobert Mustacchi /* 170*52d2369aSRobert Mustacchi * This only handles a subset of the properties that exist on the 171*52d2369aSRobert Mustacchi * system. A proper driver will need to handle more. See mac(9E) for a 172*52d2369aSRobert Mustacchi * full property list. 173*52d2369aSRobert Mustacchi */ 174*52d2369aSRobert Mustacchi switch (pr_num) { 175*52d2369aSRobert Mustacchi case MAC_PROP_DUPLEX: 176*52d2369aSRobert Mustacchi if (pr_valsize < sizeof (link_duplex_t)) { 177*52d2369aSRobert Mustacchi ret = EOVERFLOW; 178*52d2369aSRobert Mustacchi break; 179*52d2369aSRobert Mustacchi } 180*52d2369aSRobert Mustacchi bcopy(ep->ep_link_duplex, pr_val, sizeof (link_duplex_t)); 181*52d2369aSRobert Mustacchi case MAC_PROP_SPEED: 182*52d2369aSRobert Mustacchi if (pr_valsize < sizeof (uint64_t)) { 183*52d2369aSRobert Mustacchi ret = EOVERFLOW; 184*52d2369aSRobert Mustacchi break; 185*52d2369aSRobert Mustacchi } 186*52d2369aSRobert Mustacchi /* 187*52d2369aSRobert Mustacchi * The link speed is stored in Mbits/s in this driver and is 188*52d2369aSRobert Mustacchi * expected in bits/s. 189*52d2369aSRobert Mustacchi */ 190*52d2369aSRobert Mustacchi speed = ep->ep_link_speed * 1000000ULL; 191*52d2369aSRobert Mustacchi bcopy(&speed, pr_val, sizeof (speed)); 192*52d2369aSRobert Mustacchi break; 193*52d2369aSRobert Mustacchi case MAC_PROP_MTU: 194*52d2369aSRobert Mustacchi if (pr_valsize < sizeof (uint32_t)) { 195*52d2369aSRobert Mustacchi ret = EOVERFLOW; 196*52d2369aSRobert Mustacchi break; 197*52d2369aSRobert Mustacchi } 198*52d2369aSRobert Mustacchi bcopy(&ep->ep_mtu, pr_val, sizeof (speed)); 199*52d2369aSRobert Mustacchi break; 200*52d2369aSRobert Mustacchi case MAC_PROP_PRIVATE: 201*52d2369aSRobert Mustacchi ret = example_m_getprop_private(ep, pr_name, pr_valsize, 202*52d2369aSRobert Mustacchi pr_val); 203*52d2369aSRobert Mustacchi break; 204*52d2369aSRobert Mustacchi default: 205*52d2369aSRobert Mustacchi ret = ENOTSUP; 206*52d2369aSRobert Mustacchi break; 207*52d2369aSRobert Mustacchi } 208*52d2369aSRobert Mustacchi 209*52d2369aSRobert Mustacchi mutex_exit(&ep->ep_lock); 210*52d2369aSRobert Mustacchi 211*52d2369aSRobert Mustacchi return (ret); 212*52d2369aSRobert Mustacchi} 213*52d2369aSRobert Mustacchi.Ed 214*52d2369aSRobert Mustacchi.Sh ERRORS 215*52d2369aSRobert MustacchiThe device driver may return one of the following errors. While this list 216*52d2369aSRobert Mustacchiis not intended to be exhaustive, it is recommended to use one of these 217*52d2369aSRobert Mustacchiif possible. 218*52d2369aSRobert Mustacchi.Bl -tag -width Er 219*52d2369aSRobert Mustacchi.It Er ENOTSUP 220*52d2369aSRobert MustacchiThis error should be used whenever an unknown or unsupported property is 221*52d2369aSRobert Mustacchiencountered. 222*52d2369aSRobert Mustacchi.It Er EOVERFLOW 223*52d2369aSRobert MustacchiThis error should be used when 224*52d2369aSRobert Mustacchi.Fa pr_valsize 225*52d2369aSRobert Mustacchiis smaller than the required size for a given value. 226*52d2369aSRobert Mustacchi.El 227*52d2369aSRobert Mustacchi.Sh SEE ALSO 228*52d2369aSRobert Mustacchi.Xr mac 9E , 229*52d2369aSRobert Mustacchi.Xr mac_register 9F , 230*52d2369aSRobert Mustacchi.Xr strcmp 9F , 231*52d2369aSRobert Mustacchi.Xr mac_register 9S 232