2009/235 dladm Possible Values List

[James Carlson]

I'm sponsoring this fast-track request for Girish Moodalbail.  The
timer is set to 04/20/2009.


The consolidation is "ON" and the stability level for the interfaces 
being introduced is "Consolidation Private".

Introduction:
-------------

dladm(1m) does not display possible values for some properties like MTU. 
For a data-link which supports setting MTU on it, there exists a range of 
values (for e.g., 108-9000) that can be set as MTU. Today in ON we do 
not display that range (see CR 6680929) in 'dladm show-linkprop' output. 
MTU happens to be one such property and there could be many.

To display such range of values we need to contact driver or MAC layer 
(based on the property being queried). However there isn't any structure 
to represent
(a) range of values (read: integers, unsigned integers, et al) or
     collection of strings
(b) the type of the values returned and
(c) count of the range itself.

We want to provide one such structure and make it part of the linkprop 
framework itself, so that it will be useful for implementers to send in 
range of values from userspace to kernel or from kernel/driver to user 
space. This data structure would be defined in 'mac.h' and would be used 
as a value-result parameter (see below for more details).

Interfaces being added:
---------------------------

(a) Set of data structures to represent range of values (int32, int64, 
uint32, uint64, et al) or collection/enumeration of values (strings). 
For now we define uint32 range (mac_propval_uint32_range_t) for MTU. The 
framework can be extended for other types.

/*
  * Defines range of uint32 values. (108-9000)
  */
typedef struct mac_propval_uint32_range_s {
     uint32_t mpur_min;    /* minimum value in the range */
     uint32_t mpur_max;    /* maximum value in the range */
} mac_propval_uint32_range_t;

/*
  * Data type of the value.
  */
typedef enum {
     MAC_PROPVAL_UINT32 = 0x1

     /* Various other types could be
      * MAC_PROPVAL_INT32
      * MAC_PROPVAL_INT64
      * MAC_PROPVAL_UINT64
      * MAC_PROPVAL_STRING
      */
} mac_propval_type_t;

/*
  * Captures range of values for a given property. For e.g.,
  * - MTU property for a data link can have values between 68-9000.
  * - CPU property for a MAC client can have multiple CPU ranges
  *   1-6, 10-16 assigned to it.
  */
typedef struct mac_propval_range_s {
     uint_t mpr_count;                /* count of ranges */
     mac_propval_type_t mpr_type;    /* type of value */
     union {
         mac_propval_uint32_range_t mpr_uint32[1];
     } u;
} mac_propval_range_t;

#define    range_uint32    u.mpr_uint32

(b) MAC_PROP_POSSIBLE:
	In order to avoid explosion of MAC properties (read: MAC_PROP_YYY, 
MAC_PROP_YYY_RANGE, et al), we chose to use a new flag 
'MAC_PROP_POSSIBLE' to tell the drivers that the linkprop framework is 
interested in the range of property values. Device driver authors should 
  handle the above flag by populating the aforementioned data structures 
and returning them.
	This flag is in the same league as MAC_PROP_DEFAULT, which is used to 
tell the drivers to return default property value.

	NOTE: MAC_PROP_POSSIBLE flag needs to be handled 'carefully'. 
MAC_PROP_YYY by itself means current value of property, however 
MAC_PROP_YYY with MAC_PROP_POSSIBLE flag means range of property values. 
So when MAC_PROP_POSSIBLE flag is used for a particular property, one 
may have to change "all" the drivers to handle this flag for that 
property (i.e., either return 'ENOTSUP' when not supported or return 
'range of values').

Interface interaction details:
-------------------------------

The caller is responsible to allocate sufficient memory for the drivers 
to fill in the details. The caller provides a pointer to an array (union 
member 'u' of 'mac_propval_range_t') and a size of the array 
('mpr_count' of the 'mac_propval_range_t') and the callee will copy the 
data into that array. Upon success, mpr_count will have count of range 
of values and the array itself will have value range. However if 
sufficient memory was not allocated, the driver would return ENOBUF and 
would set 'mpr_count' to the required size of the array.

The query/reply mechanism is achieved by calling i_dladm_range_get() for 
query and the respective driver function <drv>_m_getprop() would reply 
back with the range of values.

i_dladm_range_get() is a function available in libdladm.so.1, which 
needs to be registered as a callback function in prop_desc_t[] table for 
those properties interested in range of values.

Following drivers would be changed to use the above structure:
     bge, e1000g, nxge, nge, hxge, vnic & aggr.
All the changes would be in the respective <drv>_m_getprop() function.