Remote NDIS Specification

Rev 1.1

August 9, 2002

© 1998-2001 Microsoft Corporation. All rights reserved.

Introduction

License Agreement

Concepts and Definitions

Control channel

Data channel

Initialization and Teardown

Device State Definitions

Halt

Reset

Flow Control

Byte Ordering

Encapsulation

Remote NDIS Version

Status Values

Message Set for Connectionless (802.3) Devices

REMOTE_NDIS_INITIALIZE_MSG

REMOTE_NDIS_INITIALIZE_MSG Format

Response to REMOTE_NDIS_INITIALIZE_MSG

REMOTE_NDIS_HALT_MSG

REMOTE_NDIS_QUERY_MSG

REMOTE_NDIS_QUERY_MSG Format

Response to REMOTE_NDIS_QUERY_MSG

REMOTE_NDIS_SET_MSG

REMOTE_NDIS_SET_MSG Format

Response to REMOTE_NDIS_SET_MSG

Setting Device-specific Parameters

REMOTE_NDIS_RESET_MSG

REMOTE_NDIS_RESET_MSG Format

Response to REMOTE_NDIS_RESET_MSG

REMOTE_NDIS_INDICATE_STATUS_MSG

REMOTE_NDIS_INDICATE_STATUS_MSG Format

REMOTE_NDIS_KEEPALIVE_MSG

REMOTE_NDIS_KEEPALIVE_MSG Format

Response to REMOTE_NDIS_KEEPALIVE_MSG

Example Connectionless (802.3) Initialization Sequence

Data Messages (REMOTE_NDIS_PACKET_MSG)

REMOTE_NDIS_PACKET_MSG Format

Multi-Packet Transfers

Required NDIS OIDs

General OIDs

802.3 OIDs

Optional Power Management OIDs

Network Wake-Up

Remote NDIS to USB Mapping

Related Specifications

Overview

PnP and USB-level initialization

USB Device Descriptor

USB Configuration Descriptor

Communication Class Interface

Data Class Interface

USB-level termination

Control channel characteristics

Data channel characteristics

USB Short Packets

Flow Control

Power management

Timer constants

Remote NDIS is a bus-independent class specification for Ethernet (802.3) network devices on dynamic PnP busses such as USB, 1394, BlueTooth, and InfiniBand. This specification defines a bus-independent message protocol between a host PC and a Remote NDIS device over abstract control and data channels. Also included are bus-mapping chapters which define specific features of the specification on the respective busses.

The "legacy-free" PC revolution is eliminating not only legacy connection ports (e.g. serial, parallel, PS/2) but also legacy expansion buses like ISA and PCI in mainstream PCs. The resulting "sealed case" PCs will require either built-in networking support on the motherboard or support for network adapters on external busses. This specification defines a message protocol for external bus attached network devices. It is precise enough to allow vendor-independent class driver support for Remote NDIS devices on the host PC.

Remote NDIS is a fairly simple extension of the well-understood and time-tested NDIS architecture. NDIS defines a function-call interface for device-specific NDIS miniport drivers. This interface defines primitives to send and receive network data, and to query and set configuration parameters and statistics. Remote NDIS leverages NDIS by defining a message wrapping for the NDIS miniport interface, thus moving the NDIS-handling code from a miniport driver into the device itself. In this and other ways, the Remote NDIS specification allows for a wide range of device functionality and performance levels.

License Agreement

The Remote NDIS Specification and any accompanying materials (the "Specification") provided by Microsoft is for your personal use only, and may be used solely for the purpose of implementing the Remote NDIS protocol message set to interface with (i) a Microsoft Windows operating system or (ii) a bus or network-connected communications device, such as a USB, 1394 or TCP/IP device. THE SPECIFICATION MAY NOT BE COPIED OR DISTRIBUTED.

Microsoft may have copyrights, patents or pending patent applications covering subject matter in the Specification. To the extent Microsoft has such copyrights, patents or applications, Microsoft agrees to grant a nonexclusive, royalty-free, world-wide license under these copyrights, patents or applications solely to implement the Remote NDIS Specification to interface with (i) a Microsoft Windows operating system or (ii) a bus or network-connected communications device, such as a USB, 1394 or TCP/IP device, on condition that you agree not to assert any intellectual property rights against Microsoft or other companies for their implementation of the Specification. Microsoft reserves all other rights it may have in the Specification. The furnishing of this document does not give you any license to any other Microsoft patents, trademarks, copyrights, or other intellectual property rights. Specifically, neither this document nor the Specification give you any license to the NDIS Specification or to USB Communication Device Class technology.

The Specification is provided "AS IS" without warranty of any kind. To the maximum extent permitted by applicable law, Microsoft further disclaims all warranties, including without limitation any implied warranties of merchantability and fitness for a particular purpose, as well as warranties of title and noninfringement. The entire risk arising out of the use or performance of the Specification remains with you.

To the maximum extent permitted by applicable law, in no event shall Microsoft or its suppliers be liable for any consequential, incidental, direct, indirect, special, punitive, or other damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the Specification, even if Microsoft has been advised of the possibility of such damages. Because some states/jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, the above limitation may not apply to you.

This section discusses requirements and characteristics of the channels used to communicate between the host and the remote device. Device state transitions and major operations such as initialization, halt and reset are also defined here.

Control channel

The specifics of the control channel are given in the appropriate bus-mapping chapter. The control channel must be reliable and ensure sequenced delivery. It is used for all communication except for the transmission of network data packets. All required control messages except REMOTE_NDIS_HALT and REMOTE_NDIS_INDICATE_STATUS_MSG are request/response exchanges initiated by the host. The device must respond within the ControlTimeoutPeriod as specified in the appropriate bus-mapping chapter.

Data channel

The specifics of the data channel are given in the appropriate bus-mapping chapter. The data channel is used exclusively for the transmission of network data packets. It may consist of multiple sub-channels (e.g. for varying quality of service) as defined in the appropriate bus-mapping chapter. The reliability and delivery specifics of the data channel are likewise defined in the respective bus-mapping chapter.

Initialization and Teardown

The control and data channels are initialized as specified in the respective bus-mapping chapter. The host and Remote NDIS device then exchange initialization messages. The host sends REMOTE_NDIS_INITIALIZE_MSG to the device, and the device provides information about its type, supported medium and version in the response message REMOTE_NDIS_INITIALIZE_CMPLT.

Either the host or the remote device can halt the network connection in an abortive fashion via the REMOTE_NDIS_HALT_MSG message. All outstanding requests and packets should be discarded on receipt of this message.

Device State Definitions

Following bus-level initialization, the device is in the rndis-uninitialized state. Upon receiving REMOTE_NDIS_INITIALIZE_MSG and returning REMOTE_NDIS_INITIALIZE_CMPLT with status success, the device enters the rndis-initialized state.

Upon receiving REMOTE_NDIS_SET_MSG for the OID_GEN_CURRENT_PACKET_FILTER parameter with a non-zero filter, the device e 23223s1821x nters the rndis-data-initialized state. When in the rndis-data-initialized state, receiving REMOTE_NDIS_SET_MSG for OID_GEN_CURRENT_PACKET_FILTER with a zero filter value forces the device back into the rndis-initialized state.

Receiving REMOTE_NDIS_HALT_MSG or a bus-level disconnect or hard-reset at any time forces the device into the rndis-uninitialized state.

Halt

At any time that the device is in the rndis-initialized or rndis-data-initialized state, the host computer may terminate the Remote NDIS functionality of the device in an abortive fashion by sending REMOTE_NDIS_HALT_MSG to the device.

Reset

The communication channel is "soft-reset" when an error such as message timeout occurs. The host may initiate a soft-reset at any time when the device is in the rndis_initialized state by sending REMOTE_NDIS_RESET_MSG to the device (see details below); and the device must send a response message when it has completed the reset. For example, the host may initiate a soft-reset when an error, such as a message timeout has occurred.

Note that this is a soft reset in the sense that any handles (e.g. VCs for connection-oriented devices) continue to be valid after the reset. The Remote NDIS device, as part of the reset process, discards all outstanding requests and packets. The remote device may reset some of its hardware components, but keeps all communication channels to the host intact.

Hard Reset

If the Remote NDIS device performs a hard reset (i.e. reboot), this event is assumed to be equivalent of "Remove" followed by "Add" plug-and-play events. The host NDIS mini-port will be halted and removed, and a new instance will be added and started. All bus-level and Remote NDIS initialization will be re-executed. A Remote NDIS device may hard-reset itself in the event of a critical device failure.

Flow Control

The Remote NDIS device may need to exercise flow control to prevent the host from overflowing its data buffers with packets. Any flow control provisions or requirements are given in the respective bus-mapping chapter.

Byte Ordering

All numeric values in message fields defined by this specification are assumed to be coded in little-endian format, i.e. least significant byte first.

Encapsulation

This section does not specify the way NDIS messages are encapsulated in native bus messages or primitives. Please refer to the appropriate bus-mapping chapter for more details.

Remote NDIS Version

Table - defines the Remote NDIS protocol version identifiers exchanged between host and device.

Note that these are unrelated to the revision number of this specification.

Table - : Remote NDIS Protocol Version

Status Values

The Remote NDIS status values are generally equivalent to the 32-bit status values defined in the Windows 2000 DDK. Specifically, high bit set indicates an error state and the high bit clear indicates a success state. The specific Remote NDIS status values used in this specification are listed below, others can be inferred from the Windows 2000 DDK or MSDN. A device may return any semantically correct Remote NDIS status value in a Status field of a message that it generates.

Table - : Remote NDIS Status Values

The following Remote NDIS control messages that must be supported by an 802.3 connectionless device, see Table 3- for an overview. In the more detailed descriptions below, some messages include a RequestId field. This is used to match sent messages with responses. With this mechanism, a host driver can send multiple Remote NDIS messages to a device without concern for the ordering of responses. A Remote NDIS device must maintain the RequestId field when returning a response.

Table - : Control Messages Set

REMOTE_NDIS_INITIALIZE_MSG

This message is sent by the host to a Remote NDIS device to initialize the network connection. It is sent via the control channel and only when the device is in the rndis-uninitialized state. See Table 3- for details of the message.

The MaxTransferSize indicates the maximum size, in bytes, of any single bus data transfer that the host expects to receive from the device. Typically, each bus data transfer accommodates a single Remote NDIS message. However, as described below (see Multi-Packet Transfers), the device may bundle several Remote NDIS messages containing Data packets into a single transfer.

MajorVersion and MinorVersion indicate the highest Remote NDIS protocol version implemented by the host. There is no guarantee that the host supports any lower versions; specifics of Remote NDIS version(s) supported by various Windows operating system versions will be documented in appropriate product documentation, e.g. the DDK. See Table - for more details.

REMOTE_NDIS_INITIALIZE_MSG Format

Table - : REMOTE_NDIS_INITIALIZE_MSG

Response to REMOTE_NDIS_INITIALIZE_MSG

The device should report its medium type, Remote NDIS version numbers, and its type (connection-less or connection-oriented) in its response to REMOTE_NDIS_INITIALIZE_MSG.

The Status field should be set to RNDIS_STATUS_SUCCESS if the device initialized successfully; otherwise it is set to an error code indicating the failure.

The device should return the highest Remote NDIS protocol version that it can support, in MajorVersion and MinorVersion - the combined version number should be less than or equal to the version number specified by the host in the REMOTE_NDIS_INITIALIZE_MSG message. This allows for the device to fall back to a compatibility mode when the host implements a Remote NDIS protocol version that is lower than that supported by the device.

The DeviceFlags field specifies the device type. MaxPacketsPerTransfer is the maximum number of REMOTE_NDIS_PACKET_MSGs that the device can handle in a single transfer to it - this should be at least 1. MaxTransferSize is the maximum size, in bytes, of a single data transfer that the device expects to receive from the host. The device can specify the byte alignment it expects for each Remote NDIS message that is part of a multi-message transfer to it - PacketAlignmentFactor contains this value as an exponent of 2. For example, this is set to 3 to indicate 8-byte alignment.

NOTE: The AFListSize and AFListOffset fields are only relevant for connection-oriented devices that include a call manager. Connectionless devices should set these fields to 0.

Table - : REMOTE_NDIS_INITIALIZE_CMPLT

REMOTE_NDIS_HALT_MSG

This message is sent by the host in order to terminate the network connection. Unlike the other host initiated control messages, there is no device response to REMOTE_NDIS_HALT_MSG. The message may be sent at any time that the device is in the rndis-initialized or rndis-data-initialized state.

Table - : REMOTE_NDIS_HALT_MSG Message

It is optional for the device to implement sending the REMOTE_NDIS_HALT_MSG. If implemented, the device sends this message to the host via the control channel only when the device is in the rndis-initialized or rndis-data-initialized state. The device must terminate all communication immediately after sending this message. Sending this message causes the device to enter the rndis-uninitialized state.

REMOTE_NDIS_QUERY_MSG

REMOTE_NDIS_QUERY_MSG is sent to a Remote NDIS device from a host when it needs to query the device for its characteristics or statistics information or status. The parameter or statistics being queried for is identified by means of an Object Identifier (OID). The host may send REMOTE_NDIS_QUERY_MSG to the device via the control channel at any time that the device is in the rndis-initialized or rndis-data-initialized state. A Remote NDIS device will respond to REMOTE_NDIS_QUERY_MSG with information about the desired capabilities or status.

REMOTE_NDIS_QUERY_MSG Format

Table - : REMOTE_NDIS_QUERY_MSG Message

Response to REMOTE_NDIS_QUERY_MSG

The device sends REMOTE_NDIS_QUERY_CMPLT to the host in response to REMOTE_NDIS_QUERY_MSG. This message is used to relay the result of a query for a device parameter or statistics counter to the host.

Table - : REMOTE_NDIS_QUERY_CMPLT

REMOTE_NDIS_SET_MSG

REMOTE_NDIS_SET_MSG is sent to a Remote NDIS device from a host, when it needs to set the value of some operational parameter on the device. The specific parameter being set is identified by means of an Object Identifier (OID), and the value it is to be set to is contained in an information buffer sent along with the message. (For a complete list of required and optional OIDs, please refer to Section .) The host may send REMOTE_NDIS_SET_MSG to the device via the control channel at any time that the device is in the rndis-initialized or rndis-data-initialized state. A Remote NDIS device will respond to a REMOTE_NDIS_SET_MSG message with a status.

REMOTE_NDIS_SET_MSG Format

Table - : REMOTE_NDIS_SET_MSG Message

Response to REMOTE_NDIS_SET_MSG

The device sends the REMOTE_NDIS_SET_CMPLT message to the host in response to REMOTE_NDIS_SET_MSG. This message is used to relay the result of setting the value of a device operational parameter to the host.

Table - : REMOTE_NDIS_SET_CMPLT

Setting Device-specific Parameters

It is expected that most Remote NDIS devices will function well without the need to configure parameters on the host. However, there may be cases where proper network operation requires some configuration on the host. If the device supports configurable parameters, then it should include the following optional OID in the list of supported OIDs it reports in response to a query for OID_GEN_SUPPORTED_LIST:

OID_GEN_RNDIS_CONFIG_PARAMETER (0x0001021B)

If the device supports this OID, the host uses it to set device-specific parameters, soon after the device enters the rndis_initialized state from rndis_uninitialized. The host will send zero or more REMOTE_NDIS_SET_MSGs to the device, with OID_GEN_RNDIS_CONFIG_PARAMETER as the OID value to set. Each such REMOTE_NDIS_SET_MSG corresponds to one device-specific parameter that is configured on the host.

The InformationBuffer associated with each such REMOTE_NDIS_SET_MSG has the following format. Note that the Offset values are relative to the beginning of the information buffer.

Table - : InformationBuffer for OID_GEN_RNDIS_CONFIG_PARAMETER

The device sends a REMOTE_NDIS_SET_CMPLT in response to each REMOTE_NDIS_SET_MSG, after applying the parameter value. If the parameter setting is acceptable, it returns a status of RNDIS_STATUS_SUCCESS in the response. If the parameter setting is not acceptable, and the device cannot apply a useful default value for this parameter, then the device returns an appropriate error status value (see Table - ). If an error status is returned, then the host will initiate a Halt process (see Section 3) for the device.

Device-specific parameters are expected to be configured in the Windows registry. The keys that define parameter values are typically created in the registry during the process of device installation; the list of keys, type information, default values and optional range of valid values are specified in the INF file for the device. For more information on using an INF to set up configuration parameters in the registry for network devices, please consult the Windows 2000 DDK.

REMOTE_NDIS_RESET_MSG

A REMOTE_NDIS_RESET_MSG message is sent to a Remote NDIS device from a host via the control channel to soft-reset the device and return status. This message may be sent at any time that the device is in the rndis-initialized or rndis-data-initialized state. A Remote NDIS device will respond to a REMOTE_NDIS_RESET_MSG message with a status.

REMOTE_NDIS_RESET_MSG Format

Table - : REMOTE_NDIS_RESET_MSG Message

Response to REMOTE_NDIS_RESET_MSG

When the device receives REMOTE_NDIS_RESET_MSG, it performs a soft-reset and then sends REMOTE_NDIS_RESET_CMPLT to the host with the result status.

Table - : REMOTE_NDIS_RESET_CMPLT

REMOTE_NDIS_INDICATE_STATUS_MSG

The device may send REMOTE_NDIS_INDICATE_STATUS_MSG to the host via the control channel in an unsolicited fashion at any time that the device is in the rndis-initialized or rndis-data-initialized state. This message is used to indicate a change in the status of the device. REMOTE_NDIS_INDICATE_STATUS_MSG can also be used to indicate an error event, such as an unrecognized message.

The most common use of REMOTE_NDIS_INDICATE_STATUS_MSG is to indicate the state of link for an 802.3 device. Status=RNDIS_STATUS_MEDIA_CONNECT indicates a transition from disconnected (e.g. no 802.3 link pulse) to connected state (802.3 link pulse detected); Status= RNDIS_STATUS_MEDIA_DISCONNECT indicates a transition from connected to disconnected state . The device must send REMOTE_NDIS_INDICATE_STATUS_MSG with one of these values every time that the 802.3 link state changes. No status buffer is required to return these two common indications.

In the specific case where this is sent in response to a message that the device could not handle, the Status field must be set to RNDIS_STATUS_INVALID_DATA, and the status buffer is formatted as described in Table - .

If the error condition was caused by an Remote NDIS message, for example if the device didn't understand a particular Remote NDIS message, then the device must append the original message at the end of the status message defined above. In this case, DiagStatus contains additional status about the error itself (e.g. RNDIS_STATUS_NOT_SUPPORTED) and ErrorOffset is the 0-based byte offset within the offending message at which the error was detected.

Note that this message is used to report an error condition only in circumstances where the device is not able to generate a response message with appropriate status. Examples of appropriate usage are: (a) on receiving a message with unsupported message type (b) on receiving an REMOTE_NDIS_PACKET_MSG with unacceptable contents.

REMOTE_NDIS_INDICATE_STATUS_MSG Format

Table - : REMOTE_NDIS_INDICATE_STATUS_MSG Message

Table - : Rndis_Diagnostic_Info

REMOTE_NDIS_KEEPALIVE_MSG

The host sends REMOTE_NDIS_KEEPALIVE_MSG to the device via the control channel in order to check the health of the device. When the device is in the rndis-data-initialized state, the host sends this message periodically when there has been no other control or data traffic from the device to the host for the KeepAliveTimeoutPeriod. KeepAliveTimeoutPeriod is bus-dependent and is defined in the appropriate bus-mapping chapter.

Upon receiving this message, the remote device must send back a response whose Status field indicates whether the device solicits a REMOTE_NDIS_RESET_MSG message from the host.

The host will not send REMOTE_NDIS_KEEPALIVE_MSG until the KeepAliveTimeoutPeriod has elapsed since the last message received from the remote device. This avoids unnecessary exchange of REMOTE_NDIS_KEEPALIVE_MSG messages when the communication channel is active.

The device may optionally send this message to the host as well. For example, the device may use this message to trigger a response from the host for the purpose of computing round-trip delay time. If implemented, the device must send REMOTE_NDIS_KEEPALIVE_MSG via the control channel and only when in the rndis-initialized or rndis-data-initialized state.

NOTE: The device does not need to perform any specific action if it stops seeing REMOTE_NDIS_KEEPALIVE_MSG messages from the host.

REMOTE_NDIS_KEEPALIVE_MSG Format

Table - : REMOTE_NDIS_KEEPALIVE_MSG Message

Response to REMOTE_NDIS_KEEPALIVE_MSG

The device sends REMOTE_NDIS_KEEPALIVE_CMPLT to the host in response to a REMOTE_NDIS_KEEPALIVE_MSG. If the returned Status is not RNDIS_STATUS_SUCCESS, then the host will send REMOTE_NDIS_RESET_MSG to reset the device.

Table - : REMOTE_NDIS_KEEPALIVE_CMPLT

If the device implements the option of sending REMOTE_NDIS_KEEPALIVE_MSG, then the host will respond with REMOTE_NDIS_KEEPALIVE_CMPLT via the control channel.

Example Connectionless (802.3) Initialization Sequence

This section describes the general order of events that a device can expect upon startup as a Remote NDIS connectionless device. Because the basic operation of Remote NDIS is the same, regardless of the underlying bus, the require bus enumeration and start up process has been left out of the example.

Table - : Generic Connectionless Remote NDIS Initialization Sequence

Note: real world operation will vary depending on version of Windows and NDIS.

Data Messages (REMOTE_NDIS_PACKET_MSG)

A Remote NDIS device transfers NDIS packets, encapsulated as REMOTE_NDIS_PACKET_MSG across the data channel. REMOTE_NDIS_PACKET_MSG may contain out of band (OOB) data and/or per-packet information.

REMOTE_NDIS_PACKET_MSG Format

Table - : REMOTE_NDIS_PACKET_MSG

Out-of-band data

Each REMOTE_NDIS_PACKET_MSG may contain one or more out-of-band data records. NumOOBDataElements indicates the number of out-of-band data records in this message. The out-of-band data records must appear in sequence. The OOBDataLength field indicates the byte length of the entire out-of-band data block. The OOBDataOffset field indicates the byte offset from the beginning of the DataOffset field to the beginning of the out-of-band data block. See the NDIS specification for more information about out-of-band packet data. Table - defines the format of a single out-of-band data record.

Table - : Out of Band Data Record Format

Note: (N) is equal to the value of ClassInformationOffset

If there are multiple out-of-band data blocks attached to a REMOTE_NDIS_PACKET_MSG, then each subsequent out-of-band data record must immediately follow the previous out-of-band record's data.

There is no out of band information currently defined for 802.3 devices.

Per-packet-info Data

Each REMOTE_NDIS_PACKET_MSG may contain one or more per-packet-info data records. Per-packet-info is used to convey packet meta-data such as TCP checksum. See the NDIS specification for more information about per-packet info data. Table - defines the format of a per-packet-info data record.

Table - : Per-Packet Info Data Record Format

NOTE: (N) is equal to the value of PerPacketInformationOffset

If there are multiple per-packet-info data blocks, then each subsequent per-packet-info data record must immediately follow the previous per-packet-info record's data.

Multi-Packet Transfers

Multiple REMOTE_NDIS_PACKET_MSG messages may be sent in a single transfer, in either direction. The maximum length of such a transfer is governed by the MaxTransferSize parameter passed in the REMOTE_NDIS_INITIALIZE_MSG and response messages. The host will also limit the number of REMOTE_NDIS_PACKET_MSGs it bundles into a single transfer to the value of the MaxPacketsPerTransfer parameter returned by the device in its response to REMOTE_NDIS_INITIALIZE_MSG.

Concatenating multiple REMOTE_NDIS_PACKET_MSG elements forms a multi-packet message. Each individual REMOTE_NDIS_PACKET_MSG component is constructed as described above. The difference from the single-packet message case is that the MessageLength field in each REMOTE_NDIS_PACKET_MSG header includes some additional padding bytes. These padding bytes are appended to all but the last REMOTE_NDIS_PACKET_MSG such that the succeeding REMOTE_NDIS_PACKET_MSG starts at an appropriate byte boundary. For messages sent from the device to the host, this padding should result in each REMOTE_NDIS_PACKET_MSG starting at a byte offset that is a multiple of 8 bytes starting from the beginning of the multi-packet message. When the host sends a multi-packet message to the device, it will adhere to the PacketAlignmentFactor specified by the device.

Note that neither the combined length of a multi-packet message nor the number of REMOTE_NDIS_PACKET_MSG elements in a combined message is given explicitly in any Remote NDIS -defined field. The combined length is implicit in the bus-specific transfer mechanism, and the host or device must walk the MessageLength fields of the combined message to determine the number of combined messages.

Table 3- contains an example of a multi-packet message that is made up of two REMOTE_NDIS_PACKET_MSGs, sent from the host to the device. During the REMOTE_NDIS_INITIALIZE_MSG exchange, the device requested a PacketAlignmentFactor of 3 (i.e. alignment along an 8 byte boundary).

Table - : Example of Multiple REMOTE_NDIS_PACKET_MSG Messages

This section is the list of optional and mandatory NDIS OIDs that Remote NDIS "Ethernet" devices can or must support. The list takes into account the unique properties of a Remote NDIS device, so the list is not identical to the list that a "normal" NDIS connection-less miniport would support. Some OIDs are both set and query OIDs; if a mandatory OID is defined as both, then it must be supported by a Remote NDIS device for both REMOTE_NDIS_SET_MSG and REMOTE_NDIS_QUERY_MSG. For a detailed explanation of the OIDs, please consult the Windows 2000 DDK.

General OIDs

Currently the lists are broken down into two groups, general OID and 802.3 specific OID. Additionally each group includes a sub-section of statistic OID queries.

Table - : General OIDs

Table - : General Statistics OIDs

802.3 OIDs

The following tables list the specific 802.3 OIDs that are applicable to Remote NDIS Ethernet devices.

Table - : 802.3 NDIS OIDs

Table - : 802.3 Statistics NDIS OIDs

Optional Power Management OIDs

For NDIS to consider a device power management aware, it must respond to the power management OIDs. These are listed in Table - . They are marked as optional, but if NDIS does not receive a NDIS_STATUS_SUCCESS to query of OID_PNP_CAPABILITIES, then it will consider the device as not being power manageable. NDIS decides whether to query this OID based on the underlying bus technology that the Remote NDIS device is connected. Some buses are inherently power manageable, like USB, so it is expected that these types of Remote NDIS devices will support the minimal OIDs to be considered power manageable.

Table - : Required Power Management OIDs

Network Wake-Up

To support network wake up events, a Remote NDIS device must additionally support the OID_PNP_ENABLE_WAKE_UP that is used by both the network protocols (TCP/IP) and NDIS to enable the wake up capabilities. Other options are available to enable specific types of wake up patterns. For further details, please consult the latest version of the Windows 2000 DDK.

Table - : Network Wake Up OIDs

This chapter defines the bus-specific characteristics of a USB (Universal Serial Bus) Remote NDIS device.

Related Specifications

The Universal Serial Bus (USB) Specification version 1.1 is required. The USB Communication Device Class (CDC) Specification version 1.1 is suggested as a reference. Both documents are available at https://www.usb.org.

Overview

A USB Remote NDIS device is implemented as a USB CDC device with two interfaces. A Communication Class interface, of type Abstract Control, and a Data Class interface combine to form a single functional unit representing the USB Remote NDIS device. The Communication Class interface includes a single endpoint for event notification; it also uses the shared bi-directional Control endpoint for control messages. The Data Class interface includes two bulk endpoints for data traffic.

NOTE: The CDC 1.1 specification also defines an "Ethernet Control Model" type Communication Class interface, but it is not used in a USB Remote NDIS device.

PnP and USB-level initialization

See the USB Specification for generic USB device initialization. The host issues standard USB requests to obtain a set of standard USB descriptors for the device. The relevant portions of those descriptors are given below.

USB Device Descriptor

The device returns a USB Device Descriptor as defined in the USB Specification. Table - defines the salient fields of the Device Descriptor.

Table - : Salient fields of USB Remote NDIS Device Descriptor

USB Configuration Descriptor

The device returns a Configuration Descriptor as defined in the USB Specification. The Configuration Descriptor indicates two default interfaces.

Communication Class Interface

The Communication Class interface is described by a USB interface descriptor and an endpoint descriptor for the notification endpoint. Table - defines the salient fields of the Communication Class interface descriptor.

Table - : Salient fields of Communication Class Interface Descriptor

The notification endpoint descriptor is a standard USB Interrupt-type IN endpoint descriptor whose wMaxPacketSize field is 8.

Data Class Interface

The Data Class interface is described by a standard USB Interface Descriptor followed by two endpoint descriptors. Table - defines the salient fields of the Data Class Interface Descriptor.

Table - : Data Class Interface Descriptor Requirements

The two endpoint descriptors in the Data Class interface define standard USB Bulk-type endpoints: one Bulk-IN and one Bulk-OUT.

USB-level termination

See the USB Specification for a description of generic USB bus-level termination

Control channel characteristics

The Control channel for the device is its USB Control endpoint.

A control message from the host to the device is sent as a SEND_ENCAPSULATED_COMMAND transfers. This transfer is defined in Table -

Table - : Format of USB bus transfer for SEND_ENCAPSULATED_COMMAND

The host does not continuously poll the USB Control endpoint for input control messages. Upon placing a control message on its Control endpoint, the device must return a notification on the Communication Class interface's Interrupt IN endpoint, which is polled by the host whenever the device can return control messages. The transfer from the device's interrupt IN endpoint to the host is a standard USB Interrupt IN transfer. The only defined device notification is the RESPONSE_AVAILABLE notification, defined in Table - .

Table - : RESPONSE_AVAILABLE notification message

Upon receiving the RESPONSE_AVAILABLE notification, the host reads the control message from the Control endpoint using a GET_ENCAPSULATED_RESPONSE transfer, defined in Table - .

Table - : Format of USB bus transfer for GET_ENCAPSULATED_RESPONSE

If for some reason the device receives a GET_ENCAPSULATED_RESPONSE and is unable to respond with a valid data on the Control endpoint, then it should return a one-byte packet set to 00h, rather than stalling the Control endpoint.

Data channel characteristics

The data channel for the device consists of the Bulk IN and OUT endpoints in the Data Class interface.

A single USB data transfer in either direction may consist of a single REMOTE_NDIS_PACKET_MSG or a longer message as defined in Multi-Packet Messages.

The USB transfer to send a data message from the host to the device is a standard USB bulk transfer to the Bulk OUT endpoint of the Data Class interface.

The USB transfer to send a data message from the device to the host is a standard USB bulk transfer from the Bulk IN endpoint of the Data Class interface. The host will read up to the number of bytes indicated by the MaxTransferSize field of REMOTE_NDIS_INITIALIZE_MSG, which will be no greater than 0x4000 bytes for a USB 1.1 device.

USB Short Packets

USB passes data over the wire in the form of USB packets, which should not be confused with NDIS or networking packets. The maximum length of a USB packet to or from a USB endpoint is limited to the value of the wMaxPacketSize field of the endpoint's descriptor. For bulk pipes the maximum packet size is 64 bytes. Due to constraints of certain USB host controllers, there is a penalty associated with using short USB packets, i.e. those of less then 64 bytes, when streaming data.

To work around this limitation, Remote NDIS USB devices may append zero-byte padding to data messages so that a short packet will not occur (within the constraints of the MaxTransferSize field of REMOTE_NDIS_INITIALIZE_MSG). The MessageLength field of the final REMOTE_NDIS_PACKET_MSG does not include these appended padding bytes.

If the device has transmitted its last available REMOTE_NDIS_PACKET_MSG (so no more are left in the device's queue), then it is acceptable to send a short USB packet.

If the last REMOTE_NDIS_PACKET_MSG of a device-send RNDIS data message (without any zero-byte padding) ends with a USB packet whose length is exactly the wMaxPacketSize for that endpoint, then the device may send an additional one-byte zero packet as an appended part of the transfer; some device implementations are simplified by this allowance.

Similarly, some device-side USB chipsets do not detect the end of a received USB transfer that ends with a USB packet whose length is the wMaxPacketSize for that endpoint. For this reason, the host must append a one-byte zero packet to a data transfer that otherwise would have a length that is a multiple of the wMaxPacketSize of the receiving endpoint. USB RNDIS devices must tolerate the appended byte. The MessageLength field of the final REMOTE_NDIS_PACKET_MSG does not include this appended byte.

Flow Control

Flow control for a USB Remote NDIS device is entirely defined by the USB Specification.

Since all communication on USB is based on a host to device transaction, all the host must do to slow the flow of data is stop issuing IN tokens to the device on the bulk pipe. If the device needs to assert flow control, then it should NAK data transfers from the host until it is able to process data again. For a detailed explanation of this process, review Section 8.4.4 in the USB Specification, version 1.1.

Power management

A USB Remote NDIS device must support the Power Management OIDs listed in the parent specification as well as Network wake-up. See the USB specification for a description of USB bus-level power management.

Timer constants

The ControlTimeoutPeriod for a USB Remote NDIS device is 10 seconds.

The KeepAliveTimeoutPeriod for a USB Remote NDIS device is 5 seconds.

Appendix A Overview of Bus-Mapping Chapters

This section is a guide describing the requirements of each bus-mapping chapter. It is intended to clarify the boundary between the specification proper and each bus-specific mapping chapter.

A.1 Versioning

An in-progress bus-mapping chapter should not be incorporated into this document until it is finalized and fully supports the RNDIS_MAJOR_VERSION/RNDIS_MINOR_VERSION of the document. Likewise, a bus-mapping chapter should be separated from the parent document if following a revision it no longer supports the RNDIS_MAJOR_VERSION/RNDIS_MINOR_VERSION of the parent document.

A.2 Requirements

Each bus-mapping chapter must at minimum define the following:

PnP and bus-specific initialization and termination of the adapter.

Characteristics of the control channel; including initialization, control message encapsulation and communication, and termination.

Characteristics of the data channel; including initialization, data message encapsulation and communication, reliability and in-order characteristics, flow control, and termination.

Power management

RNDIS_MAJOR_VERSION/RNDIS_MINOR_VERSION supported by the bus-mapping chapter. If the bus-mapping chapter is included as part of this document, then it implicitly supports the Remote NDIS version of this document. If, when the RNDIS_MAJOR_VERSION/ RNDIS_MINOR_VERSION of this specification is changed, one or more bus-mapping chapters do not support that change, then those bus-mapping chapters must be separated from this specification and distributed independently with the highest supported RNDIS_MAJOR_VERSION/ RNDIS_MINOR_VERSION stated explicitly therein.

The ControlTimeoutPeriod (see Control channel).

The KeepAliveTimeoutPeriod (see REMOTE_NDIS_KEEPALIVE_MSG).

A.3 Bus-specific messages

A bus-mapping chapter may include non-trivial bus-specific protocol. For example, if the bus layer does not provide a reliable transport for the control channel, the bus-mapping chapter may need to define a protocol to make the control channel reliable, as required by the Remote NDIS specification.

For such purposes, a bus-mapping chapter may define bus-specific messages on the control channel in either direction. Bus-specific control messages have the generic identifier REMOTE_NDIS_BUS_MSG. To avoid conflicts with future versions of the Remote NDIS specification, bus-mapping chapters must use the REMOTE_NDIS_BUS_MSG format for all bus-specific messages. REMOTE_NDIS_BUS_MSG messages may be sent at any time that the control channel is functioning, regardless of whether the adapter is in the rndis-uninitialized, rndis-initialized, or rndis-data-initialized state. A bus-mapping chapter may impose any desired restrictions on REMOTE_NDIS_BUS_MSG messages. Table A-1 defines the general template for this message.

Table A-1: Format of bus-specific REMOTE_NDIS_BUS_MSG messages

A.4 Optional features

A bus-mapping chapter may restrict any optional feature of the parent Remote NDIS specification.

Appendix B USB 802.3 Device Sample

The following is a sample set of descriptors for a USB Remote NDIS Ethernet Device. It includes a CDC Communication Class interface and a CDC Data Class interface. The Device Descriptor is returned independently. The Configuration descriptor and all following descriptors are returned as a single block in the order shown.

Control messages are sent on the Control endpoint. Notification messages are sent on the Interrupt In endpoint in the CDC Communication Class interface. Data messages are sent on the Bulk In and Bulk Out endpoints in the CDC Data Class interface. String descriptors are not shown.

B.1 Device Descriptor

Table B-1: USB Device Descriptor

B.2 Configuration Descriptor

Table B-2: USB Configuration Descriptor

B.3 Interface Descriptor for Communication Class Interface

Table B-3: USB Communication Class Interface Descriptor

B.4 Notification Endpoint Descriptor

Table B-4: Descriptor for Notification Endpoint

B.5 Interface Descriptor for Data Class Interface

Table B-5: USB Data Class Interface Descriptor

B.6  Data In Endpoint Descriptor

Table B-6: Descriptor for Bulk IN Endpoint

B.7 Data Out Endpoint Descriptor

Table B-7: Descriptor for Bulk OUT Endpoint

Notes:

The Remote NDIS implementation in Windows ME assumes that the Communication Class interface precedes the Data Class interface. Vendors should choose this descriptor ordering so that devices initialize correctly on Windows ME.

If any portion of this sample contradicts a controlling specification, follow the specification.

Some pre-1.0 versions of this Remote NDIS specification required 3 class-specific descriptors following the USB Communication Class Interface descriptor. These are no longer required. Devices that include these 3 descriptors are compatible with the Remote NDIS specification, and as such are supported in all Windows implementations of Remote NDIS.