I'm sponsoring the following fasttrack for Sowmini Varadhan. Timeout is set
for March 11, 2008.
Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Brussels: NDD compatiblity support
1.2. Name of Document Author/Supplier:
Author: Sowmini Varadhan
1.3 Date of This Document:
04 March, 2008
4. Technical Description
Brussels: NDD compatiblity support
----------------------------------
1. Introduction
---------------
This case describes the ``ndd compatibility'' component of the umbrella
case for PSARC 2007/429, that will provide legacy support of
existing ndd usage at the GLDv3 layer using the methods
described in Section 2 of this document.
Release binding: minor
2. NDD Compatibility Problem
-----------------------------
Drivers typically parse the ioctl data for ndd(1m) ioctls
by using undocumented Mentat interfaces like nd_load() and nd_getset()
with these calls being unfortunately duplicated across drivers.
The duplicated logic can easily be avoided by parsing the ndd ioctl
mapping it to GLDv3 calls in the intermediate GLDv3 modules
(See CR 6667363).
2.1 Proposed Solution
---------------------
Variables typically covered by ndd(1m) for drivers are typically the
MII parameters defined in ieee802.3(5). For the purpose of this
document, we define these MII parameters, and particularly the syntax
used in ieee802.3(5) as "canonical ndd parameters".
In addition to the canonical parameters, it is not uncommon to encounter
other ndd parameters implemented in many drivers. For example, the bge
driver implements "adv_asym_pause_cap" instead of the ieee802.3(5)
version, adv_cap_asmpause. This document defines these variant
names supported in driver ndd implementations as "non-canonical
ndd parameters".
The public properties introduced by PSARC 2007/429 ("Brussels Enhanced
Network Driver Configuration Via dladm") and the ether_stats introduced
by PSARC 2006/248 ("Nemo MAC-Type Plugin Architecture") together cover
all of the canonical NDD parameters. Thus, when the mac layer recognizes
that mc_setprop and mc_getprop interfaces have been registered for the
driver, the ioctl data for the ndd call may be intercepted and parsed
at the mac layer and mapped to an equivalent GLDv3 call. All syntax,
permission and bound-checks will be performed at the mac layer, and the
driver only needs to provide mc_setprop/mc_getprop/mc_getstat callbacks.
Non-canonical NDD parameters will be passed to the driver as private
properties. The driver would have to do any string processing to parse
these properties, but would not need to invoke any other interfaces.
such as nd_load(), nd_getset() etc.
Note that Drivers not converted to the Brussels framework will continue
to function in the pre-Brussels manner. For these drivers, the mac
layer will not have a registered mc_setprop or mc_getprop callback,
so that the ioctl data will be passed down to the driver without
modification.
2.1 Getting Parameters Supported By the Driver
----------------------------------------------
The ndd invocation
# ndd -get /dev/<driver> \?
has traditionally been used to obtain the list of ndd parameters supported
by <driver>. Although it is not a Stable interface, this command
is widely used so that legacy support is justifiable. Support for
this invocation will be provided in the following manner:
- The driver must register any non-canonical properties that it supports
through its xxattach() routine by invoking the mac_register_priv_prop()
interface described in Section 4.1 below.
- The mac layer will provide a listing of the canonical ndd names as
well as the non-canonical names registed for the driver when it
receives a ND_GET ioctl for the "\?" parameter.
4. Exported Interfaces:
-----------------------
Interface Classification Comments
-----------------------------------------------------------------------------
mac_register_priv_prop Committed Section 4.1
DLD_PERM_{READ, WRITE} Committed r/w permissions
for ndd properties
defined in <sys/dld.h>
DLD_MAP_KSTAT Private used internally
to identify ndd props
that map to kstats.
4.1 mac_register_priv_prop()
----------------------------
Synopsis:
void mac_register_priv_prop(mac_handle_t mh, char *name, int flags)
Description:
Drivers wishing to support non-canonical ndd parameters must provide
the names of these parameters to the GLDv3 framework after
succesfully completing mac_register() in their attach(9E) routine.
Parameters:
mh mac_handle_t obtained after succesfully completing mac_register.
name property name of the non-canonical ndd prop to be registered
flags property flags defined in <sys/dld.h> which may be a logical OR of
{DLD_PERM_READ, DLD_PERM_WRITE}, describing read/write permissions
for the property.}
Returned value: None.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
