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

NAME


mac_prop_info, 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_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).

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

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.

SEE ALSO


mac(9E), mc_getprop(9E), mc_propinfo(9E), mc_setprop(9E)

OmniOS May 31, 2016 OmniOS