illumos: manual page: mc

MC_PROPINFO(9E) Driver Entry Points MC_PROPINFO(9E)

NAME

mc_propinfo - get information about a property

SYNOPSIS

#include <sys/mac_provider.h>

void
prefix_m_propinfo(void *driver, const char *pr_name, mac_prop_id_t pr_num,
mac_prop_info_handle_t hdl);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

driver A pointer to the driver's private data that was passed in via the
m_pdata member of the mac_register(9S) structure to the
mac_register(9F) function.

pr_name
A null-terminated string that contains the name of the property.

pr_num The value indicates the property that the device is working with.

hdl A handle to use with the mac_prop_info(9F) family of routines to
indicate the property's metadata.

DESCRIPTION

The mc_propinfo() entry point is an optional entry point for networking
device drivers that is used to obtain metadata about a property, including
its permissions, default value, and information about valid possible
values. If the device driver does not implement either of the
mc_getprop(9E) or mc_setprop(9E) entry points then it does not need to
implement the mc_propinfo() entry point. However, it is highly recommended
that these interfaces be implemented in order to give users and
administrators of the system access to the properties of the device.

When the mc_propinfo() entry point is called, the driver needs to first
identify the property. The set of possible properties and their meaning is
listed in the PROPERTIES section of mac(9E). It should identify the
property based on the value of pr_num. Most drivers will use a switch
statement and for any property that it supports it should call the
appropriate mac_prop_info(9F) functions to set values and then return.
When an unknown or unsupported property is encountered, generally the
default case of the switch statement, the device driver should simply do
nothing and return.

The special property MAC_PROP_PRIVATE indicates that this is a device
driver specific private property. The device driver must then look at the
value of the pr_name argument and use strcmp(9F) on it, comparing it to
each of its private properties to identify which one it is.

For each property the driver has three different sets of information that
it can fill in. The driver should try to fill in all of these that make
sense, if possible.

1. First, the driver should fill in the permissions of the property with
the mac_prop_info_set_perm(9F) function. These permissions indicate
what the device driver supports for a given property. For each non-
private property, see the property list in mac(9E) to see what the
maximum property permissions are. As discussed in mac(9E), a device
driver may have more limited permissions than the default. For
example, on some SFP-based devices, it may not be possible to change
any of the auto-negotiation properties.

2. The driver should then fill in any default value that it has for a
property. This is the value that the device driver sets by default if
no other tuning has been performed. There are different functions
depending on the type of the default value to call. They are all
listed in mac_prop_info(9F).

3. Finally, a driver may optionally set one or more value ranges. These
are used for integer properties such as MAC_PROP_MTU. The driver may
call mac_prop_info_set_range_uint32(9F) to set a series of one or more
inclusive ranges that describe valid values for the property. For
example, a device that supports jumbo frames up to 9600 bytes would
call mac_prop_info_set_range_uint32(9F) to convey that it supports
MTUs in the range of 1500-9600 bytes.

If the device driver needs to access its private data, it will be available
in the driver argument which it should cast to the appropriate structure.
From there, the device driver may need to lock the structure to ensure that
access to it is properly serialized.

RETURN VALUES

The mc_propinfo() entry point does not have a return value. Drivers should
simply ignore and immediately return when encountering unsupported and
unknown properties.

EXAMPLES

The following example shows how a device driver might structure its
mc_propinfo() entry point.

#include <sys/mac_provider.h>

/*
* Note, this example merely shows the structure of this function.
* Different devices will manage their state in different ways. Like other
* examples, this assumes that the device has state in a structure called
* example_t and that there is a lock which keeps track of that state.
*/

static void
example_m_propinfo(void *arg, const char *pr_name, mac_prop_id_t pr_num,
mac_prop_info_handle_t prh)
{
uint8_t value;
uint_t perm;

example_t *ep = arg;

mutex_enter(&ep->ep_lock);

switch (pr_num) {
/*
* We try to fill in as much information for each property as makes
* sense. In some cases, you may only be able to set the permissions.
*/
case MAC_PROP_DUPLEX:
case MAC_PROP_SPEED:
mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ);
break;

/*
* The MTU is a good example of a property that has a property range.
* The range represents the valid values the MTU can take.
*/
case MAC_PROP_MTU:
mac_prop_info_set_perm(prh, MAC_PROP_PERM_RW);
mac_prop_info_set_range(prh, ep->ep_min_mtu, ep->ep_max_mtu);
break;

/*
* The ADV properties represent things that the device supports and
* can't be changed by the user. These are good examples of properties
* that have a default value and are read-only.
*/
case MAC_PROP_ADV_100FDX_CAP:
mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ);
value = (ep->ep_link_sup_speeds & EXAMPLE_100FDX) ? 1 : 0;
mac_prop_info_set_default_uint8(prh, value);
break;
case MAC_PROP_ADV_1000FDX_CAP:
mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ);
value = (ep->ep_link_sup_speeds & EXAMPLE_1000FDX) ? 1 : 0;
mac_prop_info_set_default_uint8(prh, value);
break;
case MAC_PROP_ADV_10GFDX_CAP:
mac_prop_info_set_perm(prh, MAC_PROP_PERM_READ);
value = (ep->ep_link_sup_speeds & EXAMPLE_10GDX) ? 1 : 0;
mac_prop_info_set_default_uint8(prh, value);
break;

/*
* The EN properties represent the speeds advertised by the driver. On
* baseT (copper) PHYs, we allow them to be set, otherwise we don't.
* This driver always advertises it if supported, hence why all of these
* default to advertised if the link supports its.
*/
case MAC_PROP_EN_100FDX_CAP:
perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ?
MAC_PROP_PERM_RW : MAC_PROP_PERM_READ;
mac_prop_info_set_perm(prh, perm);
value = (ep->ep_link_sup_speeds & EXAMPLE_100FDX) ? 1 : 0;
mac_prop_info_set_default_uint8(prh, value);
break;
case MAC_PROP_EN_1000FDX_CAP:
perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ?
MAC_PROP_PERM_RW : MAC_PROP_PERM_READ;
mac_prop_info_set_perm(prh, perm);
value = (ep->ep_link_sup_speeds & EXAMPLE_1000FDX) ? 1 : 0;
mac_prop_info_set_default_uint8(prh, value);
break;
case MAC_PROP_EN_10GFDX_CAP:
perm = ep->ep_link_type == EXAMPLE_LINK_COPPER ?
MAC_PROP_PERM_RW : MAC_PROP_PERM_READ;
mac_prop_info_set_perm(prh, perm);
value = (ep->ep_link_sup_speeds & EXAMPLE_10GFDX) ? 1 : 0;
mac_prop_info_set_default_uint8(prh, value);
break;

/*
* If this device has private properties, then it should compare pr_name
* with the device's private properties and then fill in property
* information if it recognizes the name.
*/
case MAC_PROP_PRIVATE:
break;

/*
* For unknown properties, there's not much to do. Simply don't call any
* of the mac_prop_info(9F) related functions.
*/
default:
break;
}
mutex_exit(&ep->ep_lock);
}