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