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 >> <sys/mac_provider.h> 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 >> >> >
