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