微软RNDIS协议模板.doc

Remote NDIS Specification

Rev 1.1
August 9,
© 1998- Microsoft Corporation. All rights reserved.

1 INTRODUCTION 4
1.1 License Agreement 5
2 CONCEPTS AND DEFINITIONS 6
2.1 Control channel 6
2.2 Data channel 6
2.3 Initialization and Teardown 6
2.4 Device State Definitions 6
2.4.1 Halt 7
2.4.2 Reset 7
2.5 Flow Control 7
2.6 Byte Ordering 7
2.7 Encapsulation 7
2.8 Remote NDIS Version 7
2.9 Status Values 8
3 MESSAGE SET FOR CONNECTIONLESS (802.3) DEVICES 9
3.1 REMOTE_NDIS_INITIALIZE_MSG 9
3.1.1 REMOTE_NDIS_INITIALIZE_MSG Format 10
3.1.2 Response to REMOTE_NDIS_INITIALIZE_MSG 10
3.2 REMOTE_NDIS_HALT_MSG 12
3.3 REMOTE_NDIS_QUERY_MSG 13
3.3.1 REMOTE_NDIS_QUERY_MSG Format 13
3.3.2 Response to REMOTE_NDIS_QUERY_MSG 14
3.4 REMOTE_NDIS_SET_MSG 14
3.4.1 REMOTE_NDIS_SET_MSG Format 15
3.4.2 Response to REMOTE_NDIS_SET_MSG 15
3.4.3 Setting Device-specific Parameters 16
3.5 REMOTE_NDIS_RESET_MSG 17
3.5.1 REMOTE_NDIS_RESET_MSG Format 17
3.5.2 Response to REMOTE_NDIS_RESET_MSG 17
3.6 REMOTE_NDIS_INDICATE_STATUS_MSG 18
3.6.1 REMOTE_NDIS_INDICATE_STATUS_MSG Format 19
3.7 REMOTE_NDIS_KEEPALIVE_MSG 19
3.7.1 REMOTE_NDIS_KEEPALIVE_MSG Format 20
3.7.2 Response to REMOTE_NDIS_KEEPALIVE_MSG 20
3.8 Example Connectionless (802.3) Initialization Sequence 21
3.9 Data Messages (REMOTE_NDIS_PACKET_MSG) 22
3.9.1 REMOTE_NDIS_PACKET_MSG Format 22
3.9.2 Multi-Packet Transfers 24
4 REQUIRED NDIS OIDS 27
4.1 General OIDs 27
4.2 802.3 OIDs 29
4.3 Optional Power Management OIDs 30
4.3.1 Network Wake-Up 31
5 REMOTE NDIS TO USB MAPPING 32
5.1 Related Specifications 32
5.2 Overview 32
5.3 PnP and USB-level initialization 32
5.3.1 USB Device Descriptor 32
5.3.2 USB Configuration Descriptor 33
5.3.3 Communication Class Interface 33
5.3.4 Data Class Interface 33
5.4 USB-level termination 34
5.5 Control channel characteristics 34
5.6 Data channel characteristics 35
5.6.1 USB Short Packets 35
5.6.2 Flow Control 36
5.7 Power management 36
5.8 Timer constants 36

1 Introduction

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.

1.1 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.

2 Concepts and Definitions
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.

2.1 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.

2.2 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.

2.3 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.

2.4 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 REMOTENDIS_SET_MSG for the OID_GEN_CURRENT_PACKET_FILTER parameter with a non-zero filter, the device enters 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.

2.4.1 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.

2.4.2 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.

2.4.2.1 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.

2.5 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.

2.6 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.

2.7 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.

2.8 Remote NDIS Version
Error! Reference source not found. 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 21: Remote NDIS Protocol Version
Version Identifier
Value
Description
RNDIS_MAJOR_VERSION
1
Remote NDIS Major Version specified in this document.
RNDIS_MINOR_VERSION
0
Remote NDIS Minor Version specified in this document.

2.9 Status Values
The Remote NDIS status values are generally equivalent to the 32-bit status values defined in the Windows 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 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 22: Remote NDIS Status Values
Status Identifier
Value
Description
RNDIS_STATUS_SUCCESS
0x00000000
Success
RNDIS_STATUS_FAILURE
0xC0000001
Unspecified error (equivalent to STATUS_UNSUCCESSFUL)
RNDIS_STATUS_INVALID_DATA
0xC0010015
Invalid data error
RNDIS_STATUS_NOT_SUPPORTED
0xC00000BB
Unsupported request error
RNDIS_STATUS_MEDIA_CONNECT
0x4001000B
Device is connected to network medium (equivalent to NDIS_STATUS_MEDIA_CONNECT from Windows DDK)
RNDIS_STATUS_MEDIA_DISCONNECT
0x4001000C
Device is disconnected from network medium (equivalent to NDIS_STATUS_MEDIA_DISCONNECT from Windows DDK)
RNDIS_STATUS_Xxx
…
Equal to NDIS_STATUS_Xxx values defined in Windows DDK or MSDN

3 Message Set for Connectionless (802.3) Devices
The following Remote NDIS control messages that must be supported by an 802.3 connectionless device, see Error! Reference source not found. 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 31: Control Messages Set
Message Identifier
Value
Description
REMOTE_NDIS_INITIALIZE_MSG
0x00000002
Initialize the device.
REMOTE_NDIS_HALT_MSG
0x00000003
Halt the device. This is the only host control message that doesn’t get a response.
REMOTE_NDIS_QUERY_MSG
0x00000004
Send a ‘query’ OID.
REMOTE_NDIS_SET_MSG
0x00000005
Send a ‘set’ OID.
REMOTE_NDIS_RESET_MSG
0x00000006
Perform a soft reset on the device.
REMOTE_NDIS_INDICATE_STATUS_MSG
0x00000007
Indicates 802.3 link state or undefined message error.
REMOTE_NDIS_KEEPALIVE_MSG
0x00000008

During idle periods, sent every few seconds to check that the device is still responsive (may optionally also be sent by the device).
REMOTE_NDIS_INITIALIZE_CMPLT
0x80000002
Device response to initialization request.
REMOTE_NDIS_QUERY_CMPLT
0x80000004
Device response to ‘query’ OID request.
REMOTE_NDIS_SET_CMPLT
0x80000005
Device response to ‘set’ OID request.
REMOTE_NDIS_RESET_CMPLT
0x80000006
Device responses to reset request.
REMOTE_NDIS_KEEPALIVE_CMPLT
0x80000008
Device response to keep alive message.

3.1 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 Error! Reference source not found. 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 Error! Reference source not found.), the device may bundle several Remote NDIS messages containing Data packets into a sing