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 May 31, 2016 15.Dt MC_PROPINFO 9E 16.Os 17.Sh NAME 18.Nm mc_propinfo 19.Nd get information about a property 20.Sh SYNOPSIS 21.In sys/mac_provider.h 22.Ft void 23.Fo prefix_m_propinfo 24.Fa "void *driver" 25.Fa "const char *pr_name" 26.Fa "mac_prop_id_t pr_num" 27.Fa "mac_prop_info_handle_t hdl" 28.Fc 29.Sh INTERFACE LEVEL 30illumos DDI specific 31.Sh PARAMETERS 32.Bl -tag -width Ds 33.It Fa driver 34A pointer to the driver's private data that was passed in via the 35.Sy m_pdata 36member of the 37.Xr mac_register 9S 38structure to the 39.Xr mac_register 9F 40function. 41.It Fa pr_name 42A null-terminated string that contains the name of the property. 43.It Ft pr_num 44The value indicates the property that the device is working with. 45.It Fa hdl 46A handle to use with the 47.Xr mac_prop_info 9F 48family of routines to indicate the property's metadata. 49.El 50.Sh DESCRIPTION 51The 52.Fn mc_propinfo 53entry point is an optional entry point for networking device drivers 54that is used to obtain metadata about a property, including its 55permissions, default value, and information about valid possible values. 56If the device driver does not implement either of the 57.Xr mc_getprop 9E 58or 59.Xr mc_setprop 9E 60entry points then it does not need to implement the 61.Fn mc_propinfo 62entry point. 63However, it is highly recommended that these interfaces be implemented in order 64to give users and administrators of the system access to the properties of the 65device. 66.Pp 67When the 68.Fn mc_propinfo 69entry point is called, the driver needs to first identify the property. 70The set of possible properties and their meaning is listed in the 71.Sy PROPERTIES 72section of 73.Xr mac 9E . 74It should identify the property based on the value of 75.Fa pr_num . 76Most drivers will use a 77.Sy switch 78statement and for any property that it supports it should call the 79appropriate 80.Xr mac_prop_info 9F 81functions to set values and then return. 82When an unknown or unsupported property is encountered, generally the 83.Sy default 84case of the switch statement, the device driver should simply do nothing 85and return. 86.Pp 87The special property 88.Sy MAC_PROP_PRIVATE 89indicates that this is a device driver specific private property. 90The device driver must then look at the value of the 91.Fa pr_name 92argument and use 93.Xr strcmp 9F 94on it, comparing it to each of its private properties to identify which 95one it is. 96.Pp 97For each property the driver has three different sets of information 98that it can fill in. 99The driver should try to fill in all of these that make sense, if possible. 100.Bl -enum 101.It 102First, the driver should fill in the permissions of the property with 103the 104.Xr mac_prop_info_set_perm 9F 105function. 106These permissions indicate what the device driver supports for a given property. 107For each non-private property, see the property list in 108.Xr mac 9E 109to see what the maximum property permissions are. 110As discussed in 111.Xr mac 9E , 112a device driver may have more limited permissions than the default. 113For example, on some SFP-based devices, it may not be possible to change any 114of the auto-negotiation properties. 115.It 116The driver should then fill in any default value that it has for a 117property. 118This is the value that the device driver sets by default if no other tuning has 119been performed. 120There are different functions depending on the type of the default value to 121call. 122They are all listed in 123.Xr mac_prop_info 9F . 124.It 125Finally, a driver may optionally set one or more value ranges. 126These are used for integer properties such as 127.Sy MAC_PROP_MTU . 128The driver may call 129.Xr mac_prop_info_set_range_uint32 9F 130to set a series of one or more inclusive ranges that describe valid 131values for the property. 132For example, a device that supports jumbo frames up to 9600 bytes would call 133.Xr mac_prop_info_set_range_uint32 9F 134to convey that it supports MTUs in the range of 1500-9600 bytes. 135.El 136.Pp 137If the device driver needs to access its private data, it will be 138available in the 139.Fa driver 140argument which it should cast to the appropriate structure. 141From there, the device driver may need to lock the structure to ensure that 142access to it is properly serialized. 143.Sh RETURN VALUES 144The 145.Fn mc_propinfo 146entry point does not have a return value. 147Drivers should simply ignore and immediately return when encountering 148unsupported and unknown properties. 149.Sh EXAMPLES 150The following example shows how a device driver might structure its 151.Fn mc_propinfo 152entry point. 153.Bd -literal 154#include <sys/mac_provider.h> 155 156/* 157 * Note, this example merely shows the structure of this function. 158 * Different devices will manage their state in different ways. Like other 159 * examples, this assumes that the device has state in a structure called 160 * example_t and that there is a lock which keeps track of that state. 161 */ 162 163static void 164example_m_propinfo(void *arg, const char *pr_name, mac_prop_id_t pr_num, 165 mac_prop_info_handle_t prh) 166{ 167 uint8_t value; 168 uint_t perm; 169 170 example_t *ep = arg; 171 172 mutex_enter(&ep->ep_lock); 173 174 switch (pr_num) { 175 /* 176 * We try to fill in as much information for each property as makes 177 * sense. In some cases, you may only be able to set the permissions. 178 */ 179 case MAC_PROP_DUPLEX: 180 case MAC_PROP_SPEED: 181 mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); 182 break; 183 184 /* 185 * The MTU is a good example of a property that has a property range. 186 * The range represents the valid values the MTU can take. 187 */ 188 case MAC_PROP_MTU: 189 mac_prop_info_set_perm(prh, MAC_PROP_PERM_RW); 190 mac_prop_info_set_range(prh, ep->ep_min_mtu, ep->ep_max_mtu); 191 break; 192 193 /* 194 * The ADV properties represent things that the device supports and 195 * can't be changed by the user. These are good examples of properties 196 * that have a default value and are read-only. 197 */ 198 case MAC_PROP_ADV_100FDX_CAP: 199 mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); 200 value = (ep->ep_link_sup_speeds & EXAMPLE_100FDX) ? 1 : 0; 201 mac_prop_info_set_default_uint8(prh, value); 202 break; 203 case MAC_PROP_ADV_1000FDX_CAP: 204 mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); 205 value = (ep->ep_link_sup_speeds & EXAMPLE_1000FDX) ? 1 : 0; 206 mac_prop_info_set_default_uint8(prh, value); 207 break; 208 case MAC_PROP_ADV_10GFDX_CAP: 209 mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ); 210 value = (ep->ep_link_sup_speeds & EXAMPLE_10GDX) ? 1 : 0; 211 mac_prop_info_set_default_uint8(prh, value); 212 break; 213 214 /* 215 * The EN properties represent the speeds advertised by the driver. On 216 * baseT (copper) PHYs, we allow them to be set, otherwise we don't. 217 * This driver always advertises it if supported, hence why all of these 218 * default to advertised if the link supports its. 219 */ 220 case MAC_PROP_EN_100FDX_CAP: 221 perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ? 222 MAC_PROP_PERM_RW : MAC_PROP_PERM_READ; 223 mac_prop_info_set_perm(prh, perm); 224 value = (ep->ep_link_sup_speeds & EXAMPLE_100FDX) ? 1 : 0; 225 mac_prop_info_set_default_uint8(prh, value); 226 break; 227 case MAC_PROP_EN_1000FDX_CAP: 228 perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ? 229 MAC_PROP_PERM_RW : MAC_PROP_PERM_READ; 230 mac_prop_info_set_perm(prh, perm); 231 value = (ep->ep_link_sup_speeds & EXAMPLE_1000FDX) ? 1 : 0; 232 mac_prop_info_set_default_uint8(prh, value); 233 break; 234 case MAC_PROP_EN_10GFDX_CAP: 235 perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ? 236 MAC_PROP_PERM_RW : MAC_PROP_PERM_READ; 237 mac_prop_info_set_perm(prh, perm); 238 value = (ep->ep_link_sup_speeds & EXAMPLE_10GFDX) ? 1 : 0; 239 mac_prop_info_set_default_uint8(prh, value); 240 break; 241 242 /* 243 * If this device has private properties, then it should compare pr_name 244 * with the device's private properties and then fill in property 245 * information if it recognizes the name. 246 */ 247 case MAC_PROP_PRIVATE: 248 break; 249 250 /* 251 * For unknown properties, there's not much to do. Simply don't call any 252 * of the mac_prop_info(9F) related functions. 253 */ 254 default: 255 break; 256 } 257 mutex_exit(&ep->ep_lock); 258} 259.Ed 260.Sh SEE ALSO 261.Xr mac 9E , 262.Xr mc_getprop 9E , 263.Xr mac_prop_info 9F 264