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
