微软RNDIS协议.doc

Remote NDIS Specification Rev 1 1 August 9 2002 1998 2001 Microsoft Corporation All rights reserved Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 2 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 3 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 4 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 5 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 6 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 7 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 8 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 Xxx Equal to NDIS STATUS Xxx values defined in Windows 2000 DDK or MSDN Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 9 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 the device REMOTE NDIS HALT MSG0 x00000003Halt the device This is the only host control message that doesn t get a response REMOTE NDIS QUERY MSG0 x00000004Send a query OID REMOTE NDIS SET MSG0 x00000005Send a set OID REMOTE NDIS RESET MSG0 x00000006Perform a soft reset on the device REMOTE NDIS INDICATE STATUS MSG 0 x00000007Indicates 802 3 link state or undefined message error REMOTE NDIS KEEPALIVE MSG0 x00000008During 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 CMPLT0 x80000002Device response to initialization request REMOTE NDIS QUERY CMPLT0 x80000004Device response to query OID request REMOTE NDIS SET CMPLT0 x80000005Device response to set OID request REMOTE NDIS RESET CMPLT0 x80000006Device responses to reset request REMOTE NDIS KEEPALIVE CMPLT0 x80000008Device 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 Table 3 2 for details of the message Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 10 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 2 1 for more details 3 1 1 REMOTE NDIS INITIALIZE MSG Format Table 3 2 REMOTE NDIS INITIALIZE MSG OffsetSizeFieldDescription 04MessageTypeSpecifies the Remote NDIS message type This is set to REMOTE NDIS INITIALIZE MSG 0 x2 44MessageLengthSpecifies the total length of this Remote NDIS message in bytes 24 84RequestIdSpecifies the Remote NDIS message id value This value is used to match host sent messages with device responses 124MajorVersionRNDIS MAJOR VERSION Specifies the Remote NDIS protocol major version implemented by the host 164MinorVersionRNDIS MINOR VERSION Specifies the Remote NDIS protocol minor version implemented by the host 204MaxTransferSizeSpecifies 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 the device may bundle several Remote NDIS data packets into a single transfer see REMOTE NDIS PACKET MSG 3 1 2 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 Remote NDIS Specification Rev 1 00 Microsoft CorporationPage 11 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 3 3 REMOTE NDIS INITIALIZE CMPLT OffsetSizeFieldDescription 04MessageTypeSpecifies the Remote NDIS message type This is set to REMOTE NDIS INITIALIZE CMPLT 0 x80000002 44MessageLengthSpecifies the total length of this Remote NDI