Network Drivers and Windows

Updated: December 4, 2001

This article presents information about Microsoft Windows 2000 and Windows XP network drivers which are documented in the current Windows DDK.

On This Page

  Implementing Support for Media Sense
  Clarifications to the TCP/IP - NDIS Task Offload DDK Documentation
  NDIS_TASK_OFFLOAD_HEADER Definition Revision
  NDIS_TASK_OFFLOAD_HEADER Members
  Comments
  Revisions to Task Offload Objects
  Querying an Adapter's Task-Offload Capabilities
  Enabling an Adapter's Task-Offload Capabilities
  Disabling an Adapter's Task-Offload Capabilities
  Changing an Adapter's Task-Offload Capabilities
  Changes to NDIS_TASK_OFFLOAD Structure
  NDIS_TASK_OFFLOAD Definition
  NDIS_TASK_OFFLOAD Members
  Getting Ready for Large Memory-Enabled Windows
  Building Drivers with Symbols (dbg and pdb)

Implementing Support for Media Sense

The overall rule to follow for media sense is: Indicate a media event only if a change state has occurred. The following describes applicable scenarios.

Connect/Disconnect

• If a connected device is disconnected, it should generate a disconnect event within two seconds.

• If a disconnected device is connected, it should generate a connect event within two seconds.

Reset

• If a connected device is reset, it should not generate any disconnect or connect events. (Preferred)
  Or it can generate one disconnect and one connect event.
  If it generates a connect event, then this should happen within two seconds of reset completion.

• If a disconnected device resets, it should not generate any disconnect events.

Halt

• If a connected or disconnected device is halted, it must not generate any media events.

Load

• If a connected device is loaded, Network Driver Interface Specification (NDIS) assumes the device is connected, it should not generate a connect event. (Preferred)
  Or it is acceptable to generate a connect event within two seconds of initialization completion.

• If a disconnected device is loaded, it should generate a disconnect event within two seconds of initialization completion.

Sleep

• If a connected or disconnected device is put into a sleep state, it should not generate a media event.

• If a connected device is brought out of a sleep state and it was connected when put to sleep, it should not generate a connect event.

• If a disconnected device is brought out of a sleep state and it was disconnected when put to sleep, it should not generate a disconnect event.

• If the connect status changes while a device is asleep, then when it is awakened, it should generate an event indicating its new status within two seconds of waking.

NOTES:

• When loading or waking, the device should hold responses to OID_GEN_(CO_)MEDIA_CONNECT_STATUS until connect status is determined.

• Determination of the wake status should not slow initialization.

• Resets should not be completed until connect status has been determined.

• Token ring adapters and drivers can take up to 30 seconds to generate media events in all situations mentioned earlier.

 Top of page

Clarifications to the TCP/IP - NDIS Task Offload DDK Documentation

Upon implementing TCP/IP offloads to NIC hardware through NDIS, Microsoft has found that there are some areas of the DDK documentation in need of clarification. These clarifications are intended to answer questions that have arisen with the current documentation. See details in the current Windows DDK.

 Top of page

NDIS_TASK_OFFLOAD_HEADER Definition Revision

typedef struct _NDIS_TASK_OFFLOAD_HEADER















{















        ULONG  Version;















        ULONG  Size;















        ULONG  Reserved;















        UCHAR  OffsetFirstTask;















        NDIS_ENCAPSULATION_FORMAT  EncapsulationFormat;















} NDIS_TASK_OFFLOAD_HEADER , *PNDIS_TASK_OFFLOAD_HEADER ;

The NDIS_TASK_OFFLOAD_HEADER structure specifies the encapsulation format for send and receive packets on which a miniport may perform tasks offloaded from the TCP/IP transport.

 Top of page

NDIS_TASK_OFFLOAD_HEADER Members

Version
Specifies the task-offload version supported by the TCP/IP transport. This value is always set to NDIS_TASK_OFFLOAD_VERSION.

Size
Specifies in bytes the size of the NDIS_TASK_OFFLOAD_HEADER structure. Size is set to sizeof (NDIS_TASK_OFFLOAD_HEADER) and is used to determine the version of the NDIS_TASK_OFFLOAD_HEADER structure.

Reserved
This is reserved.

OffsetFirstTask
Specifies in bytes the offset from the beginning of the InformationBuffer to the first NDIS_TASK_OFFLOAD structure. The miniport is responsible for setting this value when responding to a query of OID_TCP_TASK_OFFLOAD. The TCP/IP transport is responsible for setting this value when setting OID_TCP_TASK_OFFLOAD. If no NDIS_TASK_OFFLOAD structures are in the InformationBuffer, OffsetFirstTask is set to zero.

EncapsulationFormat
Specifies the encapsulation format for both send and receive packets that are passed to or from the TCP/IP transport through the miniport's NIC. This information is formatted as an NDIS_ENCAPSULATION_FORMAT structure, which is defined as follows:

typedef struct _NDIS_ENCAPSULATION_FORMAT















{















    NDIS_ENCAPSULATION  Encapsulation;















    {















        ULONG   FixedHeaderSize:1;















        ULONG   Reserved:31;















    } Flags;















    ULONG     EncapsulationHeaderSize;















} NDIS_ENCAPSULATION_FORMAT,*PNDIS_ENCAPSULATION_FORMAT;

The members of this structure contain the following information:

Encapsulation
Specifies the encapsulation type as one of the following values:

UNSPECIFIED_Encapsulation An encapsulation other than the encapsulations listed below.

NULL_Encapsulation This value is reserved for future use.

IEEE_802_3_Encapsulation IEEE 802.3 encapsulation (Ethernet_DIX).

IEEE_802_5_Encapsulation IEEE 802.5 encapsulation.

LLC_SNAP_ROUTED_Encapsulation LLC encapsulation for routed protocols, for example, as described in RFC 1483. This is also used to indicate Ethernet LLC/SNAP encapsulation.

LLC_SNAP_BRIDGE_Encapsulation This value is reserved for future use.

FixedHeaderSize
This field is always set to 1. It indicates that the encapsulation header is the same size in each packet.

Reserved
This is reserved.

EncapsulationHeaderSize
Specifies in bytes the size of the encapsulation header. The first IP header in the encapsulated transmit packet starts at this offset from the start of the packet.

 Top of page

Comments

When the TCP/IP transport queries OID_TCP_TASK_OFFLOAD, it initializes and passes an NDIS_TASK_OFFLOAD_HEADER structure in the InformationBuffer associated with the query. The miniport that receives this query examines the NDIS_TASK_OFFLOAD_HEADER structure to determine the version and encapsulation format for send and receive packets processed by the TCP/IP transport. The miniport or its NIC uses the encapsulation information to determine the format of the encapsulation header, as well as the start of the first IP header in such packets so that the NIC can perform offload tasks on these packets.

The miniport responds to the query by appending one or more NDIS_TASK_OFFLOAD structures (representing the supported offload tasks) to the NDIS_TASK_OFFLOAD_HEADER structure. The miniport sets OffsetFirstTask to the offset of the first task from the start of InformationBuffer. The miniport does not alter any of the other fields in NDIS_TASK_OFFLOAD_HEADER. If the miniport does not understand the version number, size, or encapsulation format, the miniport fails the query with status NDIS_STATUS_NOT_SUPPORTED.

The encapsulation format specified by TCP/IP transport in the NDIS_TASK_OFFLOAD_HEADER structure applies to both send and receive packets that are passed to or from the TCP/IP transport through the NIC. Only one encapsulation format is supported per NIC at any given time.

To disable all of a NIC's task-offload capabilities, the TCP/IP transport sets OID_TCP_TASK_OFFLOAD, passing only an NDIS_TASK_OFFLOAD_HEADER in the InformationBuffer. In this case, the TCP/IP transport sets the OffsetFirstTask member of the NDIS_TASK_OFFLOAD_HEADER to zero.

If a miniport and its NIC supports offload, it must implement offload for the "Required" encapsulation type indicated in the table below. In addition, the miniport may support other frame types, if the media supports more than one, as indicated in the following table.

If the NIC supports more than one frame type, specific offload types (checksum, large send) implemented for each framing type need not be the same. For example, an Ethernet NIC may implement checksum and IPSec offloads for DIX, but only checksum for Sub-network Access Protocol (SNAP).

TCP Largesend capability requires knowledge of the encapsulation header. Therefore, TCP Largesend capability must not be offered by the miniport if the miniport does not recognize the encapsulation format specified in Encapsulation. TCP Largesend capability may be offered if Encapsulation is set to UNSPECIFIED_Encapsulation and EncapsulationHeaderSize is set to size of the encapsulation header for the media supported by the miniport and its NIC.

The encapsulation format specified by TCP/IP transport in the NDIS_TASK_OFFLOAD_HEADER structure applies to both send and receive packets that are passed to or from the TCP/IP transport through the NIC. Only one encapsulation format is supported per NIC at any given time.

To disable all a NIC's task-offload capabilities, the TCP/IP transport sets OID_TCP_TASK_OFFLOAD, passing only an NDIS_TASK_OFFLOAD_HEADER in the InformationBuffer. In this case, the TCP/IP transport sets the OffsetFirstTask member of the NDIS_TASK_OFFLOAD_HEADER to zero.

See also: NDIS_TASK_OFFLOAD, OID_TCP_TASK_OFFLOAD.

 Top of page

Revisions to Task Offload Objects

This is a revision to Windows 2000 DDK Network Design Guide, Chapter 16, Task Offload Objects. This is preliminary documentation and subject to change.

The following chart summarizes the OIDs that support TCP/IP task-offload operations. For a description of such operations, see Part 2 of the Network Design Guide in the DDK.

The TCP/IP transport queries the OID_TCP_TASK_OFFLOAD to determine the task-offload capabilities of a miniport's NIC. After determining which task-offload capabilities a NIC supports, the TCP/IP transport protocol sets this OID to enable the reported capabilities. The TCP/IP protocol can also disable all of a NIC's task-offload capabilities by setting this OID.

Only one protocol at a time can enable the task-offload capabilities of a particular NIC.

For more information about OID_TCP_TASK_IPSEC_ADD_SA and OID_TCP_TASK_IPSEC_DELETE_SA, see the http://www.microsoft.com/whdc/devtools/ddk/default.mspxWindows 2000 DDK.

 Top of page

Querying an Adapter's Task-Offload Capabilities

When the TCP/IP transport queries OID_TCP_TASK_OFFLOAD, it supplies an NDIS_TASK_OFFLOAD_HEADER structure in the InformationBuffer. This structure specifies the task-offload version supported by the TCP/IP transport, the encapsulation format for send and receive packets processed by the TCP/IP transport, and the size of the encapsulation header in such packets. With this information, the miniport or its NIC can locate the beginning of the first IP header in a transmit packet, which is a prerequisite for performing an offload task.

In response to a query of OID_TCP_TASK_OFFLOAD, a miniport returns (in the InformationBuffer) the NDIS_TASK_OFFLOAD_HEADER structure, followed immediately by one or more NDIS_TASK_OFFLOAD structures. Each NDIS_TASK_OFFLOAD structure describes a task-offload capability supported by the miniport's NIC. If the miniport's NIC supports multiple versions of a particular task-offload capability, it should return one NDIS_TASK_OFFLOAD structure for each version.

Each NDIS_TASK_OFFLOAD structure has a Task member that specifies the particular offload task to which the structure applies. Each NDIS_TASK_OFFLOAD structure also has a TaskBuffer that contains information pertinent to the specified offload task. The information in the TaskBuffer is formatted as one of the following structures:

• NDIS_TASK_TCP_IP_CHECKSUM - specifies checksum offload capabilities.

• NDIS_TASK_IPSEC - specifies IP Security offload capabilities.

• NDIS_TASK_TCP_LARGE_SEND - specifies large-TCP-packet segmentation capabilities.

 Top of page

Enabling an Adapter's Task-Offload Capabilities

After querying a NIC's task-offload capabilities, the TCP/IP transport enables one or more of these capabilities by setting OID_TCP_TASK_OFFLOAD. When setting OID_TCP_TASK_OFFLOAD, the TCP/IP transport supplies in the InformationBuffer an NDIS_TASK_OFFLOAD_HEADER structure, followed immediately by an NDIS_TASK_OFFLOAD structure for each task-offload capability that the transport is enabling.

The Task in each NDIS_TASK_OFFLOAD structure indicates the offload task that the TCP/IP transport is enabling. The TCP/IP transport also enables capabilities for a particular offload task by setting members of the structure (NDIS_TASK_TCP_IP_CHECKSUM, NDIS_TASK_IPSEC, or NDIS_TASK_TCP_LARGE_SEND) in the TaskBuffer of each NDIS_TASK_OFFLOAD structure.

 Top of page

Disabling an Adapter's Task-Offload Capabilities

To disable all task-offload capabilities supported by a NIC, the TCP/IP transport sets OID_TCP_TASK_OFFLOAD, passing in the InformationBuffer only an NDIS_TASK_OFFLOAD_HEADER structure with the OffsetFirstTask member of this structure set to 0.

 Top of page

Changing an Adapter's Task-Offload Capabilities

To change the set of task-offload capabilities supported by a NIC, the TCP/IP transport sets OID_TCP_TASK_OFFLOAD as when first enabling a NIC's task-offload capabilities. The miniport must enable exactly those capabilities (and no others) as specified in the most recent set of OID_TCP_TASK_OFFLOAD.

 Top of page

Changes to NDIS_TASK_OFFLOAD Structure

The following changes have been made to the NDIS_TASK_OFFLOAD structure, specifically for the OffsetNextTask member. This is preliminary documentation and subject to change.

 Top of page

NDIS_TASK_OFFLOAD Definition

typedef struct _NDIS_TASK_OFFLOAD















{















        ULONG      Version;















        ULONG      Size;















        NDIS_TASK  Task;















        ULONG      OffsetNextTask;















        ULONG      TaskBufferLength;















        UCHAR      TaskBuffer[1];















} NDIS_TASK_OFFLOAD, *PNDIS_TASK_OFFLOAD;

When supplied by a miniport in response to OID_TCP_TASK_OFFLOAD, the NDIS_TASK_OFFLOAD structure specifies a NIC's capabilities for performing a particular type of task offloaded from the TCP/IP transport. When supplied by the TCP/IP transport in a set of OID_TCP_TASK_OFFLOAD, the NDIS_TASK_OFFLOAD structure specifies an offload task that the TCP/IP transport is enabling.

 Top of page

NDIS_TASK_OFFLOAD Members

Version
Specifies the version number of this task-offload capability. If the miniport's NIC supports more than one version of a particular task-offload capability, each version of the capability should be indicated with a separate NDIS_TASK_OFFLOAD structure. The TCP/IP transport chooses the most suitable version to enable.

Size
Specifies the size in bytes of the NDIS_TASK_OFFLOAD structure. Size is set to sizeof (NDIS_TASK_OFFLOAD) and is used to determine the version of the NDIS_TASK_OFFLOAD structure.

Task
Specifies the type of offload task as one of the following:
TcpIpChecksumNdisTask
Checksum offload. The TaskBuffer contains an NDIS_TASK_TCP_IP_CHECKSUM structure.
IpSecNdisTask
IP Security offload. The TaskBuffer contains an NDIS_TASK_IPSEC structure.
TcpLargeSendNdisTask
Segmentation offload. The TaskBuffer contains an NDIS_TASK_TCP_LARGE_SEND structure.

OffsetNextTask
Specifies in bytes the offset from the beginning of the current NDIS_TASK_OFFLOAD structure to the next NDIS_TASK_OFFLOAD structure in the InformationBuffer. If this NDIS_TASK_OFFLOAD structure is the last one in the InformationBuffer, OffsetNextTask is set to 0.

TaskBufferLength
Specifies the size in bytes of the structure at TaskBuffer .

TaskBuffer
Specifies a variable-length array that contains information specific to the offload task indicated by Task . The contents of the TaskBuffer vary according to the Task type.

 Top of page

Getting Ready for Large Memory-Enabled Windows

To accommodate drivers that use 64-bit DMA and not force them to use ScatterGatherDma (to improve performance), the following changes have been made to NdisMAllocateMapRegisters. These changes are backward compatible with earlier semantics. This will be included in the Windows 2000 RC2 DDK.

Old Definition

EXPORT















NDIS_STATUS















NdisMAllocateMapRegisters(















        IN  NDIS_HANDLE  MiniportAdapterHandle,















        IN  UINT         DmaChannel,















	   IN  BOOLEAN   Dma32BitAddresses,















        IN  ULONG        PhysicalMapRegistersNeeded,















        IN  ULONG        MaximumPhysicalMapping















        );

New Definition for NdisMAllocateMapRegisters

typedef UCHAR   NDIS_DMA_SIZE;































#define NDIS_DMA_24BITS             0















#define NDIS_DMA_32BITS             1















#define NDIS_DMA_64BITS             2































EXPORT















NDIS_STATUS















NdisMAllocateMapRegisters(















    IN  NDIS_HANDLE       MiniportAdapterHandle,















    IN  UINT              DmaChannel,















    IN  NDIS_DMA_SIZE  DmaSize,















    IN  ULONG             PhysicalMapRegistersNeeded,















    IN  ULONG             MaximumPhysicalMapping















    );

The change is highlighted in bold above. In the old definition, FALSE maps to NDIS_DMA_24_BITS and TRUE maps to NDIS_DMA_32BITS. Drivers that support 64 bits need to use NDIS_DMA_64BITS. Everything else remains the same. Also, note that mapped memory descriptor lists (MDLs) will result in physical address greater than 32 bits on systems supporting greater than 4 GB physical memory.

NOTE: The maximum value for the MaximumPhysicalMapping parameter in the call to NdisMAllocateMapRegisters is 0xF000. Specifying a value greater than 0xF000 will likely cause the call to fail.

 Top of page

Building Drivers with Symbols (dbg and pdb)

This section includes new information about setting up the build environment.

Linker Options. If you are not using Build.exe to generate the binaries, then use the following option with the linker (Link.exe).

/Debugtype:CV,Fixup

 Top of page