MAC_PROP_INFO(9F) Kernel Functions for Drivers MAC_PROP_INFO(9F)

mac_prop_info, mac_prop_info_set_default_fec, mac_prop_info_set_default_link_flowctrl, mac_prop_info_set_default_str, mac_prop_info_set_default_uint8, mac_prop_info_set_default_uint32, mac_prop_info_set_default_uint64, mac_prop_info_set_perm, mac_prop_info_set_range_uint32
mac property information functions

#include <sys/mac_provider.h>

void
mac_prop_info_set_default_fec(mac_prop_info_handle_t hdl, link_fec_t fec);

void
mac_prop_info_set_default_link_flowctrl(mac_prop_info_handle_t hdl, link_flowctrl_t fctl);

void
mac_prop_info_set_default_str(mac_prop_info_handle_t hdl, const char *str);

void
mac_prop_info_set_default_uint8(mac_prop_info_handle_t hdl, uint8_t u8);

void
mac_prop_info_set_default_uint16(mac_prop_info_handle_t hdl, uint16_t u16);

void
mac_prop_info_set_default_uint32(mac_prop_info_handle_t hdl, uint32_t u32);

void
mac_prop_info_set_perm(mac_prop_info_handle_t hdl, uint8_t perm);

void
mac_prop_info_set_range_uint32(mac_prop_info_handle_t hdl, uint32_t low, uint32_t high);

illumos DDI specific

hdl
A pointer to the MAC property information handle.
fctl
A valid link flow control entry. Valid values are documented in the MAC_PROP_FLOWCTRL property description in the PROPERTIES section of mac(9E).
fec
A valid link forward error correction (fec) scheme. Valid values are documented in the MAC_PROP_EN_FEC_CAP property description in the PROPERTIES section of mac(9E).
str
A null-terminated ASCII character string that describes that contains a value of a property.
u8
An 8-bit unsigned value.
u16
An 16-bit unsigned value.
u32
An 32-bit unsigned value.
perm
An 8-bit unsigned value which is the bitwise inclusive OR of the following values:
MAC_PROP_PERM_READ
This flag indicates that a property is readable.
MAC_PROP_PERM_WRITE
This flag indicates that a property is writable.
MAC_PROP_PERM_RW
This flag indicates that a property is both readable and writable. This is equivalent to specifying both MAC_PROP_PERM_READ and MAC_PROP_PERM_WRITE.
low
A 32-bit unsigned value that represents the lowest possible value of an integer property, generally inclusive.
high
A 32-bit unsigned value that represents the highest possible value an integer property, generally inclusive.

The mac_prop_info family of functions are used to fill in metadata about a given property as part of a driver's mc_propinfo(9E) entry point. These functions can be used to fill in information about the default value that the device assigns to a property and the permissions that a privileged user has to update the property.

The mac_prop_info_set_perm() function is used to set the permissions of a property. These permissions indicate whether or not the property can be read or modified from the device driver's perspective. The permissions for a given property should generally not change for a given device and they do not need to take into account user privileges. For the most case, properties will only take one of two values: MAC_PROP_PERM_READ or MAC_PROP_PERM_RW. Usually it does not make sense for a property to just have MAC_PROP_PERM_WRITE.

Subsequent calls to the mac_prop_info_set_perm() function will override the values stored in previous calls.

The mac_prop_info_set_range_uint32() function is used to indicate a range of possible integer values that a device may take. This range is generally inclusive, meaning the property may be set to any value in the range of low to high. Each time the mac_prop_info_set_range_uint32() function is called, a new property range is added, allowing for multiple disjoint ranges to be specified for a given property.

The remaining functions, mac_prop_info_set_default_fec(), mac_prop_info_set_default_link_flowctrl(), mac_prop_info_set_default_str(), mac_prop_info_set_uint8(), mac_prop_info_set_uint16(), mac_prop_info_set_uint32(), and mac_prop_info_set_range_uint32() update the default value of a given property. The default value is the initial value that the property takes after the device driver has called mac_register(9F). If these functions are called multiple times, then the default value will be replaced with each call.

The different functions each support a different type of default value and some are used for specific properties. The mac_prop_info_set_default_link_flowctrl() function works with properties that describe flow control properties. The various values of a link_flowctrl_t are documented in mac(9E).

The mac_prop_info_set_default_str() function sets the default value for properties that use strings. The device driver should ensure that it uses alphanumeric ASCII characters only in the string to guarantee portability.

The mac_prop_info_set_default_uint8(), mac_prop_info_set_default_uint16(), and mac_prop_info_set_default_uint32() functions set the default value for values whose properties are 8-, 16-, and 32-bit unsigned values respectively.

The mac_prop_info_set_default_fec() function is used for properties that describe link forward error correction values such as MAC_PROP_EN_FEC_CAP and MAC_PROP_ADV_FEC_CAP. The various values of a link_fec_t are documented in mac(9E).

These functions are generally called on a handle passed into the mc_propinfo(9E) entry point, though they function in both user and kernel context.

All of the functions documented here do not return a value. It is not the driver's responsibility to ensure that there is sufficient space for permissions, ranges, or default values in the mac_prop_info_handle_t structures: the surrounding driver framework will transparently take care of that and ensure that errors are correctly propagated.

mac(9E), mc_getprop(9E), mc_propinfo(9E), mc_setprop(9E)
February 25, 2021 OmniOS