usr/src/man/man9f/mac_prop_info.9f

   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 MAC_PROP_INFO 9F
  16 .Os
  17 .Sh NAME
  18 .Nm mac_prop_info ,
  19 .Nm mac_prop_info_set_default_link_flowctrl ,
  20 .Nm mac_prop_info_set_default_str ,
  21 .Nm mac_prop_info_set_default_uint8 ,
  22 .Nm mac_prop_info_set_default_uint32 ,
  23 .Nm mac_prop_info_set_default_uint64 ,
  24 .Nm mac_prop_info_set_perm ,
  25 .Nm mac_prop_info_set_range_uint32
  26 .Nd mac property information functions
  27 .Sh SYNOPSIS
  28 .In sys/mac_provider.h
  29 .Ft void
  30 .Fo mac_prop_info_set_default_link_flowctrl
  31 .Fa "mac_prop_info_handle_t hdl"
  32 .Fa "link_flowctrl_t fctl"
  33 .Fc
  34 .Ft void
  35 .Fo mac_prop_info_set_default_str
  36 .Fa "mac_prop_info_handle_t hdl"
  37 .Fa "const char *str"
  38 .Fc
  39 .Ft void
  40 .Fo mac_prop_info_set_default_uint8
  41 .Fa "mac_prop_info_handle_t hdl"
  42 .Fa "uint8_t u8"
  43 .Fc
  44 .Ft void
  45 .Fo mac_prop_info_set_default_uint16
  46 .Fa "mac_prop_info_handle_t hdl"
  47 .Fa "uint16_t u16"
  48 .Fc
  49 .Ft void
  50 .Fo mac_prop_info_set_default_uint32
  51 .Fa "mac_prop_info_handle_t hdl"
  52 .Fa "uint32_t u32"
  53 .Fc
  54 .Ft void
  55 .Fo mac_prop_info_set_perm
  56 .Fa "mac_prop_info_handle_t hdl"
  57 .Fa "uint8_t perm"
  58 .Fc
  59 .Ft void
  60 .Fo mac_prop_info_set_range_uint32
  61 .Fa "mac_prop_info_handle_t hdl"
  62 .Fa "uint32_t low"
  63 .Fa "uint32_t high"
  64 .Fc
  65 .Sh INTERFACE LEVEL
  66 illumos DDI specific
  67 .Sh PARAMETERS
  68 .Bl -tag -width Ds
  69 .It Ft hdl
  70 A pointer to the MAC property information handle.
  71 .It Ft fctl
  72 A valid link flow control entry.
  73 Valid values are documented in the
  74 .Sy MAC_PROP_FLOWCTRL
  75 property description in the
  76 .Sx PROPERTIES
  77 section of
  78 .Xr mac 9E .
  79 .It Ft str
  80 A null-terminated ASCII character string that describes that contains a
  81 value of a property.
  82 .It Ft u8
  83 An 8-bit unsigned value.
  84 .It Ft u16
  85 An 16-bit unsigned value.
  86 .It Ft u32
  87 An 32-bit unsigned value.
  88 .It Ft perm
  89 An 8-bit unsigned value which is the bitwise inclusive OR of the
  90 following values:
  91 .Bl -tag -width Ds
  92 .It Sy MAC_PROP_PERM_READ
  93 This flag indicates that a property is
  94 .Sy readable .
  95 .It Sy MAC_PROP_PERM_WRITE
  96 This flag indicates that a property is
  97 .Sy writable .
  98 .It Sy MAC_PROP_PERM_RW
  99 This flag indicates that a property is both
 100 .Sy readable
 101 and
 102 .Sy writable .
 103 This is equivalent to specifying both
 104 .Sy MAC_PROP_PERM_READ
 105 and
 106 .Sy MAC_PROP_PERM_WRITE .
 107 .El
 108 .It Ft low
 109 A 32-bit unsigned value that represents the lowest possible value of an
 110 integer property, generally inclusive.
 111 .It Ft high
 112 A 32-bit unsigned value that represents the highest possible value an
 113 integer property, generally inclusive.
 114 .El
 115 .Sh DESCRIPTION
 116 The
 117 .Sy mac_prop_info
 118 family of functions are used to fill in metadata about a given property
 119 as part of a driver's
 120 .Xr mc_propinfo 9E
 121 entry point.
 122 These functions can be used to fill in information about the default value that
 123 the device assigns to a property and the permissions that a privileged user has
 124 to update the property.
 125 .Pp
 126 The
 127 .Fn mac_prop_info_set_perm
 128 function is used to set the permissions of a property.
 129 These permissions indicate whether or not the property can be read or modified
 130 from the device driver's perspective.
 131 The permissions for a given property should generally not change for a given
 132 device and they do not need to take into account user privileges.
 133 For the most case, properties will only take one of two values:
 134 .Sy MAC_PROP_PERM_READ
 135 or
 136 .Sy MAC_PROP_PERM_RW .
 137 Usually it does not make sense for a property to just have
 138 .Sy MAC_PROP_PERM_WRITE .
 139 .Pp
 140 Subsequent calls to the
 141 .Fn mac_prop_info_set_perm
 142 function will override the values stored in previous calls.
 143 .Pp
 144 The
 145 .Fn mac_prop_info_set_range_uint32
 146 function is used to indicate a range of possible integer values that a
 147 device may take.
 148 This range is generally inclusive, meaning the property may be set to any value
 149 in the range of
 150 .Fa low
 151 to
 152 .Fa high .
 153 Each time the
 154 .Fn mac_prop_info_set_range_uint32
 155 function is called, a new property range is added, allowing for multiple
 156 disjoint ranges to be specified for a given property.
 157 .Pp
 158 The remaining functions,
 159 .Fn mac_prop_info_set_default_link_flowctrl ,
 160 .Fn mac_prop_info_set_default_str ,
 161 .Fn mac_prop_info_set_uint8 ,
 162 .Fn mac_prop_info_set_uint16 ,
 163 .Fn mac_prop_info_set_uint32 ,
 164 and
 165 .Fn mac_prop_info_set_range_uint32
 166 update the default value of a given property.
 167 The default value is the initial value that the property takes after the device
 168 driver has called
 169 .Xr mac_register 9F .
 170 If these functions are called multiple times, then the default value
 171 will be replaced with each call.
 172 .Pp
 173 The different functions each support a different type of default value
 174 and some are used for specific properties.
 175 The
 176 .Fn mac_prop_info_set_default_link_flowctrl
 177 function works with properties that describe flow control properties.
 178 The various values of a
 179 .Ft link_flowctrl_t
 180 are documented in
 181 .Xr mac 9E .
 182 .Pp
 183 The
 184 .Fn mac_prop_info_set_default_str
 185 function sets the default value for properties that use strings.
 186 The device driver should ensure that it uses alphanumeric ASCII characters
 187 only in the string to guarantee portability.
 188 .Pp
 189 The
 190 .Fn mac_prop_info_set_default_uint8 ,
 191 .Fn mac_prop_info_set_default_uint16 ,
 192 and
 193 .Fn mac_prop_info_set_default_uint32
 194 functions set the default value for values whose properties are 8-, 16-,
 195 and 32-bit unsigned values respectively.
 196 .Sh CONTEXT
 197 These functions are generally called on a handle passed into the
 198 .Xr mc_propinfo 9E
 199 entry point, though they function in both
 200 .Sy user
 201 and
 202 .Sy kernel
 203 context.
 204 .Sh RETURN VALUES
 205 All of the functions documented here do not return a value.
 206 It is not the driver's responsibility to ensure that there is sufficient space
 207 for permissions, ranges, or default values in the
 208 .Ft mac_prop_info_handle_t
 209 structures: the surrounding driver framework will transparently take
 210 care of that and ensure that errors are correctly propagated.
 211 .Sh SEE ALSO
 212 .Xr mac 9E ,
 213 .Xr mc_getprop 9E ,
 214 .Xr mc_propinfo 9E ,
 215 .Xr mc_setprop 9E