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