Subject: Brussels: NDD compatiblity support [PSARC/2008/171 FastTrack timeout 03/11/2008] To: PSARC-ext@Sun.Com Cc: brussels-dev@opensolaris.org, sowmini-varadhan@sun.com Bcc: one-pager-list@sac.sfbay one-pager-log@sac.sfbay sac-bar@sac.sfbay 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/ \? 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 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 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 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