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