usr/src/man/man9e/mc_propinfo.9e

   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
  30 illumos DDI specific
  31 .Sh PARAMETERS
  32 .Bl -tag -width Ds
  33 .It Fa driver
  34 A pointer to the driver's private data that was passed in via the
  35 .Sy m_pdata
  36 member of the
  37 .Xr mac_register 9S
  38 structure to the
  39 .Xr mac_register 9F
  40 function.
  41 .It Fa pr_name
  42 A null-terminated string that contains the name of the property.
  43 .It Ft pr_num
  44 The value indicates the property that the device is working with.
  45 .It Fa hdl
  46 A handle to use with the
  47 .Xr mac_prop_info 9F
  48 family of routines to indicate the property's metadata.
  49 .El
  50 .Sh DESCRIPTION
  51 The
  52 .Fn mc_propinfo
  53 entry point is an optional entry point for networking device drivers
  54 that is used to obtain metadata about a property, including its
  55 permissions, default value, and information about valid possible values.
  56 If the device driver does not implement either of the
  57 .Xr mc_getprop 9E
  58 or
  59 .Xr mc_setprop 9E
  60 entry points then it does not need to implement the
  61 .Xr mc_propinfo 9E
  62 entry point.
  63 However, it is highly recommended that these interfaces be implemented in order
  64 to give users and administrators of the system access to the properties of the
  65 device.
  66 .Pp
  67 When the
  68 .Fn mc_propinfo
  69 entry point is called, the driver needs to first identify the property.
  70 The set of possible properties and their meaning is listed in the
  71 .Sx PROPERTIES
  72 section of
  73 .Xr mac 9E .
  74 It should identify the property based on the value of
  75 .Fa pr_num .
  76 Most drivers will use a
  77 .Sy switch
  78 statement and for any property that it supports it should call the
  79 appropriate
  80 .Xr mac_prop_info 9F
  81 functions to set values and then return.
  82 When an unknown or unsupported property is encountered, generally the
  83 .Sy default
  84 case of the switch statement, the device driver should simply do nothing
  85 and return.
  86 .Pp
  87 The special property
  88 .Sy MAC_PROP_PRIVATE
  89 indicates that this is a device driver specific private property.
  90 The device driver must then look at the value of the
  91 .Fa pr_name
  92 argument and use
  93 .Xr strcmp 9F
  94 on it, comparing it to each of its private properties to identify which
  95 one it is.
  96 .Pp
  97 For each property the driver has three different sets of information
  98 that it can fill in.
  99 The driver should try to fill in all of these that make sense, if possible.
 100 .Bl -enum
 101 .It
 102 First, the driver should fill in the permissions of the property with
 103 the
 104 .Xr mac_prop_info_set_perm 9F
 105 function.
 106 These permissions indicate what the device driver supports for a given property.
 107 For each non-private property, see the property list in
 108 .Xr mac 9E
 109 to see what the maximum property permissions are.
 110 As discussed in
 111 .Xr mac 9E ,
 112 a device driver may have more limited permissions than the default.
 113 For example, on some SFP-based devices, it may not be possible to change any
 114 of the auto-negotiation properties.
 115 .It
 116 The driver should then fill in any default value that it has for a
 117 property.
 118 This is the value that the device driver sets by default if no other tuning has
 119 been performed.
 120 There are different functions depending on the type of the default value to
 121 call.
 122 They are all listed in
 123 .Xr mac_prop_info 9F .
 124 .It
 125 Finally, a driver may optionally set one or more value ranges.
 126 These are used for integer properties such as
 127 .Sy MAC_PROP_MTU .
 128 The driver may call
 129 .Xr mac_prop_info_set_range_uint32 9F
 130 to set a series of one or more inclusive ranges that describe valid
 131 values for the property.
 132 For example, a device that supports jumbo frames up to 9600 bytes would call
 133 .Xr mac_prop_info_set_range_uint32 9F
 134 to convey that it supports MTUs in the range of 1500-9600 bytes.
 135 .El
 136 .Pp
 137 If the device driver needs to access its private data, it will be
 138 available in the
 139 .Fa driver
 140 argument which it should cast to the appropriate structure.
 141 From there, the device driver may need to lock the structure to ensure that
 142 access to it is properly serialized.
 143 .Sh RETURN VALUES
 144 The
 145 .Fn mc_propinfo
 146 entry point does not have a return value.
 147 Drivers should simply ignore and immediately return when encountering
 148 unsupported and unknown properties.
 149 .Sh EXAMPLES
 150 The following example shows how a device driver might structure its
 151 .Fn mc_propinfo
 152 entry 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
 163 static void
 164 example_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 mc_propinfo 9E ,
 264 .Xr mac_prop_info 9F