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/ \? has traditionally been used to obtain the list of ndd parameters supported by . 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 passing the names of these properties along with the associated permissions during mac_register() using the interfaces to described in Section 4.1 below. These property names must begin with the "_" character, conformant with the defintion of the private property name space defined for dladm by PSARC 2007/429. - 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. - The input (output) for ND_SET (ND_GET) ioctls will be filtered through the mac layer such that a leading "_" character will be added (removed) as a prefix before passing in (out) property names of the non-canonical ndd properties to (from) the driver. 4. Exported Interfaces: ----------------------- Interface Classification Comments ----------------------------------------------------------------------------- mac_priv_prop_t Consolidation Private Section 4.1 MAC_PERM_{READ, WRITE} Consolidation Private r/w permissions for ndd properties defined in MAC_MAP_KSTAT Consolidation Private used internally to identify ndd props that map to kstats. 4.1 mac_priv_prop_t -------------------- Drivers wishing to support non-canonical ndd parameters must provide the names of these parameters to the GLDv3 framework when invoking mac_register() in their attach(9E) routine. The names of the parameters, along with the associated r/w permissions, must be passed in an array of mac_priv_prop_t structure that is defined in as typedef struct mac_priv_prop_s { char mpp_name[MAXLINKPROPNAME]; /* name of private property */ uint_t mpp_flags; /* permissions associated with property */ } mac_priv_prop_t; The array of mac_priv_prop_t structures must be passed to mac_register() through the following fields in the mac_register_t structure used for registration: typedef struct mac_register_s { /* * ..fields as defined in PSARC/2006/249 */ mac_priv_prop_t *m_priv_props; size_t m_priv_prop_count; } The property name being registered must start with the "_" character, conformant with the definition of private properties recognized by dladm(1m).