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. 133be0d903SRobert Mustacchi.\" Copyright 2021 Oxide Computer Company 1452d2369aSRobert Mustacchi.\" 153be0d903SRobert Mustacchi.Dd February 25, 2021 1652d2369aSRobert Mustacchi.Dt MAC_PROP_INFO 9F 1752d2369aSRobert Mustacchi.Os 1852d2369aSRobert Mustacchi.Sh NAME 1952d2369aSRobert Mustacchi.Nm mac_prop_info , 203be0d903SRobert Mustacchi.Nm mac_prop_info_set_default_fec , 2152d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_link_flowctrl , 2252d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_str , 2352d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_uint8 , 2452d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_uint32 , 2552d2369aSRobert Mustacchi.Nm mac_prop_info_set_default_uint64 , 2652d2369aSRobert Mustacchi.Nm mac_prop_info_set_perm , 2752d2369aSRobert Mustacchi.Nm mac_prop_info_set_range_uint32 2852d2369aSRobert Mustacchi.Nd mac property information functions 2952d2369aSRobert Mustacchi.Sh SYNOPSIS 3052d2369aSRobert Mustacchi.In sys/mac_provider.h 3152d2369aSRobert Mustacchi.Ft void 323be0d903SRobert Mustacchi.Fo mac_prop_info_set_default_fec 333be0d903SRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 343be0d903SRobert Mustacchi.Fa "link_fec_t fec" 353be0d903SRobert Mustacchi.Fc 363be0d903SRobert Mustacchi.Ft void 3752d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_link_flowctrl 3852d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 3952d2369aSRobert Mustacchi.Fa "link_flowctrl_t fctl" 4052d2369aSRobert Mustacchi.Fc 4152d2369aSRobert Mustacchi.Ft void 4252d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_str 4352d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 4452d2369aSRobert Mustacchi.Fa "const char *str" 4552d2369aSRobert Mustacchi.Fc 4652d2369aSRobert Mustacchi.Ft void 4752d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_uint8 4852d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 4952d2369aSRobert Mustacchi.Fa "uint8_t u8" 5052d2369aSRobert Mustacchi.Fc 5152d2369aSRobert Mustacchi.Ft void 5252d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_uint16 5352d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 5452d2369aSRobert Mustacchi.Fa "uint16_t u16" 5552d2369aSRobert Mustacchi.Fc 5652d2369aSRobert Mustacchi.Ft void 5752d2369aSRobert Mustacchi.Fo mac_prop_info_set_default_uint32 5852d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 5952d2369aSRobert Mustacchi.Fa "uint32_t u32" 6052d2369aSRobert Mustacchi.Fc 6152d2369aSRobert Mustacchi.Ft void 6252d2369aSRobert Mustacchi.Fo mac_prop_info_set_perm 6352d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 6452d2369aSRobert Mustacchi.Fa "uint8_t perm" 6552d2369aSRobert Mustacchi.Fc 6652d2369aSRobert Mustacchi.Ft void 6752d2369aSRobert Mustacchi.Fo mac_prop_info_set_range_uint32 6852d2369aSRobert Mustacchi.Fa "mac_prop_info_handle_t hdl" 6952d2369aSRobert Mustacchi.Fa "uint32_t low" 7052d2369aSRobert Mustacchi.Fa "uint32_t high" 7152d2369aSRobert Mustacchi.Fc 7252d2369aSRobert Mustacchi.Sh INTERFACE LEVEL 7352d2369aSRobert Mustacchiillumos DDI specific 7452d2369aSRobert Mustacchi.Sh PARAMETERS 7552d2369aSRobert Mustacchi.Bl -tag -width Ds 763be0d903SRobert Mustacchi.It Fa hdl 7752d2369aSRobert MustacchiA pointer to the MAC property information handle. 783be0d903SRobert Mustacchi.It Fa fctl 7972d3dbb9SYuri PankovA valid link flow control entry. 8072d3dbb9SYuri PankovValid values are documented in the 8152d2369aSRobert Mustacchi.Sy MAC_PROP_FLOWCTRL 8252d2369aSRobert Mustacchiproperty description in the 83*6ed464ecSRobert Mustacchi.Sy PROPERTIES 8452d2369aSRobert Mustacchisection of 8552d2369aSRobert Mustacchi.Xr mac 9E . 863be0d903SRobert Mustacchi.It Fa fec 873be0d903SRobert MustacchiA valid link forward error correction 883be0d903SRobert Mustacchi.Pq fec 893be0d903SRobert Mustacchischeme. 903be0d903SRobert MustacchiValid values are documented in the 913be0d903SRobert Mustacchi.Sy MAC_PROP_EN_FEC_CAP 923be0d903SRobert Mustacchiproperty description in the 93*6ed464ecSRobert Mustacchi.Sy PROPERTIES 943be0d903SRobert Mustacchisection of 953be0d903SRobert Mustacchi.Xr mac 9E . 963be0d903SRobert Mustacchi.It Fa str 9752d2369aSRobert MustacchiA null-terminated ASCII character string that describes that contains a 9852d2369aSRobert Mustacchivalue of a property. 993be0d903SRobert Mustacchi.It Fa u8 10052d2369aSRobert MustacchiAn 8-bit unsigned value. 1013be0d903SRobert Mustacchi.It Fa u16 10252d2369aSRobert MustacchiAn 16-bit unsigned value. 1033be0d903SRobert Mustacchi.It Fa u32 10452d2369aSRobert MustacchiAn 32-bit unsigned value. 1053be0d903SRobert Mustacchi.It Fa perm 10652d2369aSRobert MustacchiAn 8-bit unsigned value which is the bitwise inclusive OR of the 10752d2369aSRobert Mustacchifollowing values: 10852d2369aSRobert Mustacchi.Bl -tag -width Ds 10952d2369aSRobert Mustacchi.It Sy MAC_PROP_PERM_READ 11052d2369aSRobert MustacchiThis flag indicates that a property is 11152d2369aSRobert Mustacchi.Sy readable . 11252d2369aSRobert Mustacchi.It Sy MAC_PROP_PERM_WRITE 11352d2369aSRobert MustacchiThis flag indicates that a property is 11452d2369aSRobert Mustacchi.Sy writable . 11552d2369aSRobert Mustacchi.It Sy MAC_PROP_PERM_RW 11652d2369aSRobert MustacchiThis flag indicates that a property is both 11752d2369aSRobert Mustacchi.Sy readable 11852d2369aSRobert Mustacchiand 119bccbd30bSPeter Tribble.Sy writable . 12052d2369aSRobert MustacchiThis is equivalent to specifying both 12152d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_READ 12252d2369aSRobert Mustacchiand 12352d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_WRITE . 12452d2369aSRobert Mustacchi.El 1253be0d903SRobert Mustacchi.It Fa low 12652d2369aSRobert MustacchiA 32-bit unsigned value that represents the lowest possible value of an 12752d2369aSRobert Mustacchiinteger property, generally inclusive. 1283be0d903SRobert Mustacchi.It Fa high 12952d2369aSRobert MustacchiA 32-bit unsigned value that represents the highest possible value an 13052d2369aSRobert Mustacchiinteger property, generally inclusive. 13152d2369aSRobert Mustacchi.El 13252d2369aSRobert Mustacchi.Sh DESCRIPTION 13352d2369aSRobert MustacchiThe 13452d2369aSRobert Mustacchi.Sy mac_prop_info 13552d2369aSRobert Mustacchifamily of functions are used to fill in metadata about a given property 13652d2369aSRobert Mustacchias part of a driver's 13752d2369aSRobert Mustacchi.Xr mc_propinfo 9E 13872d3dbb9SYuri Pankoventry point. 13972d3dbb9SYuri PankovThese functions can be used to fill in information about the default value that 14072d3dbb9SYuri Pankovthe device assigns to a property and the permissions that a privileged user has 14172d3dbb9SYuri Pankovto update the property. 14252d2369aSRobert Mustacchi.Pp 14352d2369aSRobert MustacchiThe 14452d2369aSRobert Mustacchi.Fn mac_prop_info_set_perm 14572d3dbb9SYuri Pankovfunction is used to set the permissions of a property. 14672d3dbb9SYuri PankovThese permissions indicate whether or not the property can be read or modified 14772d3dbb9SYuri Pankovfrom the device driver's perspective. 14872d3dbb9SYuri PankovThe permissions for a given property should generally not change for a given 14972d3dbb9SYuri Pankovdevice and they do not need to take into account user privileges. 15072d3dbb9SYuri PankovFor the most case, properties will only take one of two values: 15152d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_READ 15252d2369aSRobert Mustacchior 15352d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_RW . 15452d2369aSRobert MustacchiUsually it does not make sense for a property to just have 15552d2369aSRobert Mustacchi.Sy MAC_PROP_PERM_WRITE . 15652d2369aSRobert Mustacchi.Pp 15752d2369aSRobert MustacchiSubsequent calls to the 15852d2369aSRobert Mustacchi.Fn mac_prop_info_set_perm 15952d2369aSRobert Mustacchifunction will override the values stored in previous calls. 16052d2369aSRobert Mustacchi.Pp 16152d2369aSRobert MustacchiThe 16252d2369aSRobert Mustacchi.Fn mac_prop_info_set_range_uint32 16352d2369aSRobert Mustacchifunction is used to indicate a range of possible integer values that a 16472d3dbb9SYuri Pankovdevice may take. 16572d3dbb9SYuri PankovThis range is generally inclusive, meaning the property may be set to any value 16672d3dbb9SYuri Pankovin the range of 16752d2369aSRobert Mustacchi.Fa low 16852d2369aSRobert Mustacchito 16952d2369aSRobert Mustacchi.Fa high . 17052d2369aSRobert MustacchiEach time the 17152d2369aSRobert Mustacchi.Fn mac_prop_info_set_range_uint32 17252d2369aSRobert Mustacchifunction is called, a new property range is added, allowing for multiple 17352d2369aSRobert Mustacchidisjoint ranges to be specified for a given property. 17452d2369aSRobert Mustacchi.Pp 17552d2369aSRobert MustacchiThe remaining functions, 1763be0d903SRobert Mustacchi.Fn mac_prop_info_set_default_fec , 17752d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_link_flowctrl , 17852d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_str , 17952d2369aSRobert Mustacchi.Fn mac_prop_info_set_uint8 , 18052d2369aSRobert Mustacchi.Fn mac_prop_info_set_uint16 , 18152d2369aSRobert Mustacchi.Fn mac_prop_info_set_uint32 , 18252d2369aSRobert Mustacchiand 18352d2369aSRobert Mustacchi.Fn mac_prop_info_set_range_uint32 18472d3dbb9SYuri Pankovupdate the default value of a given property. 18572d3dbb9SYuri PankovThe default value is the initial value that the property takes after the device 18672d3dbb9SYuri Pankovdriver has called 18752d2369aSRobert Mustacchi.Xr mac_register 9F . 18852d2369aSRobert MustacchiIf these functions are called multiple times, then the default value 18952d2369aSRobert Mustacchiwill be replaced with each call. 19052d2369aSRobert Mustacchi.Pp 19152d2369aSRobert MustacchiThe different functions each support a different type of default value 19272d3dbb9SYuri Pankovand some are used for specific properties. 19372d3dbb9SYuri PankovThe 19452d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_link_flowctrl 19552d2369aSRobert Mustacchifunction works with properties that describe flow control properties. 19652d2369aSRobert MustacchiThe various values of a 19752d2369aSRobert Mustacchi.Ft link_flowctrl_t 19852d2369aSRobert Mustacchiare documented in 19952d2369aSRobert Mustacchi.Xr mac 9E . 20052d2369aSRobert Mustacchi.Pp 20152d2369aSRobert MustacchiThe 20252d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_str 20372d3dbb9SYuri Pankovfunction sets the default value for properties that use strings. 20472d3dbb9SYuri PankovThe device driver should ensure that it uses alphanumeric ASCII characters 20552d2369aSRobert Mustacchionly in the string to guarantee portability. 20652d2369aSRobert Mustacchi.Pp 20752d2369aSRobert MustacchiThe 20852d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_uint8 , 20952d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_uint16 , 21052d2369aSRobert Mustacchiand 21152d2369aSRobert Mustacchi.Fn mac_prop_info_set_default_uint32 21252d2369aSRobert Mustacchifunctions set the default value for values whose properties are 8-, 16-, 21352d2369aSRobert Mustacchiand 32-bit unsigned values respectively. 2143be0d903SRobert Mustacchi.Pp 2153be0d903SRobert MustacchiThe 2163be0d903SRobert Mustacchi.Fn mac_prop_info_set_default_fec 2173be0d903SRobert Mustacchifunction is used for properties that describe link forward error 2183be0d903SRobert Mustacchicorrection values such as 2193be0d903SRobert Mustacchi.Dv MAC_PROP_EN_FEC_CAP 2203be0d903SRobert Mustacchiand 2213be0d903SRobert Mustacchi.Dv MAC_PROP_ADV_FEC_CAP . 2223be0d903SRobert MustacchiThe various values of a 2233be0d903SRobert Mustacchi.Ft link_fec_t 2243be0d903SRobert Mustacchiare documented in 2253be0d903SRobert Mustacchi.Xr mac 9E . 22652d2369aSRobert Mustacchi.Sh CONTEXT 22752d2369aSRobert MustacchiThese functions are generally called on a handle passed into the 22852d2369aSRobert Mustacchi.Xr mc_propinfo 9E 22952d2369aSRobert Mustacchientry point, though they function in both 23052d2369aSRobert Mustacchi.Sy user 23152d2369aSRobert Mustacchiand 23252d2369aSRobert Mustacchi.Sy kernel 23352d2369aSRobert Mustacchicontext. 23452d2369aSRobert Mustacchi.Sh RETURN VALUES 23572d3dbb9SYuri PankovAll of the functions documented here do not return a value. 23672d3dbb9SYuri PankovIt is not the driver's responsibility to ensure that there is sufficient space 23772d3dbb9SYuri Pankovfor permissions, ranges, or default values in the 23852d2369aSRobert Mustacchi.Ft mac_prop_info_handle_t 23952d2369aSRobert Mustacchistructures: the surrounding driver framework will transparently take 24052d2369aSRobert Mustacchicare of that and ensure that errors are correctly propagated. 24152d2369aSRobert Mustacchi.Sh SEE ALSO 24252d2369aSRobert Mustacchi.Xr mac 9E , 24352d2369aSRobert Mustacchi.Xr mc_getprop 9E , 24452d2369aSRobert Mustacchi.Xr mc_propinfo 9E , 24552d2369aSRobert Mustacchi.Xr mc_setprop 9E 246