NAME

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

SYNOPSIS

#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);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

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 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 of an integer property, generally inclusive.

DESCRIPTION

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).

CONTEXT

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.

RETURN VALUES

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.