usr/src/man/man9e/mc_setprop.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 June 02, 2016
  15 .Dt MC_SETPROP 9E
  16 .Os
  17 .Sh NAME
  18 .Nm mc_setprop
  19 .Nd set device properties
  20 .Sh SYNOPSIS
  21 .In sys/mac_provider.h
  22 .Ft int
  23 .Fo prefix_m_setprop
  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 "const void *pr_val"
  29 .Fc
  30 .Sh INTERFACE LEVEL
  31 illumos DDI specific
  32 .Sh PARAMETERS
  33 .Bl -tag -width Fa
  34 .It Fa driver
  35 A pointer to the driver's private data that was passed in via the
  36 .Sy m_pdata
  37 member of the
  38 .Xr mac_register 9S
  39 structure to the
  40 .Xr mac_register 9F
  41 function.
  42 .It Fa pr_name
  43 A null-terminated string that contains the name of the property.
  44 .It Fa pr_num
  45 A constant that is used to identify the property.
  46 .It Fa pr_valsize
  47 A value that indicates the size in bytes of
  48 .Fa pr_val .
  49 .It Fa pr_val
  50 A pointer to a
  51 .Fa pr_valsize
  52 byte buffer that contains the new value of the property.
  53 .El
  54 .Sh DESCRIPTION
  55 The
  56 .Fn mc_setprop
  57 entry point is used to set the value of a given device's property from
  58 the copy stored in
  59 .Fa pr_val .
  60 .Pp
  61 When the
  62 .Fn mc_setprop
  63 entry point is called, the driver needs to first identify the property.
  64 The set of possible properties and their meaning is listed in the
  65 .Sx PROPERTIES
  66 section of
  67 .Xr mac 9E .
  68 It should identify the property based on the value of
  69 .Fa pr_num .
  70 Most drivers will use a
  71 .Sy switch
  72 statement and for any property that it supports it should then check if
  73 the value in
  74 .Fa pr_valsize
  75 is sufficient for the property, comparing it to the minimum size
  76 listed for the property in
  77 .Xr mac 9E .
  78 If it is not, then it should return an error.
  79 Otherwise, it should update the property based on the value in
  80 .Fa pr_val .
  81 When an unknown or unsupported property is encountered, generally the
  82 .Sy default
  83 case of the switch statement, the device driver should return an error.
  84 .Pp
  85 The special property
  86 .Sy MAC_PROP_PRIVATE
  87 indicates that this is a device driver specific private property.
  88 The device driver must then look at the value of the
  89 .Fa pr_name
  90 argument and use
  91 .Xr strcmp 9F
  92 on it, comparing it to each of its private properties to identify which
  93 one it is.
  94 .Pp
  95 Not all properties are supposed to be writable.
  96 Some devices may opt to not allow a property that is designated as read/write to
  97 be set.
  98 When such a property is encountered, the driver should return the appropriate
  99 error.
 100 .Pp
 101 The device
 102 driver can access its device soft state by casting the
 103 .Fa device
 104 pointer to the appropriate structure.
 105 As this may be called while other operations are ongoing, the device driver
 106 should employ the appropriate locking while writing the properties.
 107 .Sh RETURN VALUES
 108 Upon successful completion, the device driver should have copied the
 109 value of the property into
 110 .Fa pr_val
 111 and return
 112 .Sy 0 .
 113 Otherwise, a positive error should be returned to indicate failure.
 114 .Sh EXAMPLES
 115 The following examples shows how a device driver might structure its
 116 .Fn mc_setporp
 117 entry point.
 118 .Bd -literal
 119 #include <sys/mac_provider.h>
 120
 121 /*
 122  * Note, this example merely shows the structure of this function.
 123  * Different devices will manage their state in different ways. Like other
 124  * examples, this assumes that the device has state in a structure called
 125  * example_t and that there is a lock which keeps track of that state.
 126  *
 127  * For the purpose of this example, we assume that this device supports 100 Mb,
 128  * 1 GB, and 10 Gb full duplex speeds.
 129  */
 130
 131 static int
 132 exmple_m_setprop(void *arg, const char *pr_name, mac_prop_id_t pr_num,
 133     uint_t pr_valsize, const void *pr_val)
 134 {
 135         uint32_t new_mtu;
 136         int ret = 0;
 137         example_t *ep = arg;
 138
 139         mutex_enter(&ep->ep_lock);
 140         switch (pr_num) {
 141         /*
 142          * These represent properties that can never be changed, regardless of
 143          * the type of PHY on the device (copper, fiber, etc.)
 144          */
 145         case MAC_PROP_DUPLEX:
 146         case MAC_PROP_SPEED:
 147         case MAC_PROP_STATUS:
 148         case MAC_PROP_ADV_100FDX_CAP:
 149         case MAC_PROP_ADV_1000FDX_CAP:
 150         case MAC_PROP_ADV_10GFDX_CAP:
 151                 ret = ENOTSUP;
 152                 break;
 153
 154         /*
 155          * These EN properties are used to control the advertised speeds of the
 156          * device. For this example, we assume that this device does not have a
 157          * copper phy, at which point auto-negotiation and the speeds in
 158          * question cannot be changed. These are called out separately as they
 159          * should be controllable for copper based devices or it may need to be
 160          * conditional depending on the type of phy present.
 161          */
 162         case MAC_PROP_EN_100FDX_CAP:
 163         case MAC_PROP_EN_1000FDX_CAP:
 164         case MAC_PROP_EN_10GFDX_CAP:
 165         case MAC_PROP_AUTONEG:
 166                 ret = ENOTSUP;
 167                 break;
 168
 169         case MAC_PROP_MTU:
 170                 if (pr_valsize < sizeof (uint32_t)) {
 171                         ret = EOVERFLOW;
 172                         break;
 173                 }
 174                 bcopy(&new_mtu, pr_val, sizeof (uint32_t));
 175
 176                 if (new_mtu < ep->ep_min_mtu ||
 177                     new_mtu > ep->ep_max_mtu) {
 178                         ret = EINVAL;
 179                         break;
 180                 }
 181
 182                 /*
 183                  * We first ask MAC to update the MTU before we do anything.
 184                  * This may fail. It returns zero on success. The
 185                  * example_update_mtu function does device specific updates to
 186                  * ensure that the MTU on the device is updated and any internal
 187                  * data structures are up to date.
 188                  */
 189                 ret = mac_maxdsu_update(&ep->ep_mac_hdl, new_mtu);
 190                 if (ret == 0) {
 191                         example_update_mtu(ep, new_mtu);
 192                 }
 193                 break;
 194
 195         /*
 196          * Devices may have their own private properties. If they do, they
 197          * should not return ENOTSUP, but instead see if it's a property they
 198          * recognize and handle it similar to those above. If it doesn't
 199          * recognize the name, then it should return ENOTSUP.
 200          */
 201         case MAC_PROP_PRIVATE:
 202                 ret = ENOTSUP;
 203                 break;
 204
 205         default:
 206                 ret = ENOTSUP;
 207                 break;
 208         }
 209         mutex_exit(&ep->ep_lock);
 210
 211         return (ret);
 212 }
 213 .Ed
 214 .Sh ERRORS
 215 The device driver may return one of the following errors.
 216 While this list is not intended to be exhaustive, it is recommended to use one
 217 of these if possible.
 218 .Bl -tag -width Er
 219 .It Er EINVAL
 220 The contents of
 221 .Fa pr_val
 222 are outside the valid range for the property.
 223 .It Er ENOTSUP
 224 This error should be used whenever an unknown or unsupported property is
 225 encountered.
 226 It should also be used when the property is not writable.
 227 .It Er EOVERFLOW
 228 This error should be used when
 229 .Fa pr_valsize
 230 is smaller than the required size for a given value.
 231 .It Er EBUSY
 232 This error should be used when a property can't be set because the
 233 device has started.
 234 Note that device driver writers are encouraged to design device drivers such
 235 that this error is not possible.
 236 .It Er ECANCELLED
 237 The device is in a state that does not allow it to handle data;
 238 for example, it's suspended.
 239 .El
 240 .Sh SEE ALSO
 241 .Xr mac 9E ,
 242 .Xr mac_register 9F ,
 243 .Xr strcmp 9F ,
 244 .Xr mac_register 9S