From jw137282@sac.sfbay.sun.com Thu Nov 19 22:19:56 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAK6JufQ003544 for ; Thu, 19 Nov 2009 22:19:56 -0800 (PST) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAK6JsNx053910; Thu, 19 Nov 2009 23:19:55 -0700 (MST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTE0050J9L7Q300@brm-avmta-1.central.sun.com>; Thu, 19 Nov 2009 23:19:55 -0700 (MST) Received: from dm-sfbay-01.sfbay.sun.com ([129.145.155.118]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTE003W89L5GR00@brm-avmta-1.central.sun.com>; Thu, 19 Nov 2009 23:19:53 -0700 (MST) Received: from sac.sfbay.sun.com (sac.SFBay.Sun.COM [129.146.226.132]) by dm-sfbay-01.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nAK6JrTf014552; Thu, 19 Nov 2009 22:19:53 -0800 (PST) Received: from sac.sfbay.sun.com (localhost [127.0.0.1]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAK6JqBV003539; Thu, 19 Nov 2009 22:19:52 -0800 (PST) Received: (from jw137282@localhost) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8/Submit) id nAK6Jqpd003535; Thu, 19 Nov 2009 22:19:52 -0800 (PST) Date: Thu, 19 Nov 2009 22:19:52 -0800 (PST) From: James Walker Subject: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] To: PSARC-ext@sun.com Cc: nicolas.droux@sun.com Message-id: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 15406 I'm sponsoring this case for Nicolas Droux. The man pages and header files are located in the materials directory. This case is requesting a patch binding. Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI This information is Copyright 2009 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: Public GLDv3 Interfaces 1.2. Name of Document Author/Supplier: Author: Nicolas Droux 1.3 Date of This Document: 19 November, 2009 4. Technical Description Introduction ============ The GLDv3 (Generic Lan Driver version 3) provider API was first introduced as part of the Nemo project (PSARC/2004/571). The API was initially a project-private API and was later promoted to a consolidation private API within the ON consolidation (PSARC/2005/396.) These APIs were kept consolidation private to gain experience with the APIs, and in anticipation of other projects which were planning to extend the APIs, for example Crossbow (PSARC 2006/357). This effort commits a core subset of the GLDv3 provider APIs for use by Ethernet drivers outside of the ON consolidation. This subset does not include advanced features such as hardware classification or polling, which are exposed through capabilities. In the future these capabilities may be promoted to committed interfaces as they mature and stabilize. Note that this case defines a stable driver API only for Ethernet drivers, i.e. drivers registering with a plugin type of MAC_PLUGIN_IDENT_ETHER. GLDv3 Provider Interface Overview ================================= The GLDv3 driver API is a function calls-based interface (in contrast to a STREAMs-based interface), which is designed for extensibility, and for high performance. The interface consist of a set of driver entry points which are advertised during registration with the MAC layer, a set of MAC entry points which are invoked by drivers, and a set of capabilities which are used for advanced features. Driver related structures are defined in the header file header file. The driver should not include any other MAC-related header file. Registration ============ A GLDv3 device driver calls mac_register(9F) to register a new instance with the framework. mac_register(9F) is typically called from the attach(9E) entry point implemented by the device driver. mac_register(9F) must be passed as input a pointer to a mac_register(9S) structure. The registration information structure mac_register(9S) must be allocated through a call to mac_alloc(9F). mac_alloc(9F) takes as argument a version number, that version must be set to MAC_VERSION_V1 which is the version described by this document. Note: the version MAC_VERSION_V1 must be specified by drivers which implement the API described by this document. If new versions of the API are defined in the future, the version number will be incremented, and the GLDv3 framework may support one or more versions of the APIs. Having a specific MAC_VERSION_V1, instead of always using, for example, MAC_VERSION which contains the latest version number, will allow unbundled drivers to be compiled on an ON build which support more than one versions of the API. The entry points and data structures used during MAC registration are summarized below. When applicable, a reference to the file which contains a detailed description of the function or data structure is provided. extern mac_register_t *mac_alloc(uint_t version); Allocates a new structure of type mac_register_t, which can be subsequently be passed to mac_register(9F). The version argument must be set to MAC_VERSION_V1. [mac-9f.txt] extern int mac_register(mac_register_t *, mac_handle_t *); Registers a new GLDv3 MAC instance with the MAC layer. This entry point is typically invoked from the attach(9E) entry point of a physical NIC device driver, or when a pseudo MAC instance is created. Note: the public GLDv3 interface only supports physical GLDv3 devices. Creating pseudo devices require the use of other dls kernel entry points and exchange of link ids which for now are staying consolidation-private. [mac-9f.txt] extern int mac_unregister(mac_handle_t); Unregisters a MAC instance which was previously registered with mac_register(9F). [mac-9f.txt] typedef struct mac_register_s mac_register_t; MAC registration structure. Allocated by mac_alloc(9F) and passed to mac_register(9F). [mac_register-9s.txt] typedef struct mac_callbacks_s mac_callbacks_t; A pointer to a structure of type mac_callback_t is passed using the m_callbacks field of the mac_register_t structure. The mac_callbacks_t data-structure allows the driver to expose its entry points to the MAC layer. These entry points are used to start/stop the adapters, manage multicast addresses, set promiscuous mode, query the capabilities of the adapter, get and set properties, and so forth. The mac_callback_t data-structure contains a mc_callbacks bit-mask which allows data-structure to support new entry points in the future, while maintaining backward-compatibility. mc_callback can be a combination of the flags MC_IOCTL, MC_GETCAPAB, MC_SETPROP, MC_GETPROP, and MC_PROPINFO [mac_callbacks-9s.txt] Capabilities ============ GLDv3 implements a capability mechanism which allows the framework to query and enable capabilities which may not be supported by all GLDv3 drivers. Some capabilities are project private, some capabilities are consolidation private, and some capabilities are part of the stable interface proposed by this case. In particular, the capabilities being committed here are defined through the mac_capab_t enum, and are listed below. MAC_CAPAB_HCKSUM Hardware checksum offload Detailed information about this capability is passed from the driver to the stack as part of the capability query by setting a combination of the following flags. - HCKSUM_INET_PARTIAL - HCKSUM_INET_FULL_V4 - HCKSUM_INET_FULL_V6 - HCKSUM_IPHDRCKSUM Checksum offload meta-data is queried and set through the mac_hcksum_get(9F) and mac_hcksum_set(9F), respectively. MAC_CAPAB_LSO Large Segment (or Send) Offload Detailed information about the capability is passed during capability through the mac_capab_lso_t structure which consists of a structure of type lso_basic_tcp_ipv4_t, and a scalar value. Per-packet LSO meta-data can be obtained by driver using the mac_lso_get(9F) entry point. Capabilities are queried through the mc_getcapab entry point which is specified through the mac_callback(9S) structure. If a capability is supported by the driver, it passes information about that capability, such as capability-specific entry points, flags, etc, through the mc_getcapab entry point. These capabilities and associated data structures and definitions are described in details in [mac-9e.txt] Control Operations ================== The driver is controlled by the MAC layer using the driver entry points exposed through the mac_callback structure, see above, as well as mac_callbacks-9s.txt. The control entry points are exposed by drivers, these entry points are described in details in mac-9e.txt. mc_start Start a driver instance. This entry point is invoked by the framework before any operation is attempted. mc_stop Stop a driver instance. mc_setpromisc Set the promiscuous mode of a driver instance. mc_multicst Add or remove a multicast address mc_unicst Set by the driver to change the primary MAC address of the driver instance. mc_ioctl Optional ioctl entry point. mc_setprop Set a property value. mc_getprop Get a property value. mc_propinfo Get information about a property Data Path ========= Data-path entry points consist of callbacks exported by the driver and invoked by the framework for sending packets, and framework entry points called by the driver for transmit flow control and receiving packets. Transmit Data Path ------------------ The drivers expose a transmit entry point mc_tx through the callback data-structure, see the Registration section above, and [mac-9e.txt] for details. The transmit entry point is passed a chain of one or more packets linked in a list of mblk_t's. - Flow control: If the driver cannot send the packets due to a lack of hardware resources, it returns the sub-chain of packets that could not be sent. When more descriptors become available at a later time, the driver must notify the framework by invoking mac_tx_update() [mac-9f.txt] - Hardware checksumming: If the driver advertised hardware checksum capabilities, it is responsible to check every packet for hardware checksum meta-data by invoking mac_hcksum_get(9F), and program the hardware to perform the required checksum calculation [hcksum_retrieve-9f.txt] - LSO: If the driver advertised LSO capabilities, it is responsible to check every packet for LSO meta-data using the mac_lso_get(9F) entry point, and programming the hardware to segment the large segment into smaller packets [mac_lso_get-9f.txt] - VLANs: When VLANs are configured by the administrator using VLAN or VNIC data links, the MAC layer inserts the needed VLAN headers on the outbound packets before they are passed to the driver via the m_tx entry point. Receive Data Path ----------------- The device driver passes up received packets to the stack by passing the received packets as chains through mac_rx() [mac-9f.txt] - Hardware checksumming If the driver supports, hardware checksumming, it must invoke the mac_hcksum_set(9F) entry point to associate hardware checksumming meta-data to the packet. [hcksum_retrieve-9f.txt] - VLANs: VLAN packets must be passed with their tags to the MAC layer. The driver should not strip the VLAN headers from the packets. Notifications ============= The following functions can be invoke by a driver to notify the network stack that its state has changed: - mac_tx_update(9F) Invoked to notify the framework that more TX descriptors are available. [mac-9f.txt] - mac_link_update(9F) Invoked to notify the framework that the state of the link has changed. [mac-9f.txt] Statistics ========== Device drivers are expected to maintain a set of statistics for the device instances they manage. These statistics are queried by the MAC layer by invoking the mc_getstat entry point of the mc_getstat entry point of the driver [mac-9e.txt] The GLD statistics supported are the union of generic MAC statistics, and Ethernet-specific statistics that are common across Nevada and S10. Properties ========== Brussels properties, first introduced by PSARC/2007/429, are part of the committed GLDv3 interface. In order to simplify the driver interface, and to address issues with Brussels extension PSARC/2009/235 (dladm Possible Values List), which cannot be promoted to committed interface due to architectural issues, the driver properties interface are revisited as part of this case. More specifically, a new driver entry point, mc_propinfo, is introduced, and used by the driver to return immutable information about a property. This information includes permissions, default values, and allowed value ranges. The mc_getprop interface can be simplified because it can focus on returning the current value of a property. The new mc_propinfo interface is easily extensible while preserving backward compatibility. These updated properties interfaces are described in details in [mac-9e.txt] and [mac_prop_info_set_perm-9f.txt] The driver is also able to expose private properties. As defined by Brussels NDD compatiblity support (SPARC/2008/171), private properties were passed by the driver to the framework during registration using the m_priv_props and m_priv_prop_count fields of the mac_register_t structure. m_priv_prop was defined as an array of mac_priv_prop_t elements, which included the name and permission for each private property. Because property permissions can be provided by the mc_propinfo() entry point, m_priv_props can be simplified to be an array of strings containing property names. The list can be NULL-terminated, allowing the removal of the m_priv_prop_count field. m_priv_propos field is defined in [mac_register-9s.txt] Interface Table =============== Exported Interfaces Interface Name Classification Comments --------------------------------------------------------------------------- mac_alloc(9F) Committed Allocate a mac_register_t mac_free(9F) Committed Free a mac_register_t mac_register(9F) Committed Register with MAC layer mac_unregister(9F) Committed Unregister from MAC layer mac_rx(9F) Committed Pass up received packet(s) mac_tx_update(9F) Committed TX resources are available mac_link_update(9F) Committed Link state has changed mac_hcksum_get(9F) Committed Retrieve HW checksum info mac_hcksum_set(9F) Committed Attach HW checksum info mac_lso_get(9F) Committed Retrieve LSO info mc_getstat(9E) Committed Retrieve stats from driver mc_start(9E) Committed Start driver instance mc_stop(9E) Committed Stop driver instance mc_setpromisc(9E) Committed Set promiscuous mode mc_multicst(9E) Committed Add or remove mcast address mc_unicst(9E) Committed Set primary unicast address mc_tx(9E) Committed Send one or more packets mc_ioctl(9E) Committed ioctl driver interface mc_getcapab(9E) Committed Retrieve capabilities mac_register_t(9S) Committed Registration information mac_callback_t(9S) Committed Driver callbacks mac_capab_lso_t(9S) Committed LSO meta-data lso_basic_tcp_ipv4_t(9S) Committed LSO meta-data for TCP/IPv4 mac_prop_info_set_perm(9F) Committed Set permission of a property mac_prop_info_set_default_*(9F) Committed Set property value mac_prop_info_set_range_*(9F) Committed Set property values range MAC_VERSION_V1 Committed Committed interface version MC_IOCTL Committed mc_ioctl present MC_GETCAPAB Committed mc_getcapab present MAC_CAPAB_HCKSUM Committed HW checksumming capability MAC_CAPAB_LSO Committed LSO capability MAC_HCKSUM_INET_PARTIAL Committed HW cksum partial offload MAC_HCKSUM_INET_FULL_V4 Committed HW cksum IPv4 full offload MAC_HCKSUM_INET_FULL_V6 Committed HW cksum IPv6 full offload MAC_HCKSUM_IPHDRCKSUM Committed HW IP hdr cksum offload These interfaces are defined in more details in the man pages found in the man/ materials sub-directory. The man/README.txt file contains an index of the man page drafts and the interfaces they describe. Release Binding =============== Patch Files and Packages ================== The following files will be delivered as part of the package SUNWhea: /usr/include/sys/mac.h /usr/include/sys/mac_provider.h /usr/include/sys/mac_ether.h References ========== PSARC/2004/571 - Nemo - x86 Network Driver Enhancements PSARC/2005/207 - Clearview for Nemo PSARC/2005/365 - Nemo drivers interface simplification PSARC/2006/248 - Nemo MAC-Type Plugin Architecture PSARC/2006/249 - Nemo Changes for Binary Compatibility PSARC/2006/357 - Crossbow - Network Virtualization and Resource Management PSARC/2007/429 - Brussels - enhanced network driver configuration PSARC/2008/171 - Brussels: NDD compatiblity support PSARC/2008/222 - Brussels persistence 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 From Sebastien.Roy@Sun.COM Fri Nov 20 09:13:54 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAKHDsFi028400 for ; Fri, 20 Nov 2009 09:13:54 -0800 (PST) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAKHDpki017206 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Fri, 20 Nov 2009 10:13:53 -0700 (MST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTF00L2Z3V5HE00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 09:13:53 -0800 (PST) Received: from brmea-mail-1.sun.com ([192.18.98.31]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTF0073V3V46V90@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 09:13:52 -0800 (PST) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-1.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAKHDqgx023010 for ; Fri, 20 Nov 2009 17:13:52 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTF003002Z9Y900@mail-amer.sun.com> for PSARC-ext@Sun.Com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 10:13:52 -0700 (MST) Received: from [129.148.174.103] ([unknown] [129.148.174.103]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTF00DDI3UYJCF0@mail-amer.sun.com>; Fri, 20 Nov 2009 10:13:47 -0700 (MST) Date: Fri, 20 Nov 2009 12:11:07 -0500 From: Sebastien Roy Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> Sender: Sebastien.Roy@Sun.COM To: James Walker Cc: PSARC-ext@Sun.COM, Nicolas.Droux@Sun.COM Message-id: <1258737067.10163.84.camel@strat> Organization: Sun Microsystems MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> Status: RO Content-Length: 237 I haven't reviewed the materials fully yet, but a quick string search of the spec doesn't turn up any references to mac_init_ops(), and this function must be called in drivers' _init() routines. This may have been an oversight. -Seb From Nicolas.Droux@Sun.COM Fri Nov 20 11:26:03 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAKJQ3uZ000349 for ; Fri, 20 Nov 2009 11:26:03 -0800 (PST) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAKJQ28L048303 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Fri, 20 Nov 2009 12:26:03 -0700 (MST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTF00I0H9ZEQS00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 12:26:02 -0700 (MST) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTF001CC9ZEMX90@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 12:26:02 -0700 (MST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAKJQ2vg025074 for ; Fri, 20 Nov 2009 19:26:02 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTF00D009BOIQ00@mail-amer.sun.com> for PSARC-ext@Sun.Com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 12:26:02 -0700 (MST) Received: from [129.146.227.50] ([unknown] [129.146.227.50]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTF007DK9YZLK80@mail-amer.sun.com>; Fri, 20 Nov 2009 12:25:55 -0700 (MST) Date: Fri, 20 Nov 2009 11:25:29 -0800 From: Nicolas Droux Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <1258737067.10163.84.camel@strat> Sender: Nicolas.Droux@Sun.COM To: Sebastien Roy Cc: James Walker , PSARC-ext@Sun.COM Message-id: <4B06ED29.8080002@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> User-Agent: Thunderbird 2.0.0.23 (X11/20090929) Status: RO Content-Length: 646 Seb, My intent is to include this entry point as part of the GLDv3 APIs being committed. It is documented it in the mac(9F) man page draft [1], but I did not list it in the overview. I will update the spec to list it there as well. Nicolas. [1] Available in the materials for the case, see http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/mac-9f.txt Sebastien Roy wrote: > I haven't reviewed the materials fully yet, but a quick string search of > the spec doesn't turn up any references to mac_init_ops(), and this > function must be called in drivers' _init() routines. This may have > been an oversight. > > -Seb > > From Sebastien.Roy@sun.com Fri Nov 20 11:29:17 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAKJTH88000461 for ; Fri, 20 Nov 2009 11:29:17 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAKJTFZM050418 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Fri, 20 Nov 2009 12:29:17 -0700 (MST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTF0090DA4S5C00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Fri, 20 Nov 2009 11:29:16 -0800 (PST) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTF00J8YA4RR9E0@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Fri, 20 Nov 2009 11:29:15 -0800 (PST) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAKJTFZW026418 for ; Fri, 20 Nov 2009 19:29:15 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTF006009CIJ100@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Fri, 20 Nov 2009 12:29:15 -0700 (MST) Received: from [129.148.174.103] ([unknown] [129.148.174.103]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTF001WGA4OY920@mail-amer.sun.com>; Fri, 20 Nov 2009 12:29:13 -0700 (MST) Date: Fri, 20 Nov 2009 14:26:33 -0500 From: Sebastien Roy Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <4B06ED29.8080002@sun.com> Sender: Sebastien.Roy@sun.com To: Nicolas Droux Cc: James Walker , PSARC-ext@sun.com Message-id: <1258745193.10163.108.camel@strat> Organization: Sun Microsystems MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> Status: RO Content-Length: 392 On Fri, 2009-11-20 at 11:25 -0800, Nicolas Droux wrote: > Seb, > > My intent is to include this entry point as part of the GLDv3 APIs being > committed. It is documented it in the mac(9F) man page draft [1], > but I did not list it in the overview. I will update the spec to list it > there as well. Great, thanks. I'll take a closer look at the materials over the next few days. -Seb From gdamore@Sun.COM Fri Nov 20 12:54:10 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAKKsALD002033 for ; Fri, 20 Nov 2009 12:54:10 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAKKs8nX040446 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Fri, 20 Nov 2009 13:54:10 -0700 (MST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTF00E03E29CY00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 12:54:09 -0800 (PST) Received: from sca-es-mail-1.sun.com ([192.18.43.132]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTF00AYAE285930@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 12:54:08 -0800 (PST) Received: from fe-sfbay-09.sun.com ([192.18.43.129]) by sca-es-mail-1.sun.com (8.13.7+Sun/8.12.9) with ESMTP id nAKKs8g9021500 for ; Fri, 20 Nov 2009 12:54:08 -0800 (PST) Received: from conversion-daemon.fe-sfbay-09.sun.com by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTF00300DPQ9B00@fe-sfbay-09.sun.com> for PSARC-ext@Sun.Com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 12:54:08 -0800 (PST) Received: from [192.168.251.11] ([unknown] [76.93.15.33]) by fe-sfbay-09.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTF00DUPE27OYD0@fe-sfbay-09.sun.com>; Fri, 20 Nov 2009 12:54:07 -0800 (PST) Date: Fri, 20 Nov 2009 12:54:07 -0800 From: "Garrett D'Amore" Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> Sender: Garrett.Damore@Sun.COM To: James Walker Cc: PSARC-ext@Sun.COM, Nicolas.Droux@Sun.COM Message-id: <4B0701EF.9080902@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> User-Agent: Thunderbird 2.0.0.23 (X11/20091013) Status: RO Content-Length: 16266 +1. Is it the project teams intention to backport the LSO support to S10 as well? - Garrett James Walker wrote: > I'm sponsoring this case for Nicolas Droux. The man pages and header files > are located in the materials directory. This case is requesting a patch > binding. > > Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI > This information is Copyright 2009 Sun Microsystems > 1. Introduction > 1.1. Project/Component Working Name: > Public GLDv3 Interfaces > 1.2. Name of Document Author/Supplier: > Author: Nicolas Droux > 1.3 Date of This Document: > 19 November, 2009 > 4. Technical Description > > Introduction > ============ > > The GLDv3 (Generic Lan Driver version 3) provider API was first > introduced as part of the Nemo project (PSARC/2004/571). The API was > initially a project-private API and was later promoted to a > consolidation private API within the ON consolidation > (PSARC/2005/396.) > > These APIs were kept consolidation private to gain experience with the > APIs, and in anticipation of other projects which were planning to > extend the APIs, for example Crossbow (PSARC 2006/357). > > This effort commits a core subset of the GLDv3 provider APIs for use > by Ethernet drivers outside of the ON consolidation. This subset does > not include advanced features such as hardware classification or > polling, which are exposed through capabilities. In the future these > capabilities may be promoted to committed interfaces as they mature > and stabilize. > > Note that this case defines a stable driver API only for Ethernet > drivers, i.e. drivers registering with a plugin type of > MAC_PLUGIN_IDENT_ETHER. > > GLDv3 Provider Interface Overview > ================================= > > The GLDv3 driver API is a function calls-based interface (in contrast > to a STREAMs-based interface), which is designed for extensibility, > and for high performance. > > The interface consist of a set of driver entry points which are > advertised during registration with the MAC layer, a set of MAC entry > points which are invoked by drivers, and a set of capabilities which > are used for advanced features. > > Driver related structures are defined in the header file > header file. The driver should not include any > other MAC-related header file. > > Registration > ============ > > A GLDv3 device driver calls mac_register(9F) to register a new > instance with the framework. mac_register(9F) is typically called from > the attach(9E) entry point implemented by the device driver. > mac_register(9F) must be passed as input a pointer to a > mac_register(9S) structure. > > The registration information structure mac_register(9S) must be > allocated through a call to mac_alloc(9F). mac_alloc(9F) takes as > argument a version number, that version must be set to MAC_VERSION_V1 > which is the version described by this document. > > Note: the version MAC_VERSION_V1 must be specified by drivers which > implement the API described by this document. If new versions of the > API are defined in the future, the version number will be incremented, > and the GLDv3 framework may support one or more versions of the > APIs. Having a specific MAC_VERSION_V1, instead of always using, for > example, MAC_VERSION which contains the latest version number, will > allow unbundled drivers to be compiled on an ON build which support > more than one versions of the API. > > The entry points and data structures used during MAC registration are > summarized below. When applicable, a reference to the file which > contains a detailed description of the function or data structure is > provided. > > extern mac_register_t *mac_alloc(uint_t version); > > Allocates a new structure of type mac_register_t, which > can be subsequently be passed to mac_register(9F). > The version argument must be set to MAC_VERSION_V1. [mac-9f.txt] > > extern int mac_register(mac_register_t *, mac_handle_t *); > > Registers a new GLDv3 MAC instance with the MAC layer. > This entry point is typically invoked from the > attach(9E) entry point of a physical NIC device driver, > or when a pseudo MAC instance is created. > > Note: the public GLDv3 interface only supports physical > GLDv3 devices. Creating pseudo devices require the use of other > dls kernel entry points and exchange of link ids which for now > are staying consolidation-private. [mac-9f.txt] > > extern int mac_unregister(mac_handle_t); > > Unregisters a MAC instance which was previously registered > with mac_register(9F). [mac-9f.txt] > > typedef struct mac_register_s mac_register_t; > > MAC registration structure. Allocated by mac_alloc(9F) > and passed to mac_register(9F). [mac_register-9s.txt] > > typedef struct mac_callbacks_s mac_callbacks_t; > > A pointer to a structure of type mac_callback_t is passed > using the m_callbacks field of the mac_register_t structure. > The mac_callbacks_t data-structure allows the driver to expose > its entry points to the MAC layer. These entry points are used > to start/stop the adapters, manage multicast addresses, set > promiscuous mode, query the capabilities of the adapter, get > and set properties, and so forth. > > The mac_callback_t data-structure contains a mc_callbacks > bit-mask which allows data-structure to support new > entry points in the future, while maintaining > backward-compatibility. > > mc_callback can be a combination of the flags MC_IOCTL, > MC_GETCAPAB, MC_SETPROP, MC_GETPROP, and > MC_PROPINFO [mac_callbacks-9s.txt] > > Capabilities > ============ > > GLDv3 implements a capability mechanism which allows the framework to > query and enable capabilities which may not be supported by all GLDv3 > drivers. Some capabilities are project private, some capabilities are > consolidation private, and some capabilities are part of the stable > interface proposed by this case. In particular, the capabilities being > committed here are defined through the mac_capab_t enum, and are > listed below. > > MAC_CAPAB_HCKSUM Hardware checksum offload > > Detailed information about this capability is > passed from the driver to the stack as part of > the capability query by setting a combination > of the following flags. > > - HCKSUM_INET_PARTIAL > - HCKSUM_INET_FULL_V4 > - HCKSUM_INET_FULL_V6 > - HCKSUM_IPHDRCKSUM > > Checksum offload meta-data is queried and set > through the mac_hcksum_get(9F) and > mac_hcksum_set(9F), respectively. > > MAC_CAPAB_LSO Large Segment (or Send) Offload > > Detailed information about the capability is > passed during capability through the > mac_capab_lso_t structure which consists of a > structure of type lso_basic_tcp_ipv4_t, and a > scalar value. > > Per-packet LSO meta-data can be obtained by > driver using the mac_lso_get(9F) entry point. > > Capabilities are queried through the mc_getcapab entry point which is > specified through the mac_callback(9S) structure. If a capability is > supported by the driver, it passes information about that capability, > such as capability-specific entry points, flags, etc, through the > mc_getcapab entry point. > > These capabilities and associated data structures and definitions are > described in details in [mac-9e.txt] > > Control Operations > ================== > > The driver is controlled by the MAC layer using the driver entry > points exposed through the mac_callback structure, see above, as well > as mac_callbacks-9s.txt. > > The control entry points are exposed by drivers, these entry points > are described in details in mac-9e.txt. > > mc_start Start a driver instance. This entry point > is invoked by the framework before > any operation is attempted. > > mc_stop Stop a driver instance. > > mc_setpromisc Set the promiscuous mode of a driver > instance. > > mc_multicst Add or remove a multicast address > > mc_unicst Set by the driver to change the primary > MAC address of the driver instance. > > mc_ioctl Optional ioctl entry point. > > mc_setprop Set a property value. > > mc_getprop Get a property value. > > mc_propinfo Get information about a property > > > Data Path > ========= > > Data-path entry points consist of callbacks exported by the driver and > invoked by the framework for sending packets, and framework entry > points called by the driver for transmit flow control and receiving > packets. > > Transmit Data Path > ------------------ > > The drivers expose a transmit entry point mc_tx through the callback > data-structure, see the Registration section above, and [mac-9e.txt] for > details. The transmit entry point is passed a chain of one or more > packets linked in a list of mblk_t's. > > - Flow control: > > If the driver cannot send the packets due to a lack of hardware > resources, it returns the sub-chain of packets that could not be > sent. When more descriptors become available at a later time, the > driver must notify the framework by invoking mac_tx_update() > [mac-9f.txt] > > - Hardware checksumming: > > If the driver advertised hardware checksum capabilities, it is > responsible to check every packet for hardware checksum meta-data by > invoking mac_hcksum_get(9F), and program the hardware to perform the > required checksum calculation [hcksum_retrieve-9f.txt] > > - LSO: > > If the driver advertised LSO capabilities, it is responsible to check > every packet for LSO meta-data using the mac_lso_get(9F) entry point, > and programming the hardware to segment the large segment into smaller > packets [mac_lso_get-9f.txt] > > - VLANs: > > When VLANs are configured by the administrator using VLAN or VNIC data > links, the MAC layer inserts the needed VLAN headers on the outbound > packets before they are passed to the driver via the m_tx entry point. > > Receive Data Path > ----------------- > > The device driver passes up received packets to the stack by passing > the received packets as chains through mac_rx() [mac-9f.txt] > > - Hardware checksumming > > If the driver supports, hardware checksumming, it must invoke the > mac_hcksum_set(9F) entry point to associate hardware checksumming > meta-data to the packet. [hcksum_retrieve-9f.txt] > > - VLANs: > > VLAN packets must be passed with their tags to the MAC layer. The > driver should not strip the VLAN headers from the packets. > > Notifications > ============= > > The following functions can be invoke by a driver to notify the > network stack that its state has changed: > > - mac_tx_update(9F) Invoked to notify the framework that > more TX descriptors are available. > [mac-9f.txt] > > - mac_link_update(9F) Invoked to notify the framework that > the state of the link has changed. > [mac-9f.txt] > > Statistics > ========== > > Device drivers are expected to maintain a set of statistics for the > device instances they manage. These statistics are queried by the MAC > layer by invoking the mc_getstat entry point of the mc_getstat entry > point of the driver [mac-9e.txt] > > The GLD statistics supported are the union of generic MAC statistics, > and Ethernet-specific statistics that are common across Nevada and > S10. > > Properties > ========== > > Brussels properties, first introduced by PSARC/2007/429, are part of > the committed GLDv3 interface. In order to simplify the driver > interface, and to address issues with Brussels extension > PSARC/2009/235 (dladm Possible Values List), which cannot be promoted > to committed interface due to architectural issues, the driver > properties interface are revisited as part of this case. > > More specifically, a new driver entry point, mc_propinfo, is > introduced, and used by the driver to return immutable information > about a property. This information includes permissions, default > values, and allowed value ranges. The mc_getprop interface can be > simplified because it can focus on returning the current value of a > property. The new mc_propinfo interface is easily extensible while > preserving backward compatibility. These updated properties interfaces > are described in details in [mac-9e.txt] and > [mac_prop_info_set_perm-9f.txt] > > The driver is also able to expose private properties. As defined by > Brussels NDD compatiblity support (SPARC/2008/171), private properties > were passed by the driver to the framework during registration using > the m_priv_props and m_priv_prop_count fields of the mac_register_t > structure. m_priv_prop was defined as an array of mac_priv_prop_t > elements, which included the name and permission for each private > property. > > Because property permissions can be provided by the mc_propinfo() > entry point, m_priv_props can be simplified to be an array of strings > containing property names. The list can be NULL-terminated, allowing > the removal of the m_priv_prop_count field. m_priv_propos field is > defined in [mac_register-9s.txt] > > Interface Table > =============== > > Exported Interfaces > > Interface Name Classification Comments > --------------------------------------------------------------------------- > mac_alloc(9F) Committed Allocate a mac_register_t > mac_free(9F) Committed Free a mac_register_t > mac_register(9F) Committed Register with MAC layer > mac_unregister(9F) Committed Unregister from MAC layer > mac_rx(9F) Committed Pass up received packet(s) > mac_tx_update(9F) Committed TX resources are available > mac_link_update(9F) Committed Link state has changed > mac_hcksum_get(9F) Committed Retrieve HW checksum info > mac_hcksum_set(9F) Committed Attach HW checksum info > mac_lso_get(9F) Committed Retrieve LSO info > > mc_getstat(9E) Committed Retrieve stats from driver > mc_start(9E) Committed Start driver instance > mc_stop(9E) Committed Stop driver instance > mc_setpromisc(9E) Committed Set promiscuous mode > mc_multicst(9E) Committed Add or remove mcast address > mc_unicst(9E) Committed Set primary unicast address > mc_tx(9E) Committed Send one or more packets > mc_ioctl(9E) Committed ioctl driver interface > mc_getcapab(9E) Committed Retrieve capabilities > > mac_register_t(9S) Committed Registration information > mac_callback_t(9S) Committed Driver callbacks > mac_capab_lso_t(9S) Committed LSO meta-data > lso_basic_tcp_ipv4_t(9S) Committed LSO meta-data for TCP/IPv4 > > mac_prop_info_set_perm(9F) Committed Set permission of a property > mac_prop_info_set_default_*(9F) Committed Set property value > mac_prop_info_set_range_*(9F) Committed Set property values range > > MAC_VERSION_V1 Committed Committed interface version > MC_IOCTL Committed mc_ioctl present > MC_GETCAPAB Committed mc_getcapab present > MAC_CAPAB_HCKSUM Committed HW checksumming capability > MAC_CAPAB_LSO Committed LSO capability > MAC_HCKSUM_INET_PARTIAL Committed HW cksum partial offload > MAC_HCKSUM_INET_FULL_V4 Committed HW cksum IPv4 full offload > MAC_HCKSUM_INET_FULL_V6 Committed HW cksum IPv6 full offload > MAC_HCKSUM_IPHDRCKSUM Committed HW IP hdr cksum offload > > These interfaces are defined in more details in the man pages found > in the man/ materials sub-directory. The man/README.txt file contains > an index of the man page drafts and the interfaces they describe. > > Release Binding > =============== > > Patch > > Files and Packages > ================== > > The following files will be delivered as part of the package SUNWhea: > > /usr/include/sys/mac.h > /usr/include/sys/mac_provider.h > /usr/include/sys/mac_ether.h > > References > ========== > > PSARC/2004/571 - Nemo - x86 Network Driver Enhancements > PSARC/2005/207 - Clearview for Nemo > PSARC/2005/365 - Nemo drivers interface simplification > PSARC/2006/248 - Nemo MAC-Type Plugin Architecture > PSARC/2006/249 - Nemo Changes for Binary Compatibility > PSARC/2006/357 - Crossbow - Network Virtualization and Resource Management > PSARC/2007/429 - Brussels - enhanced network driver configuration > PSARC/2008/171 - Brussels: NDD compatiblity support > PSARC/2008/222 - Brussels persistence > > 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 > > From Nicolas.Droux@Sun.COM Fri Nov 20 14:29:33 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAKMTXGI003612 for ; Fri, 20 Nov 2009 14:29:33 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail3mpk.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nAKMTXxF003592 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Fri, 20 Nov 2009 14:29:33 -0800 (PST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTF00K01IH9R100@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 14:29:33 -0800 (PST) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTF00AC7IH84Y80@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 14:29:33 -0800 (PST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAKMTW6k015758 for ; Fri, 20 Nov 2009 22:29:32 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTF00000I95IJ00@mail-amer.sun.com> for PSARC-ext@Sun.Com (ORCPT PSARC-ext@Sun.Com); Fri, 20 Nov 2009 15:29:32 -0700 (MST) Received: from [129.146.227.50] ([unknown] [129.146.227.50]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTF00LD8IH07TE0@mail-amer.sun.com>; Fri, 20 Nov 2009 15:29:24 -0700 (MST) Date: Fri, 20 Nov 2009 14:29:06 -0800 From: Nicolas Droux Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <4B0701EF.9080902@sun.com> Sender: Nicolas.Droux@Sun.COM To: "Garrett D'Amore" Cc: James Walker , PSARC-ext@Sun.COM Message-id: <4B071832.6010106@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <4B0701EF.9080902@sun.com> User-Agent: Thunderbird 2.0.0.23 (X11/20090929) Status: RO Content-Length: 17562 Garrett D'Amore wrote: > +1. Thanks. > > Is it the project teams intention to backport the LSO support to S10 as > well? LSO support is already in Solaris 10. Nicolas. > > - Garrett > > James Walker wrote: >> I'm sponsoring this case for Nicolas Droux. The man pages and header >> files >> are located in the materials directory. This case is requesting a patch >> binding. >> >> Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI >> This information is Copyright 2009 Sun Microsystems >> 1. Introduction >> 1.1. Project/Component Working Name: >> Public GLDv3 Interfaces >> 1.2. Name of Document Author/Supplier: >> Author: Nicolas Droux >> 1.3 Date of This Document: >> 19 November, 2009 >> 4. Technical Description >> >> Introduction >> ============ >> >> The GLDv3 (Generic Lan Driver version 3) provider API was first >> introduced as part of the Nemo project (PSARC/2004/571). The API was >> initially a project-private API and was later promoted to a >> consolidation private API within the ON consolidation >> (PSARC/2005/396.) >> >> These APIs were kept consolidation private to gain experience with the >> APIs, and in anticipation of other projects which were planning to >> extend the APIs, for example Crossbow (PSARC 2006/357). >> >> This effort commits a core subset of the GLDv3 provider APIs for use >> by Ethernet drivers outside of the ON consolidation. This subset does >> not include advanced features such as hardware classification or >> polling, which are exposed through capabilities. In the future these >> capabilities may be promoted to committed interfaces as they mature >> and stabilize. >> >> Note that this case defines a stable driver API only for Ethernet >> drivers, i.e. drivers registering with a plugin type of >> MAC_PLUGIN_IDENT_ETHER. >> >> GLDv3 Provider Interface Overview >> ================================= >> >> The GLDv3 driver API is a function calls-based interface (in contrast >> to a STREAMs-based interface), which is designed for extensibility, >> and for high performance. >> >> The interface consist of a set of driver entry points which are >> advertised during registration with the MAC layer, a set of MAC entry >> points which are invoked by drivers, and a set of capabilities which >> are used for advanced features. >> >> Driver related structures are defined in the header file >> header file. The driver should not include any >> other MAC-related header file. >> >> Registration >> ============ >> >> A GLDv3 device driver calls mac_register(9F) to register a new >> instance with the framework. mac_register(9F) is typically called from >> the attach(9E) entry point implemented by the device driver. >> mac_register(9F) must be passed as input a pointer to a >> mac_register(9S) structure. >> >> The registration information structure mac_register(9S) must be >> allocated through a call to mac_alloc(9F). mac_alloc(9F) takes as >> argument a version number, that version must be set to MAC_VERSION_V1 >> which is the version described by this document. >> >> Note: the version MAC_VERSION_V1 must be specified by drivers which >> implement the API described by this document. If new versions of the >> API are defined in the future, the version number will be incremented, >> and the GLDv3 framework may support one or more versions of the >> APIs. Having a specific MAC_VERSION_V1, instead of always using, for >> example, MAC_VERSION which contains the latest version number, will >> allow unbundled drivers to be compiled on an ON build which support >> more than one versions of the API. >> >> The entry points and data structures used during MAC registration are >> summarized below. When applicable, a reference to the file which >> contains a detailed description of the function or data structure is >> provided. >> >> extern mac_register_t *mac_alloc(uint_t version); >> >> Allocates a new structure of type mac_register_t, which >> can be subsequently be passed to mac_register(9F). >> The version argument must be set to MAC_VERSION_V1. [mac-9f.txt] >> >> extern int mac_register(mac_register_t *, mac_handle_t *); >> >> Registers a new GLDv3 MAC instance with the MAC layer. >> This entry point is typically invoked from the >> attach(9E) entry point of a physical NIC device driver, >> or when a pseudo MAC instance is created. >> >> Note: the public GLDv3 interface only supports physical >> GLDv3 devices. Creating pseudo devices require the use of other >> dls kernel entry points and exchange of link ids which for now >> are staying consolidation-private. [mac-9f.txt] >> >> extern int mac_unregister(mac_handle_t); >> >> Unregisters a MAC instance which was previously registered >> with mac_register(9F). [mac-9f.txt] >> >> typedef struct mac_register_s mac_register_t; >> >> MAC registration structure. Allocated by mac_alloc(9F) >> and passed to mac_register(9F). [mac_register-9s.txt] >> >> typedef struct mac_callbacks_s mac_callbacks_t; >> >> A pointer to a structure of type mac_callback_t is passed >> using the m_callbacks field of the mac_register_t structure. >> The mac_callbacks_t data-structure allows the driver to expose >> its entry points to the MAC layer. These entry points are used >> to start/stop the adapters, manage multicast addresses, set >> promiscuous mode, query the capabilities of the adapter, get >> and set properties, and so forth. >> >> The mac_callback_t data-structure contains a mc_callbacks >> bit-mask which allows data-structure to support new >> entry points in the future, while maintaining >> backward-compatibility. >> >> mc_callback can be a combination of the flags MC_IOCTL, >> MC_GETCAPAB, MC_SETPROP, MC_GETPROP, and >> MC_PROPINFO [mac_callbacks-9s.txt] >> >> Capabilities >> ============ >> >> GLDv3 implements a capability mechanism which allows the framework to >> query and enable capabilities which may not be supported by all GLDv3 >> drivers. Some capabilities are project private, some capabilities are >> consolidation private, and some capabilities are part of the stable >> interface proposed by this case. In particular, the capabilities being >> committed here are defined through the mac_capab_t enum, and are >> listed below. >> >> MAC_CAPAB_HCKSUM Hardware checksum offload >> >> Detailed information about this capability is >> passed from the driver to the stack as part of >> the capability query by setting a combination >> of the following flags. >> >> - HCKSUM_INET_PARTIAL >> - HCKSUM_INET_FULL_V4 >> - HCKSUM_INET_FULL_V6 >> - HCKSUM_IPHDRCKSUM >> >> Checksum offload meta-data is queried and set >> through the mac_hcksum_get(9F) and >> mac_hcksum_set(9F), respectively. >> >> MAC_CAPAB_LSO Large Segment (or Send) Offload >> >> Detailed information about the capability is >> passed during capability through the >> mac_capab_lso_t structure which consists of a >> structure of type lso_basic_tcp_ipv4_t, and a >> scalar value. >> >> Per-packet LSO meta-data can be obtained by >> driver using the mac_lso_get(9F) entry point. >> >> Capabilities are queried through the mc_getcapab entry point which is >> specified through the mac_callback(9S) structure. If a capability is >> supported by the driver, it passes information about that capability, >> such as capability-specific entry points, flags, etc, through the >> mc_getcapab entry point. >> >> These capabilities and associated data structures and definitions are >> described in details in [mac-9e.txt] >> >> Control Operations >> ================== >> >> The driver is controlled by the MAC layer using the driver entry >> points exposed through the mac_callback structure, see above, as well >> as mac_callbacks-9s.txt. >> >> The control entry points are exposed by drivers, these entry points >> are described in details in mac-9e.txt. >> >> mc_start Start a driver instance. This entry point >> is invoked by the framework before >> any operation is attempted. >> >> mc_stop Stop a driver instance. >> >> mc_setpromisc Set the promiscuous mode of a driver >> instance. >> >> mc_multicst Add or remove a multicast address >> >> mc_unicst Set by the driver to change the primary >> MAC address of the driver instance. >> >> mc_ioctl Optional ioctl entry point. >> >> mc_setprop Set a property value. >> >> mc_getprop Get a property value. >> >> mc_propinfo Get information about a property >> >> >> Data Path >> ========= >> >> Data-path entry points consist of callbacks exported by the driver and >> invoked by the framework for sending packets, and framework entry >> points called by the driver for transmit flow control and receiving >> packets. >> >> Transmit Data Path >> ------------------ >> >> The drivers expose a transmit entry point mc_tx through the callback >> data-structure, see the Registration section above, and [mac-9e.txt] for >> details. The transmit entry point is passed a chain of one or more >> packets linked in a list of mblk_t's. >> >> - Flow control: >> >> If the driver cannot send the packets due to a lack of hardware >> resources, it returns the sub-chain of packets that could not be >> sent. When more descriptors become available at a later time, the >> driver must notify the framework by invoking mac_tx_update() >> [mac-9f.txt] >> >> - Hardware checksumming: >> >> If the driver advertised hardware checksum capabilities, it is >> responsible to check every packet for hardware checksum meta-data by >> invoking mac_hcksum_get(9F), and program the hardware to perform the >> required checksum calculation [hcksum_retrieve-9f.txt] >> >> - LSO: >> >> If the driver advertised LSO capabilities, it is responsible to check >> every packet for LSO meta-data using the mac_lso_get(9F) entry point, >> and programming the hardware to segment the large segment into smaller >> packets [mac_lso_get-9f.txt] >> >> - VLANs: >> >> When VLANs are configured by the administrator using VLAN or VNIC data >> links, the MAC layer inserts the needed VLAN headers on the outbound >> packets before they are passed to the driver via the m_tx entry point. >> >> Receive Data Path >> ----------------- >> >> The device driver passes up received packets to the stack by passing >> the received packets as chains through mac_rx() [mac-9f.txt] >> >> - Hardware checksumming >> >> If the driver supports, hardware checksumming, it must invoke the >> mac_hcksum_set(9F) entry point to associate hardware checksumming >> meta-data to the packet. [hcksum_retrieve-9f.txt] >> >> - VLANs: >> >> VLAN packets must be passed with their tags to the MAC layer. The >> driver should not strip the VLAN headers from the packets. >> >> Notifications >> ============= >> >> The following functions can be invoke by a driver to notify the >> network stack that its state has changed: >> >> - mac_tx_update(9F) Invoked to notify the framework that >> more TX descriptors are available. >> [mac-9f.txt] >> >> - mac_link_update(9F) Invoked to notify the framework that >> the state of the link has changed. >> [mac-9f.txt] >> >> Statistics >> ========== >> >> Device drivers are expected to maintain a set of statistics for the >> device instances they manage. These statistics are queried by the MAC >> layer by invoking the mc_getstat entry point of the mc_getstat entry >> point of the driver [mac-9e.txt] >> >> The GLD statistics supported are the union of generic MAC statistics, >> and Ethernet-specific statistics that are common across Nevada and >> S10. >> >> Properties >> ========== >> >> Brussels properties, first introduced by PSARC/2007/429, are part of >> the committed GLDv3 interface. In order to simplify the driver >> interface, and to address issues with Brussels extension >> PSARC/2009/235 (dladm Possible Values List), which cannot be promoted >> to committed interface due to architectural issues, the driver >> properties interface are revisited as part of this case. >> >> More specifically, a new driver entry point, mc_propinfo, is >> introduced, and used by the driver to return immutable information >> about a property. This information includes permissions, default >> values, and allowed value ranges. The mc_getprop interface can be >> simplified because it can focus on returning the current value of a >> property. The new mc_propinfo interface is easily extensible while >> preserving backward compatibility. These updated properties interfaces >> are described in details in [mac-9e.txt] and >> [mac_prop_info_set_perm-9f.txt] >> >> The driver is also able to expose private properties. As defined by >> Brussels NDD compatiblity support (SPARC/2008/171), private properties >> were passed by the driver to the framework during registration using >> the m_priv_props and m_priv_prop_count fields of the mac_register_t >> structure. m_priv_prop was defined as an array of mac_priv_prop_t >> elements, which included the name and permission for each private >> property. >> >> Because property permissions can be provided by the mc_propinfo() >> entry point, m_priv_props can be simplified to be an array of strings >> containing property names. The list can be NULL-terminated, allowing >> the removal of the m_priv_prop_count field. m_priv_propos field is >> defined in [mac_register-9s.txt] >> >> Interface Table >> =============== >> >> Exported Interfaces >> >> Interface Name Classification Comments >> --------------------------------------------------------------------------- >> >> mac_alloc(9F) Committed Allocate a mac_register_t >> mac_free(9F) Committed Free a mac_register_t >> mac_register(9F) Committed Register with MAC layer >> mac_unregister(9F) Committed Unregister from MAC layer >> mac_rx(9F) Committed Pass up received packet(s) >> mac_tx_update(9F) Committed TX resources are available >> mac_link_update(9F) Committed Link state has changed >> mac_hcksum_get(9F) Committed Retrieve HW checksum info >> mac_hcksum_set(9F) Committed Attach HW checksum info >> mac_lso_get(9F) Committed Retrieve LSO info >> >> mc_getstat(9E) Committed Retrieve stats from driver >> mc_start(9E) Committed Start driver instance >> mc_stop(9E) Committed Stop driver instance >> mc_setpromisc(9E) Committed Set promiscuous mode >> mc_multicst(9E) Committed Add or remove mcast address >> mc_unicst(9E) Committed Set primary unicast address >> mc_tx(9E) Committed Send one or more packets >> mc_ioctl(9E) Committed ioctl driver interface >> mc_getcapab(9E) Committed Retrieve capabilities >> >> mac_register_t(9S) Committed Registration information >> mac_callback_t(9S) Committed Driver callbacks >> mac_capab_lso_t(9S) Committed LSO meta-data >> lso_basic_tcp_ipv4_t(9S) Committed LSO meta-data for TCP/IPv4 >> >> mac_prop_info_set_perm(9F) Committed Set permission of a property >> mac_prop_info_set_default_*(9F) Committed Set property value >> mac_prop_info_set_range_*(9F) Committed Set property values range >> >> MAC_VERSION_V1 Committed Committed interface version >> MC_IOCTL Committed mc_ioctl present >> MC_GETCAPAB Committed mc_getcapab present >> MAC_CAPAB_HCKSUM Committed HW checksumming capability >> MAC_CAPAB_LSO Committed LSO capability >> MAC_HCKSUM_INET_PARTIAL Committed HW cksum partial offload >> MAC_HCKSUM_INET_FULL_V4 Committed HW cksum IPv4 full offload >> MAC_HCKSUM_INET_FULL_V6 Committed HW cksum IPv6 full offload >> MAC_HCKSUM_IPHDRCKSUM Committed HW IP hdr cksum offload >> >> These interfaces are defined in more details in the man pages found >> in the man/ materials sub-directory. The man/README.txt file contains >> an index of the man page drafts and the interfaces they describe. >> >> Release Binding >> =============== >> >> Patch >> >> Files and Packages >> ================== >> >> The following files will be delivered as part of the package SUNWhea: >> >> /usr/include/sys/mac.h >> /usr/include/sys/mac_provider.h >> /usr/include/sys/mac_ether.h >> >> References >> ========== >> >> PSARC/2004/571 - Nemo - x86 Network Driver Enhancements >> PSARC/2005/207 - Clearview for Nemo >> PSARC/2005/365 - Nemo drivers interface simplification >> PSARC/2006/248 - Nemo MAC-Type Plugin Architecture >> PSARC/2006/249 - Nemo Changes for Binary Compatibility >> PSARC/2006/357 - Crossbow - Network Virtualization and Resource >> Management >> PSARC/2007/429 - Brussels - enhanced network driver configuration >> PSARC/2008/171 - Brussels: NDD compatiblity support >> PSARC/2008/222 - Brussels persistence >> >> 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 >> >> > From Kais.Belgaied@Sun.COM Sat Nov 21 17:56:33 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAM1uXL3010325 for ; Sat, 21 Nov 2009 17:56:33 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nAM1uWVP011345; Sat, 21 Nov 2009 17:56:32 -0800 (PST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTH00301MQ8Z400@nwk-avmta-2.sfbay.sun.com>; Sat, 21 Nov 2009 17:56:32 -0800 (PST) Received: from jurassic-x4600.sfbay.sun.com ([129.146.17.63]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTH00EIZMQ88F50@nwk-avmta-2.sfbay.sun.com>; Sat, 21 Nov 2009 17:56:32 -0800 (PST) Received: from [129.146.11.144] (sr1-jurassic-01.SFBay.Sun.COM [129.146.11.144]) by jurassic-x4600.sfbay.sun.com (8.14.3+Sun/8.14.3) with ESMTP id nAM1uQGa330771 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 21 Nov 2009 17:56:27 -0800 (PST) Date: Sat, 21 Nov 2009 17:56:30 -0800 From: Kais Belgaied Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <4B06ED29.8080002@sun.com> To: Nicolas Droux Cc: Sebastien Roy , James Walker , PSARC-ext@Sun.COM Message-id: <4B089A4E.7070505@Sun.COM> MIME-version: 1.0 Content-type: text/plain; charset=ISO-8859-1; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> User-Agent: Thunderbird 2.0.0.23 (X11/20090910) Status: RO Content-Length: 734 +1 Kais On 11/20/09 11:25, Nicolas Droux wrote: > Seb, > > My intent is to include this entry point as part of the GLDv3 APIs > being committed. It is documented it in the mac(9F) man page draft [1], > but I did not list it in the overview. I will update the spec to list > it there as well. > > Nicolas. > > [1] Available in the materials for the case, see > http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/mac-9f.txt > > > > Sebastien Roy wrote: >> I haven't reviewed the materials fully yet, but a quick string search of >> the spec doesn't turn up any references to mac_init_ops(), and this >> function must be called in drivers' _init() routines. This may have >> been an oversight. >> >> -Seb >> >> > From Nicolas.Droux@Sun.COM Mon Nov 23 13:41:26 2009 Received: from sunmail6brm.central.sun.com (sunmail6brm.Central.Sun.COM [129.147.4.169]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nANLfQr3012150 for ; Mon, 23 Nov 2009 13:41:26 -0800 (PST) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail6brm.central.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nANLfPoE019116 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Mon, 23 Nov 2009 15:41:25 -0600 (CST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTL00K03091K200@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 23 Nov 2009 14:41:25 -0700 (MST) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTL00J8N0914P10@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 23 Nov 2009 14:41:25 -0700 (MST) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nANLfP8H013342 for ; Mon, 23 Nov 2009 21:41:25 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTK00600ZO3G900@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 23 Nov 2009 14:41:25 -0700 (MST) Received: from dhcp-umpk17-226-127.sfbay.sun.com ([unknown] [129.146.226.127]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTL00GDD08X3790@mail-amer.sun.com>; Mon, 23 Nov 2009 14:41:21 -0700 (MST) Date: Mon, 23 Nov 2009 13:41:20 -0800 From: Nicolas Droux Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <4B06ED29.8080002@sun.com> Sender: Nicolas.Droux@Sun.COM To: Nicolas Droux Cc: Sebastien Roy , James Walker , PSARC-ext@Sun.COM Message-id: MIME-version: 1.0 X-Mailer: Apple Mail (2.1077) Content-type: text/plain; CHARSET=US-ASCII Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> Status: RO Content-Length: 928 On Nov 20, 2009, at 11:25 AM, Nicolas Droux wrote: > Seb, > > My intent is to include this entry point as part of the GLDv3 APIs being committed. It is documented it in the mac(9F) man page draft [1], > but I did not list it in the overview. I will update the spec to list it there as well. The updated spec is now online in the case directory (see proposal.txt) Nicolas. > > Nicolas. > > [1] Available in the materials for the case, see > http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/mac-9f.txt > > > Sebastien Roy wrote: >> I haven't reviewed the materials fully yet, but a quick string search of >> the spec doesn't turn up any references to mac_init_ops(), and this >> function must be called in drivers' _init() routines. This may have >> been an oversight. >> -Seb > -- Nicolas Droux - Solaris Kernel Networking - Sun Microsystems, Inc. nicolas.droux@sun.com - http://blogs.sun.com/droux From Sebastien.Roy@Sun.COM Wed Nov 25 07:27:20 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAPFRKQ6012656 for ; Wed, 25 Nov 2009 07:27:20 -0800 (PST) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAPFRIUg064897 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 25 Nov 2009 08:27:20 -0700 (MST) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTO0060J89JJV00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 25 Nov 2009 07:27:19 -0800 (PST) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTO00EN589I0GB0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 25 Nov 2009 07:27:18 -0800 (PST) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAPFRIv3028989 for ; Wed, 25 Nov 2009 15:27:18 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTO00D007MAGQ00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 25 Nov 2009 08:27:18 -0700 (MST) Received: from [192.168.1.5] ([unknown] [173.76.16.34]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTO003MK89F2I50@mail-amer.sun.com>; Wed, 25 Nov 2009 08:27:16 -0700 (MST) Date: Wed, 25 Nov 2009 10:27:14 -0500 From: Sebastien Roy Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: Sender: Sebastien.Roy@Sun.COM To: Nicolas Droux Cc: James Walker , PSARC-ext@Sun.COM Message-id: <1259162834.2336.326.camel@seb> Organization: Sun Microsystems MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> Status: RO Content-Length: 2708 Nicolas, On Mon, 2009-11-23 at 13:41 -0800, Nicolas Droux wrote: > On Nov 20, 2009, at 11:25 AM, Nicolas Droux wrote: > > > Seb, > > > > My intent is to include this entry point as part of the GLDv3 APIs being committed. It is documented it in the mac(9F) man page draft [1], > > but I did not list it in the overview. I will update the spec to list it there as well. > > The updated spec is now online in the case directory (see proposal.txt) Excellently written documentation, +1 on the case. I only have a couple of requests for documentation clarification and minor nits: In proposal.txt: * "A GLDv3 device driver calls mac_register(9F) to register a new instance with the framework. mac_register(9F) is typically called from the attach(9E) entry point implemented by the device driver." In fact, it's not only typical, but for physical devices, mac_register() _must_ be called from attach(9E). Perhaps that needs to be clearly stated in the documentation, because drivers for physical devices that call mac_register() from anywhere but attach() won't work correctly (softmac_hold_device() will break). * Somewhere in the spec and/or documentation, there needs to be a discussion about locking. There is a mention in the mac(9F) man page that drivers should avoid holding locks when calling mac_rx(). Are there additional locking requirements while issuing other upcalls, and/or while handling callbacks? * In mac.c, there is the following comment in the "MAC driver rules" section: * R17 Similarly mi_stop is another synchronization point and the driver must * ensure that all upcalls are done and there won't be any future upcall * before returning from mi_stop. This is likely an important bit of information that driver developers need to know about. More generally, it would be good to go through those rules and ensure that the important parts end up reflected in developer documentation. * Regarding mac_hcksum_get(9F): Where are the definitions of such terms as "full checksum" and "partial checksum" that are used to define what the MAC_HCK_* flags represent? * Regarding mac_hcksum_get(9F), are the MAC_HCK_* flags applicable to both IPv4 and IPv6 (except for MAC_HCK_IPV4_HDRCKSUM_OK, which is obvious)? * Regarding LSO: Are drivers expected to be able to handle transmitted packets with IP options (such as TX labels), or does the framework guarantee that the IP header does not contain options when LSO is enabled? * Typos in mac_prop_info_set_perm-9f.txt: - The man page header refers to mac_lso_get(9F). - "mac_prop_info_set_perm() specifies the property of the property." s/specifies the property/specifies the permissions associated with/ (?). -Seb From Nicolas.Droux@sun.com Wed Nov 25 22:31:56 2009 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAQ6Vu8w009504 for ; Wed, 25 Nov 2009 22:31:56 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id nAQ6VqS6035451 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Wed, 25 Nov 2009 23:31:56 -0700 (MST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTP00M07E4JFQ00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 25 Nov 2009 22:31:31 -0800 (PST) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTP00HSCE4ILM20@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 25 Nov 2009 22:31:31 -0800 (PST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAQ6VUCG004154 for ; Thu, 26 Nov 2009 06:31:30 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTP00900DZJVK00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Wed, 25 Nov 2009 23:31:30 -0700 (MST) Received: from [10.0.0.8] ([unknown] [99.191.74.15]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTP007KRE4AB3A0@mail-amer.sun.com>; Wed, 25 Nov 2009 23:31:30 -0700 (MST) Date: Wed, 25 Nov 2009 22:31:22 -0800 From: Nicolas Droux Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <1259162834.2336.326.camel@seb> Sender: Nicolas.Droux@sun.com To: Sebastien Roy Cc: James Walker , PSARC-ext@sun.com Message-id: <4B0E20BA.4030706@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> <1259162834.2336.326.camel@seb> User-Agent: Thunderbird 2.0.0.23 (X11/20091027) Status: RO Content-Length: 4355 Sebastien Roy wrote: > Nicolas, > > On Mon, 2009-11-23 at 13:41 -0800, Nicolas Droux wrote: >> On Nov 20, 2009, at 11:25 AM, Nicolas Droux wrote: >> >>> Seb, >>> >>> My intent is to include this entry point as part of the GLDv3 APIs being committed. It is documented it in the mac(9F) man page draft [1], >>> but I did not list it in the overview. I will update the spec to list it there as well. >> The updated spec is now online in the case directory (see proposal.txt) > > Excellently written documentation, +1 on the case. I only have a couple > of requests for documentation clarification and minor nits: Seb, Thanks a lot for the thorough review. The updated specs will soon be posted in the case directory. Until then you can find them here: http://zia.sfbay/~nd99603/gldv3_public_psarc > > In proposal.txt: > > * "A GLDv3 device driver calls mac_register(9F) to register a new > instance with the framework. mac_register(9F) is typically called from > the attach(9E) entry point implemented by the device driver." > > In fact, it's not only typical, but for physical devices, mac_register() > _must_ be called from attach(9E). Perhaps that needs to be clearly > stated in the documentation, because drivers for physical devices that > call mac_register() from anywhere but attach() won't work correctly > (softmac_hold_device() will break). OK, fixed. > > > * Somewhere in the spec and/or documentation, there needs to be a > discussion about locking. There is a mention in the mac(9F) man page > that drivers should avoid holding locks when calling mac_rx(). Are > there additional locking requirements while issuing other upcalls, > and/or while handling callbacks? That's the only minimum requirement. Note that I also added a CONTEXT section to the man page describing device drivers entry points. > > > * In mac.c, there is the following comment in the "MAC driver rules" > section: > > * R17 Similarly mi_stop is another synchronization point and the driver must > * ensure that all upcalls are done and there won't be any future upcall > * before returning from mi_stop. > > This is likely an important bit of information that driver developers > need to know about. More generally, it would be good to go through > those rules and ensure that the important parts end up reflected in > developer documentation. OK, good suggestion. I have added the following info to the specs: - Note to mc_stop() in mac-9e.txt from R17 - Added note to mac-9f.txt for R15. - Added note to mac-9e.txt for R18. > > > * Regarding mac_hcksum_get(9F): Where are the definitions of such terms > as "full checksum" and "partial checksum" that are used to define what > the MAC_HCK_* flags represent? I have added a definition of full vs partial checksum to the capabilities section of mac-9e.txt. I have then added a cross-reference to that section from mac_hcksum_get-9f.txt, see first paragraph of the description section. > > * Regarding mac_hcksum_get(9F), are the MAC_HCK_* flags applicable to > both IPv4 and IPv6 (except for MAC_HCK_IPV4_HDRCKSUM_OK, which is > obvious)? Yes, the driver can expose separate capabilities for IPv4 and IPv6 full checksum offload, but the per-packet flags are the same in both cases (except MAC_HCK_IPV4_HDRCKSUM_OK of course). I added a note to mac_hcksum_get-9f.txt to capture this. > > > * Regarding LSO: Are drivers expected to be able to handle transmitted > packets with IP options (such as TX labels), or does the framework > guarantee that the IP header does not contain options when LSO is > enabled? It's the latter, LSO should be in general disabled if an IP option is present, since it's not possible to safely assume that all IP options available today and tomorrow will be handled by the hardware. If we need to relax that limitation in the future, we can use the lso_flags field of the mac_capab_lso_t structure to convey more information on the hardware support with respect to IP options. I have added a corresponding note to mac_lso_get-9f.txt to make this clear. > > > * Typos in mac_prop_info_set_perm-9f.txt: > - The man page header refers to mac_lso_get(9F). > - "mac_prop_info_set_perm() specifies the property of the property." > s/specifies the property/specifies the permissions associated with/ (?). Fixed. Thanks, Nicolas. > > -Seb > > From James.Walker@sun.com Mon Nov 30 09:37:41 2009 Received: from sunmail2sca.sfbay.sun.com (sunmail2sca.SFBay.Sun.COM [129.145.155.234]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAUHbfGt009681 for ; Mon, 30 Nov 2009 09:37:41 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail2sca.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nAUHbftZ016976; Mon, 30 Nov 2009 09:37:41 -0800 (PST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTX0080DNMS0V00@nwk-avmta-2.sfbay.sun.com>; Mon, 30 Nov 2009 09:37:40 -0800 (PST) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTX0012FNMROP90@nwk-avmta-2.sfbay.sun.com>; Mon, 30 Nov 2009 09:37:39 -0800 (PST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAUHbcv9005675; Mon, 30 Nov 2009 17:37:38 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTX00A00MS09E00@mail-amer.sun.com>; Mon, 30 Nov 2009 10:37:38 -0700 (MST) Received: from c-24-8-54-233.hsd1.co.comcast.net ([unknown] [129.150.220.99]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTX00M5FNMIZ4C0@mail-amer.sun.com>; Mon, 30 Nov 2009 10:37:30 -0700 (MST) Date: Mon, 30 Nov 2009 10:37:30 -0700 From: Jim Walker Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <1259162834.2336.326.camel@seb> Sender: James.Walker@sun.com To: Sebastien Roy Cc: "Nicolas Droux"@sun.com, PSARC-ext@sun.com Reply-to: James.Walker@sun.com Message-id: <4B1402DA.1040600@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> <1259162834.2336.326.camel@seb> User-Agent: Thunderbird 2.0.0.23 (Macintosh/20090812) Status: RO Content-Length: 228 The case materials have been updated (diff files showing the changes have been included). This case has received three +1s and the timeout has expired. I plan mark this case closed approved at the end of the day. Cheers, Jim From James.Walker@sun.com Mon Nov 30 09:47:17 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nAUHlGox009785 for ; Mon, 30 Nov 2009 09:47:16 -0800 (PST) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nAUHlCd8020083 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Mon, 30 Nov 2009 09:47:16 -0800 (PST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTX00N0PO2R4L00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 10:47:15 -0700 (MST) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTX00JYNO2HDS10@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 10:47:05 -0700 (MST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nAUHl5bd009784 for ; Mon, 30 Nov 2009 17:47:05 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTX00A00MS09E00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 10:47:05 -0700 (MST) Received: from c-24-8-54-233.hsd1.co.comcast.net ([unknown] [129.150.220.99]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTX00CA1O28ZF00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 10:46:57 -0700 (MST) Date: Mon, 30 Nov 2009 10:46:56 -0700 From: Jim Walker Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <1259162834.2336.326.camel@seb> Sender: James.Walker@sun.com To: Sebastien Roy Cc: Nicolas Droux , PSARC-ext@sun.com Reply-to: James.Walker@sun.com Message-id: <4B140510.5040908@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> <1258737067.10163.84.camel@strat> <4B06ED29.8080002@sun.com> <1259162834.2336.326.camel@seb> User-Agent: Thunderbird 2.0.0.23 (Macintosh/20090812) Status: RO Content-Length: 248 (cleaned up version) The case materials have been updated (diff files showing the changes are included). This case has received three +1s and the timeout has expired. I plan to mark this case closed approved at the end of the day. Cheers, Jim From James.Walker@Sun.COM Mon Nov 30 18:03:45 2009 Received: from sunmail3mpk.sfbay.sun.com (sunmail3mpk.SFBay.Sun.COM [129.146.11.52]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id nB123jDg027192 for ; Mon, 30 Nov 2009 18:03:45 -0800 (PST) Received: from brm-avmta-1.central.sun.com (brm-avmta-1.Central.Sun.COM [129.147.4.11]) by sunmail3mpk.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id nB123j8h007983 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Mon, 30 Nov 2009 18:03:45 -0800 (PST) Received: from pmxchannel-daemon.brm-avmta-1.central.sun.com by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KTY00501B29ZK00@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 19:03:45 -0700 (MST) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by brm-avmta-1.central.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KTY00B75B29WL80@brm-avmta-1.central.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 19:03:45 -0700 (MST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id nB123iO2016434 for ; Tue, 01 Dec 2009 02:03:44 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KTY00600APLRC00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 19:03:44 -0700 (MST) Received: from [172.20.25.153] ([unknown] [172.20.25.153]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KTY00GR7B28EOD0@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 30 Nov 2009 19:03:44 -0700 (MST) Date: Mon, 30 Nov 2009 19:10:57 -0700 From: Jim Walker Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> Sender: James.Walker@Sun.COM To: PSARC-ext@Sun.COM Cc: Nicolas.Droux@Sun.COM Reply-to: James.Walker@Sun.COM Message-id: <4B147B31.9080804@sun.com> Organization: Sun Microsystems, Inc. MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <200911200619.nAK6Jqpd003535@sac.sfbay.sun.com> User-Agent: Thunderbird 2.0.0.14 (X11/20080728) Status: RO Content-Length: 56 This case has been marked closed approved. Cheers, Jim From James.Walker@sun.com Sat Feb 20 08:17:00 2010 Received: from sunmail6brm.central.sun.com (sunmail6brm.Central.Sun.COM [129.147.4.169]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o1KGH0VY025077 for ; Sat, 20 Feb 2010 08:17:00 -0800 (PST) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail6brm.central.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o1KGGx28021890 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Sat, 20 Feb 2010 10:16:59 -0600 (CST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0KY500603EKBAO00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Sat, 20 Feb 2010 08:16:59 -0800 (PST) Received: from brmea-mail-2.sun.com ([192.18.98.43]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0KY500F6JEKBWW70@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Sat, 20 Feb 2010 08:16:59 -0800 (PST) Received: from fe-amer-09.sun.com ([192.18.109.79]) by brmea-mail-2.sun.com (8.13.6+Sun/8.12.9) with ESMTP id o1KGGwwQ010403 for ; Sat, 20 Feb 2010 16:16:58 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0KY500D00EG4BO00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Sat, 20 Feb 2010 09:16:58 -0700 (MST) Received: from c-24-8-151-38.hsd1.co.comcast.net ([unknown] [24.8.151.38]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0KY500343EKAZ8A0@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Sat, 20 Feb 2010 09:16:58 -0700 (MST) Date: Sat, 20 Feb 2010 09:16:58 -0700 From: Jim Walker Subject: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] Sender: James.Walker@sun.com To: PSARC-ext@sun.com Cc: Nicolas Droux Reply-to: James.Walker@sun.com Message-id: <4B800AFA.4090207@sun.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 User-Agent: Thunderbird 2.0.0.23 (Macintosh/20090812) Status: RO Content-Length: 1236 The following minor case updates and corrections have been made: - man page update and cleanup - add MC_PROPERTIES mac_callback flag - rename MAC_HCK_* mac_hcksum flags to HCK_* - add LSO_TX_BASIC_TCP_IPV4 flag to interface table - add MC_* flags to interface table The case materials have been updated at: http://arc.opensolaris.org/caselog/PSARC/2009/638/ The differences are located in the /diffs directories in the *.diff2 files. http://arc.opensolaris.org/caselog/PSARC/2009/638/diffs/proposal.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/diffs/mac_provider.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/README.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/mac-9e.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/mac-9f.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/mac_callbacks-9s.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/mac_hcksum_get-9f.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/mac_lso_get-9f.diff2 http://arc.opensolaris.org/caselog/PSARC/2009/638/materials/man/diffs/mac_prop_info_set_perm-9f.diff2 Cheers, Jim From Nicolas.Droux@sun.com Mon Apr 19 17:54:35 2010 Received: from newsunmail1brm.central.sun.com (newsunmail1brm.Central.Sun.COM [129.147.62.245]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o3K0sUiU020165 for ; Mon, 19 Apr 2010 17:54:35 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by newsunmail1brm.central.sun.com (8.13.7+Sun/8.13.7/ENSMAIL,v2.4) with ESMTP id o3K0sNtd051410 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Mon, 19 Apr 2010 18:54:25 -0600 (MDT) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L1500703H6LLQ00@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 19 Apr 2010 17:54:21 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L1500LQ8H6KL290@nwk-avmta-2.sfbay.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 19 Apr 2010 17:54:20 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id o3K0sKvm003187 for ; Tue, 20 Apr 2010 00:54:20 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0L1500700G9UNH00@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 19 Apr 2010 18:54:20 -0600 (MDT) Received: from [129.146.227.50] ([unknown] [129.146.227.50]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0L15004K2H6JP770@mail-amer.sun.com> for PSARC-ext@sun.com (ORCPT PSARC-ext@sun.com); Mon, 19 Apr 2010 18:54:20 -0600 (MDT) Date: Mon, 19 Apr 2010 17:53:23 -0700 From: Nicolas Droux Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <4B800AFA.4090207@sun.com> Sender: Nicolas.Droux@sun.com To: James.Walker@sun.com Cc: PSARC-ext@sun.com Message-id: <4BCCFB03.3010303@sun.com> MIME-version: 1.0 Content-type: multipart/mixed; boundary="Boundary_(ID_qmRs96ZbnjMpA0PC8qD8aw)" X-PMX-Version: 5.4.1.325704 References: <4B800AFA.4090207@sun.com> User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.9.1.7) Gecko/20100214 Lightning/1.0b1 Thunderbird/3.0.1 Status: RO Content-Length: 5894 This is a multi-part message in MIME format. --Boundary_(ID_qmRs96ZbnjMpA0PC8qD8aw) Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT I'd like to make an additional small update to this case: it was recently suggested that the m_margin flag be part of the committed GLDv3 interfaces to improve source-level compatibility between S10 and Nevada. The changes to the spec are straightforward. I have included the diffs below, and attached a new version of the mac_register(9S) man page draft. I'd prefer if this case could be updated to reflect these changes, instead of filing a separate case. Thanks, Nicolas. *** mac_register-9s.txt.org 2010-04-19 15:14:53.506964153 -0700 --- mac_register-9s.txt 2010-04-19 15:23:35.382018489 -0700 *************** *** 34,39 **** --- 34,40 ---- void *m_pdata; size_t m_pdata_size; mac_priv_prop_t *m_priv_props; + uint32_t m_margin; The following fields of mac_register_t must be set by the device driver before invoking the mac_register(9F) entry point: *************** *** 81,86 **** --- 82,97 ---- m_priv_props Array of Driver-private properties names, terminated by a NULL pointer. + m_margin Drivers set this value to the amount + of data in bytes that the device can + transmit beyond m_max_sdu. For + example, if an Ethernet device can + handle packets whose payload section + is no greater than 1522 bytes and + m_max_sdu is set to 1500 (as + is typical for Ethernet), then + m_margin is set to 22. + DESCRIPTION See mac_register(9F) for more details on the use of these -- Nicolas Droux - Solaris Core OS Engineering - Oracle nicolas.droux@sun.com - (650) 786-7722 17 Network Circle, Menlo Park, CA 94025 --Boundary_(ID_qmRs96ZbnjMpA0PC8qD8aw) Content-type: text/plain; name=mac_register-9s.txt Content-transfer-encoding: 7BIT Content-disposition: attachment; filename=mac_register-9s.txt Data Structures for Drivers mac_register(9S) NAME mac_register - MAC device driver registration data structure SYNOPSIS #include #include INTERFACE LEVEL Solaris architecture specific (Solaris DDI). DESCRIPTION The mac_register data structure is passed by device drivers to the MAC layer when registering using mac_register(9F). STRUCTURE MEMBERS uint_t m_version; /* set by framework */ const char *m_type_ident; void *m_driver; dev_info_t *m_dip; uint_t m_instance; uint8_t *m_src_addr; uint8_t *m_dst_addr; mac_callbacks_t *m_callbacks; uint_t m_min_sdu; uint_t m_max_sdu; void *m_pdata; size_t m_pdata_size; mac_priv_prop_t *m_priv_props; uint32_t m_margin; The following fields of mac_register_t must be set by the device driver before invoking the mac_register(9F) entry point: m_version Set by mac_alloc(9F), device drivers should not modify that field. m_type_ident Must be set to one of the following depending on the type of device being registered. MAC_PLUGIN_IDENT_ETHER Ethernet driver m_driver Driver handle, opaque to the framework, usually points to a per-driver instance data structure. Passed back as argument to driver's entry points invoked by the framework. m_dip Pointer to the driver instance dev_info structure, see attach(9E). m_instance Used by the driver to specify the instance number to be associated with the MAC being registered. This value should always specified by zero. m_src_addr Pointer to the primary MAC address value of the MAC instance. m_dst_addr Pointer to the destination MAC address value of a fixed destination MAC address. This field is optional and should be set to NULL for regular device drivers. m_min_sdu Minimum Service Data Unit size, the minimum packet size, not including the MAC header, that the device can transmit. This can be zero if the device driver can handle any required padding. m_max_sdu Maximum Service Data Unit size, the maximum packet size, not including the MAC header, that can be transmitted by the device. For Ethernet, this number is commonly refered to as the MTU (maximum transmission unit.) m_priv_props Array of Driver-private properties names, terminated by a NULL pointer. m_margin Drivers set this value to the amount of data in bytes that the device can transmit beyond m_max_sdu. For example, if an Ethernet device can handle packets whose payload section is no greater than 1522 bytes and m_max_sdu is set to 1500 (as is typical for Ethernet), then m_margin is set to 22. DESCRIPTION See mac_register(9F) for more details on the use of these various fields. Note that the driver is responsible for allocating the memory pointed to by the fields m_priv_props, m_src_addr, and m_dst_addr. The driver can free this memory if it wishes after the call to mac_register(9F) returns. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWhea | |_____________________________|_____________________________| | Interface Stability | Committed | |_____________________________|_____________________________| SEE ALSO mac_register(9F), attributes(5) --Boundary_(ID_qmRs96ZbnjMpA0PC8qD8aw)-- From jim.walker@oracle.com Tue Apr 20 20:50:15 2010 Received: from sunmail6brm.central.sun.com (sunmail6brm.Central.Sun.COM [129.147.4.169]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id o3L3oFtO006080 for ; Tue, 20 Apr 2010 20:50:15 -0700 (PDT) Received: from nwk-avmta-1.SFBay.Sun.COM (nwk-avmta-1.SFBay.Sun.COM [129.146.11.74]) by sunmail6brm.central.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.4) with ESMTP id o3L3oFor027932 for <@sunmail2sca.sfbay.sun.com:PSARC-ext@sun.com>; Tue, 20 Apr 2010 22:50:15 -0500 (CDT) Received: from pmxchannel-daemon.nwk-avmta-1.sfbay.Sun.COM by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0L1700C39JZRCI00@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Tue, 20 Apr 2010 20:50:15 -0700 (PDT) Received: from brmea-mail-4.sun.com ([192.18.98.36]) by nwk-avmta-1.sfbay.Sun.COM (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0L1700I0NJZP5LC0@nwk-avmta-1.sfbay.Sun.COM> for PSARC-ext@sun.com (ORCPT PSARC-ext@Sun.COM); Tue, 20 Apr 2010 20:50:13 -0700 (PDT) Received: from fe-amer-10.sun.com ([192.18.109.80]) by brmea-mail-4.sun.com (8.13.6+Sun/8.12.9) with ESMTP id o3L3oDAO028963 for ; Wed, 21 Apr 2010 03:50:13 +0000 (GMT) Received: from conversion-daemon.mail-amer.sun.com by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) id <0L1700F00JQKIP00@mail-amer.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Tue, 20 Apr 2010 21:50:13 -0600 (MDT) Received: from c-67-177-236-198.hsd1.co.comcast.net ([unknown] [129.150.177.171]) by mail-amer.sun.com (Sun Java(tm) System Messaging Server 7u2-7.04 64bit (built Jul 2 2009)) with ESMTPSA id <0L1700M3GJZK3P60@mail-amer.sun.com> for PSARC-ext@Sun.COM (ORCPT PSARC-ext@Sun.COM); Tue, 20 Apr 2010 21:50:13 -0600 (MDT) Date: Tue, 20 Apr 2010 21:50:08 -0600 From: Jim Walker Subject: Re: Public GLDv3 Interfaces [PSARC/2009/638 FastTrack timeout 11/26/2009] In-reply-to: <4BCCFB03.3010303@sun.com> Sender: James.Walker@sun.com To: Nicolas Droux Cc: PSARC-ext@sun.com Reply-to: jim.walker@oracle.com Message-id: <4BCE75F0.7010205@oracle.com> MIME-version: 1.0 Content-type: text/plain; CHARSET=US-ASCII; format=flowed Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 References: <4B800AFA.4090207@sun.com> <4BCCFB03.3010303@sun.com> User-Agent: Thunderbird 2.0.0.24 (Macintosh/20100228) Status: RO Content-Length: 663 I agree. It is a minor doc update. I updated the case mac_register-9s.txt man page and saved the diffs. Cheers, Jim Nicolas Droux wrote: >> + uint32_t m_margin; >> >> >> + m_margin Drivers set this value to the amount >> + of data in bytes that the device can >> + transmit beyond m_max_sdu. For >> + example, if an Ethernet device can >> + handle packets whose payload section >> + is no greater than 1522 bytes and >> + m_max_sdu is set to 1500 (as >> + is typical for Ethernet), then >> + m_margin is set to 22. >> +