2009/235 dladm Possible Values List

[Garrett D'Amore]

James Carlson wrote:
> 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.
>   
There are other drivers which use the Brussels interfaces (e.g. afe & 
mxfe).  What happens to those drivers that don't support this "possible" 
interface?  What about the bnx driver?

    -- Garrett