illumos: manual page: mac_prop_info_set_range

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

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.