微软RNDIS协议VIP

1、 remote ndis specificationrev 1.1august 9, 2002 1998-2001 microsoft corporation. all rights reserved.1introduction.41.1license agreement.52concepts and definitions.62.1control channel.62.2data channel.62.3initialization and teardown.62.4device state definitions.62.4.1halt.72.4.2reset .72.5flow contr

2、ol.72.6byte ordering.72.7encapsulation.72.8remote ndis version.72.9status values.83message set for connectionless (802.3) devices.93.1remote_ndis_initialize_msg.93.1.1remote_ndis_initialize_msg format.103.1.2response to remote_ndis_initialize_msg .103.2remote_ndis_halt_msg.123.3remote_ndis_query_msg

3、.133.3.1remote_ndis_query_msg format .133.3.2response to remote_ndis_query_msg.143.4remote_ndis_set_msg.143.4.1remote_ndis_set_msg format.153.4.2response to remote_ndis_set_msg .153.4.3setting device-specific parameters.163.5remote_ndis_reset_msg .173.5.1remote_ndis_reset_msg format.173.5.2response

4、to remote_ndis_reset_msg .173.6remote_ndis_indicate_status_msg.183.6.1remote_ndis_indicate_status_msg format .193.7remote_ndis_keepalive_msg.193.7.1remote_ndis_keepalive_msg format .203.7.2response to remote_ndis_keepalive_msg.203.8example connectionless (802.3) initialization sequence.213.9data mes

5、sages (remote_ndis_packet_msg).223.9.1remote_ndis_packet_msg format .223.9.2multi-packet transfers.244required ndis oids.274.1general oids.274.2802.3 oids.294.3optional power management oids.304.3.1network wake-up .315remote ndis to usb mapping.325.1related specifications.325.2overview.325.3pnp and

6、usb-level initialization.325.3.1usb device descriptor .325.3.2usb configuration descriptor.335.3.3communication class interface.335.3.4data class interface.335.4usb-level termination.345.5control channel characteristics.345.6data channel characteristics.355.6.1usb short packets.355.6.2flow control .

7、365.7power management.365.8timer constants.361 introductionremote 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

8、 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 le

9、gacy 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

10、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 interfac

11、e 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 an

12、d other ways, the remote ndis specification allows for a wide range of device functionality and performance levels.1.1 license agreementthe remote ndis specification and any accompanying materials (the “specification”) provided by microsoft is for your personal use only, and may be used solely for t

13、he 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,

14、 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 t

15、he 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

16、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 doc

17、ument 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 witho

18、ut 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

19、 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

20、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

21、 concepts and definitionsthis 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 channelthe specifics of

22、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_indica

23、te_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 channelthe specifics of the data channel are given in the appropriate bus-mapping chapter. the data channel is used

24、 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 ch

25、apter.2.3 initialization and teardownthe 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 a

26、bout 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 t

27、his message.2.4 device state definitionsfollowing 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_n

28、dis_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 r

29、ndis-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 haltat any time that the device is in the rndis-initialized or rndis-data-initialized state, the host computer may terminate the remot

30、e ndis functionality of the device in an abortive fashion by sending remote_ndis_halt_msg to the device. 2.4.2 resetthe 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

31、 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 an

32、y 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 hos

33、t intact.2.4.2.1hard resetif 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 remo

34、te 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 controlthe 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

35、 requirements are given in the respective bus-mapping chapter.2.6 byte orderingall 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 encapsulationthis section does not specify the way ndis messages ar

36、e encapsulated in native bus messages or primitives. please refer to the appropriate bus-mapping chapter for more details.2.8 remote ndis versiontable 2-1 defines the remote ndis protocol version identifiers exchanged between host and device. note that these are unrelated to the revision number of t

37、his specification.table 2-1: remote ndis protocol versionversion identifiervaluedescriptionrndis_major_version1remote ndis major version specified in this document.rndis_minor_version0remote ndis minor version specified in this document.2.9 status valuesthe remote ndis status values are generally eq

38、uivalent 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

39、 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 valuesstatus identifiervaluedescriptionrndis_status_success0 x00000000successrndis_status_failure0 xc0000001unspecified error (equivalent

40、 to status_unsuccessful)rndis_status_invalid_data0 xc0010015invalid data errorrndis_status_not_supported0 xc00000bbunsupported request errorrndis_status_media_connect0 x4001000bdevice is connected to network medium (equivalent to ndis_status_media_connect from windows 2000 ddk)rndis_status_media_dis

41、connect0 x4001000cdevice is disconnected from network medium (equivalent to ndis_status_media_disconnect from windows 2000 ddk)rndis_status_xxxequal to ndis_status_xxx values defined in windows 2000 ddk or msdn3 message set for connectionless (802.3) devicesthe following remote ndis control messages

42、 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

43、 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 setmessage identifiervaluedescriptionremote_ndis_initialize_msg0 x00000002initialize the device.remote_ndis_halt_msg0 x00000003halt th

44、e device. this is the only host control message that doesnt 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_msg0 x00000007indicates 802.3 link s

45、tate 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_

46、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

47、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.the maxtransfersize indicates the maximum size, in bytes, of any single

48、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

49、.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 prod

50、uct documentation, e.g. the ddk. see table 2-1 for more details.3.1.1 remote_ndis_initialize_msg formattable 3-2: remote_ndis_initialize_msgoffsetsizefielddescription04messagetypespecifies the remote ndis message type. this is set to remote_ndis_initialize_msg = 0 x2.44messagelengthspecifies the tot

51、al 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_versionspecifies the remote ndis protocol major version implemented by the host. 164minorversionr

52、ndis_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 m

53、essage. 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

54、 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 a

55、nd 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 t

56、hat 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 trans

57、fer 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 align

58、ment.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_cmpltoffsetsizefielddescription04messagetypespecifies the remote ndis message type.

59、this is set to remote_ndis_initialize_cmplt = 0 x80000002.44messagelengthspecifies the total length of this remote ndis message.84requestidspecifies the remote ndis message id value. this value is used to match host sent messages with device responses.124statusspecifies rndis_status_success if the d

60、evice initialized successfully, otherwise it specifies an error code indicating the failure. see section 2.9 for more details.164majorversionrndis_major_version together with minorversion, specifies the highest remote ndis protocol version supported by the device.204minorversionrndis_minor_version t