微软RNDIS协议

Remote NDIS Specification Rev 1.1 August 9, 2002 1998-2001 Microsoft Corporation. All rights reserved. 1INTRODUCTION.4 1.1LICENSE AGREEMENT.5 2CONCEPTS AND DEFINITIONS .6 2.1CONTROL CHANNEL.6 2.2DATA CHANNEL.6 2.3INITIALIZATION AND TEARDOWN.6 2.4DEVICE STATE DEFINITIONS.6 2.4.1Halt.7 2.4.2Reset.7 2.5FLOW CONTROL.7 2.6BYTE ORDERING.7 2.7ENCAPSULATION.7 2.8REMOTE NDIS VERSION.7 2.9STATUS VALUES.8 3MESSAGE SET FOR CONNECTIONLESS (802.3) DEVICES. 9 3.1REMOTE_NDIS_INITIALIZE_MSG.9 3.1.1REMOTE_NDIS_INITIALIZE_MSG Format. 10 3.1.2Response to REMOTE_NDIS_INITIALIZE_MSG. 10 3.2REMOTE_NDIS_HALT_MSG.12 3.3REMOTE_NDIS_QUERY_MSG.13 3.3.1REMOTE_NDIS_QUERY_MSG Format. 13 3.3.2Response to REMOTE_NDIS_QUERY_MSG . 14 3.4REMOTE_NDIS_SET_MSG .14 3.4.1REMOTE_NDIS_SET_MSG Format.15 3.4.2Response to REMOTE_NDIS_SET_MSG . 15 3.4.3Setting Device-specific Parameters .16 3.5REMOTE_NDIS_RESET_MSG .17 3.5.1REMOTE_NDIS_RESET_MSG Format. 17 3.5.2Response to REMOTE_NDIS_RESET_MSG . 17 3.6REMOTE_NDIS_INDICATE_STATUS_MSG. 18 3.6.1REMOTE_NDIS_INDICATE_STATUS_MSG Format. 19 3.7REMOTE_NDIS_KEEPALIVE_MSG.19 3.7.1REMOTE_NDIS_KEEPALIVE_MSG Format . 20 3.7.2Response to REMOTE_NDIS_KEEPALIVE_MSG . 20 3.8EXAMPLE CONNECTIONLESS (802.3) INITIALIZATION SEQUENCE. 21 3.9DATA MESSAGES (REMOTE_NDIS_PACKET_MSG). 22 3.9.1REMOTE_NDIS_PACKET_MSG Format. 22 3.9.2Multi-Packet Transfers.24 4REQUIRED NDIS OIDS.27 4.1GENERAL OIDS.27 4.2802.3 OIDS.29 4.3OPTIONAL POWER MANAGEMENT OIDS.30 4.3.1Network Wake-Up.31 5REMOTE NDIS TO USB MAPPING .32 5.1RELATED SPECIFICATIONS.32 5.2OVERVIEW.32 5.3PNP AND USB-LEVEL INITIALIZATION.32 5.3.1USB Device Descriptor.32 5.3.2USB Configuration Descriptor.33 5.3.3Communication Class Interface.33 5.3.4Data Class Interface .33 5.4USB-LEVEL TERMINATION.34 5.5CONTROL CHANNEL CHARACTERISTICS.34 5.6DATA CHANNEL CHARACTERISTICS.35 5.6.1USB Short Packets .35 5.6.2Flow Control.36 5.7POWER MANAGEMENT.36 5.8TIMER 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 REMOTE_NDIS_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.1Hard 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 Table 2-1 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 2-1: Remote NDIS Protocol Version Version IdentifierValueDescription RNDIS_MAJOR_VERSION1Remote NDIS Major Version specified in this document. RNDIS_MINOR_VERSION0Remote 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 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 2-2: Remote NDIS Status Values Status IdentifierValueDescription RNDIS_STATUS_SUCCESS0 x00000000Success RNDIS_STATUS_FAILURE0 xC0000001Unspecified error (equivalent to STATUS_UNSUCCESSFUL) RNDIS_STATUS_INVALID_DATA0 xC0010015Invalid data error RNDIS_STATUS_NOT_SUPPORTED0 xC00000BBUnsupported request error RNDIS_STATUS_MEDIA_CONNECT0 x4001000BDevice is connected to network medium (equivalent to NDIS_STATUS_MEDIA_CONNEC T from Windows 2000 DDK) RNDIS_STATUS_MEDIA_DISCONNECT0 x4001000CDevice is disconnected from network medium (equivalent to NDIS_STATUS_MEDIA_DISCONN ECT from Windows 2000 DDK) RNDIS_STATUS_XxxEqual to NDIS_STATUS_Xxx values defined in Windows 2000 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 Table 3-1 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 3-1: Control Messages Set Message IdentifierValueDescription REMOTE_NDIS_INITIALIZE_MSG0 x00000002Initialize