Tribblix: manual page: mac_prop

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

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.