152d2369aSRobert Mustacchi.\" 252d2369aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 352d2369aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 452d2369aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 552d2369aSRobert Mustacchi.\" 1.0 of the CDDL. 652d2369aSRobert Mustacchi.\" 752d2369aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 852d2369aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 952d2369aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1052d2369aSRobert Mustacchi.\" 1152d2369aSRobert Mustacchi.\" 1252d2369aSRobert Mustacchi.\" Copyright 2016 Joyent, Inc. 1352d2369aSRobert Mustacchi.\" 1452d2369aSRobert Mustacchi.Dd May 31, 2016 1552d2369aSRobert Mustacchi.Dt MAC_PROP_INFO 9F 1652d2369aSRobert Mustacchi.Os 1752d2369aSRobert Mustacchi.Sh NAME 1852d2369aSRobert Mustacchi.Nm mac_prop_info , 1952d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_link_flowctrl , 2052d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_str , 2152d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_uint8 , 2252d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_uint32 , 2352d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_uint64 , 2452d2369aSRobert Mustacchi.Nm mac_prop_info_set_perm , 2552d2369aSRobert Mustacchi.Nm mac_prop_info_set_range_uint32 2652d2369aSRobert Mustacchi.Nd mac property information functions 2752d2369aSRobert Mustacchi.Sh SYNOPSIS 2852d2369aSRobert Mustacchi.In sys/mac_provider.h 2952d2369aSRobert Mustacchi.Ft void 3052d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_link_flowctrl 3152d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 3252d2369aSRobert Mustacchi.Fa "link_flowctrl_t fctl" 3352d2369aSRobert Mustacchi.Fc 3452d2369aSRobert Mustacchi.Ft void 3552d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_str 3652d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 3752d2369aSRobert Mustacchi.Fa "const char *str" 3852d2369aSRobert Mustacchi.Fc 3952d2369aSRobert Mustacchi.Ft void 4052d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_uint8 4152d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 4252d2369aSRobert Mustacchi.Fa "uint8_t u8" 4352d2369aSRobert Mustacchi.Fc 4452d2369aSRobert Mustacchi.Ft void 4552d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_uint16 4652d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 4752d2369aSRobert Mustacchi.Fa "uint16_t u16" 4852d2369aSRobert Mustacchi.Fc 4952d2369aSRobert Mustacchi.Ft void 5052d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_uint32 5152d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 5252d2369aSRobert Mustacchi.Fa "uint32_t u32" 5352d2369aSRobert Mustacchi.Fc 5452d2369aSRobert Mustacchi.Ft void 5552d2369aSRobert Mustacchi.Fo mac_prop_info_set_perm 5652d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 5752d2369aSRobert Mustacchi.Fa "uint8_t perm" 5852d2369aSRobert Mustacchi.Fc 5952d2369aSRobert Mustacchi.Ft void 6052d2369aSRobert Mustacchi.Fo mac_prop_info_set_range_uint32 6152d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 6252d2369aSRobert Mustacchi.Fa "uint32_t low" 6352d2369aSRobert Mustacchi.Fa "uint32_t high" 6452d2369aSRobert Mustacchi.Fc 6552d2369aSRobert Mustacchi.Sh INTERFACE LEVEL 6652d2369aSRobert Mustacchiillumos DDI specific 6752d2369aSRobert Mustacchi.Sh PARAMETERS 6852d2369aSRobert Mustacchi.Bl -tag -width Ds 6952d2369aSRobert Mustacchi.It Ft hdl 7052d2369aSRobert MustacchiA pointer to the MAC property information handle. 7152d2369aSRobert Mustacchi.It Ft fctl 7252d2369aSRobert MustacchiA valid link flow control entry. Valid values are documented in the 7352d2369aSRobert Mustacchi.Sy MAC_PROP_FLOWCTRL 7452d2369aSRobert Mustacchiproperty description in the 7552d2369aSRobert Mustacchi.Sx PROPERTIES 7652d2369aSRobert Mustacchisection of 7752d2369aSRobert Mustacchi.Xr mac 9E . 7852d2369aSRobert Mustacchi.It Ft str 7952d2369aSRobert MustacchiA null-terminated ASCII character string that describes that contains a 8052d2369aSRobert Mustacchivalue of a property. 8152d2369aSRobert Mustacchi.It Ft u8 8252d2369aSRobert MustacchiAn 8-bit unsigned value. 8352d2369aSRobert Mustacchi.It Ft u16 8452d2369aSRobert MustacchiAn 16-bit unsigned value. 8552d2369aSRobert Mustacchi.It Ft u32 8652d2369aSRobert MustacchiAn 32-bit unsigned value. 8752d2369aSRobert Mustacchi.It Ft perm 8852d2369aSRobert MustacchiAn 8-bit unsigned value which is the bitwise inclusive OR of the 8952d2369aSRobert Mustacchifollowing values: 9052d2369aSRobert Mustacchi.Bl -tag -width Ds 9152d2369aSRobert Mustacchi.It Sy MAC_PROP_PERM_READ 9252d2369aSRobert MustacchiThis flag indicates that a property is 9352d2369aSRobert Mustacchi.Sy readable . 9452d2369aSRobert Mustacchi.It Sy MAC_PROP_PERM_WRITE 9552d2369aSRobert MustacchiThis flag indicates that a property is 9652d2369aSRobert Mustacchi.Sy writable . 9752d2369aSRobert Mustacchi.It Sy MAC_PROP_PERM_RW 9852d2369aSRobert MustacchiThis flag indicates that a property is both 9952d2369aSRobert Mustacchi.Sy readable 10052d2369aSRobert Mustacchiand 101*bccbd30bSPeter Tribble.Sy writable . 10252d2369aSRobert MustacchiThis is equivalent to specifying both 10352d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_READ 10452d2369aSRobert Mustacchiand 10552d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_WRITE . 10652d2369aSRobert Mustacchi.El 10752d2369aSRobert Mustacchi.It Ft low 10852d2369aSRobert MustacchiA 32-bit unsigned value that represents the lowest possible value of an 10952d2369aSRobert Mustacchiinteger property, generally inclusive. 11052d2369aSRobert Mustacchi.It Ft high 11152d2369aSRobert MustacchiA 32-bit unsigned value that represents the highest possible value an 11252d2369aSRobert Mustacchiinteger property, generally inclusive. 11352d2369aSRobert Mustacchi.El 11452d2369aSRobert Mustacchi.Sh DESCRIPTION 11552d2369aSRobert MustacchiThe 11652d2369aSRobert Mustacchi.Sy mac_prop_info 11752d2369aSRobert Mustacchifamily of functions are used to fill in metadata about a given property 11852d2369aSRobert Mustacchias part of a driver's 11952d2369aSRobert Mustacchi.Xr mc_propinfo 9E 12052d2369aSRobert Mustacchientry point. These functions can be used to fill in information about 12152d2369aSRobert Mustacchithe default value that the device assigns to a property and the 12252d2369aSRobert Mustacchipermissions that a privileged user has to update the property. 12352d2369aSRobert Mustacchi.Pp 12452d2369aSRobert MustacchiThe 12552d2369aSRobert Mustacchi.Fn mac_prop_info_set_perm 12652d2369aSRobert Mustacchifunction is used to set the permissions of a property. These permissions 12752d2369aSRobert Mustacchiindicate whether or not the property can be read or modified from the 12852d2369aSRobert Mustacchidevice driver's perspective. The permissions for a given property should 12952d2369aSRobert Mustacchigenerally not change for a given device and they do not need to take 13052d2369aSRobert Mustacchiinto account user privileges. For the most case, properties will only 13152d2369aSRobert Mustacchitake one of two values: 13252d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_READ 13352d2369aSRobert Mustacchior 13452d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_RW . 13552d2369aSRobert MustacchiUsually it does not make sense for a property to just have 13652d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_WRITE . 13752d2369aSRobert Mustacchi.Pp 13852d2369aSRobert MustacchiSubsequent calls to the 13952d2369aSRobert Mustacchi.Fn mac_prop_info_set_perm 14052d2369aSRobert Mustacchifunction will override the values stored in previous calls. 14152d2369aSRobert Mustacchi.Pp 14252d2369aSRobert MustacchiThe 14352d2369aSRobert Mustacchi.Fn mac_prop_info_set_range_uint32 14452d2369aSRobert Mustacchifunction is used to indicate a range of possible integer values that a 14552d2369aSRobert Mustacchidevice may take. This range is generally inclusive, meaning the property 14652d2369aSRobert Mustacchimay be set to any value in the range of 14752d2369aSRobert Mustacchi.Fa low 14852d2369aSRobert Mustacchito 14952d2369aSRobert Mustacchi.Fa high . 15052d2369aSRobert MustacchiEach time the 15152d2369aSRobert Mustacchi.Fn mac_prop_info_set_range_uint32 15252d2369aSRobert Mustacchifunction is called, a new property range is added, allowing for multiple 15352d2369aSRobert Mustacchidisjoint ranges to be specified for a given property. 15452d2369aSRobert Mustacchi.Pp 15552d2369aSRobert MustacchiThe remaining functions, 15652d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_link_flowctrl , 15752d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_str , 15852d2369aSRobert Mustacchi.Fn mac_prop_info_set_uint8 , 15952d2369aSRobert Mustacchi.Fn mac_prop_info_set_uint16 , 16052d2369aSRobert Mustacchi.Fn mac_prop_info_set_uint32 , 16152d2369aSRobert Mustacchiand 16252d2369aSRobert Mustacchi.Fn mac_prop_info_set_range_uint32 16352d2369aSRobert Mustacchiupdate the default value of a given property. The default value is the 16452d2369aSRobert Mustacchiinitial value that the property takes after the device driver has called 16552d2369aSRobert Mustacchi.Xr mac_register 9F . 16652d2369aSRobert MustacchiIf these functions are called multiple times, then the default value 16752d2369aSRobert Mustacchiwill be replaced with each call. 16852d2369aSRobert Mustacchi.Pp 16952d2369aSRobert MustacchiThe different functions each support a different type of default value 17052d2369aSRobert Mustacchiand some are used for specific properties. The 17152d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_link_flowctrl 17252d2369aSRobert Mustacchifunction works with properties that describe flow control properties. 17352d2369aSRobert MustacchiThe various values of a 17452d2369aSRobert Mustacchi.Ft link_flowctrl_t 17552d2369aSRobert Mustacchiare documented in 17652d2369aSRobert Mustacchi.Xr mac 9E . 17752d2369aSRobert Mustacchi.Pp 17852d2369aSRobert MustacchiThe 17952d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_str 18052d2369aSRobert Mustacchifunction sets the default value for properties that use strings. The 18152d2369aSRobert Mustacchidevice driver should ensure that it uses alphanumeric ASCII characters 18252d2369aSRobert Mustacchionly in the string to guarantee portability. 18352d2369aSRobert Mustacchi.Pp 18452d2369aSRobert MustacchiThe 18552d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_uint8 , 18652d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_uint16 , 18752d2369aSRobert Mustacchiand 18852d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_uint32 18952d2369aSRobert Mustacchifunctions set the default value for values whose properties are 8-, 16-, 19052d2369aSRobert Mustacchiand 32-bit unsigned values respectively. 19152d2369aSRobert Mustacchi.Sh CONTEXT 19252d2369aSRobert MustacchiThese functions are generally called on a handle passed into the 19352d2369aSRobert Mustacchi.Xr mc_propinfo 9E 19452d2369aSRobert Mustacchientry point, though they function in both 19552d2369aSRobert Mustacchi.Sy user 19652d2369aSRobert Mustacchiand 19752d2369aSRobert Mustacchi.Sy kernel 19852d2369aSRobert Mustacchicontext. 19952d2369aSRobert Mustacchi.Sh RETURN VALUES 20052d2369aSRobert MustacchiAll of the functions documented here do not return a value. It is not 20152d2369aSRobert Mustacchithe driver's responsibility to ensure that there is sufficient space for 20252d2369aSRobert Mustacchipermissions, ranges, or default values in the 20352d2369aSRobert Mustacchi.Ft mac_prop_info_handle_t 20452d2369aSRobert Mustacchistructures: the surrounding driver framework will transparently take 20552d2369aSRobert Mustacchicare of that and ensure that errors are correctly propagated. 20652d2369aSRobert Mustacchi.Sh SEE ALSO 20752d2369aSRobert Mustacchi.Xr mac 9E , 20852d2369aSRobert Mustacchi.Xr mc_getprop 9E , 20952d2369aSRobert Mustacchi.Xr mc_propinfo 9E , 21052d2369aSRobert Mustacchi.Xr mc_setprop 9E 211