Net ring element management

  • Article

Follow the guidance in this topic to manage your NET_RING structures and their elements during network data transfer. The rules in this topic describe which members of the net ring elements client drivers can modify and when, depending on the data path scenario, as well as general information client drivers should keep in mind for these structures.

Important

Client drivers should adhere to these directions during all phases of development. If a client driver does not adhere to these directions while testing with Driver Verifier, Driver Verifier reports a violation and triggers a bug check on the device under test.

NET_RING

When the NET_RING's parent packet queue is started, all indices in the ring are initialized to 0.

The following table describes which members of the net ring that client drivers can modify.

Field Client driver is allowed to modify
OSReserved1 No
ElementStride No
NumberOfElements No
ElementIndexMask No
EndIndex No
OSReserved0 No
OSReserved2 No
BeginIndex Yes (Required)
NextIndex Yes (Optional) Note: The framework never reads NextIndex.
Scratch Yes (Optional) Note: The framework never reads Scratch.
Buffer No

Client drivers must not modify any read only members of this structure, nor should they ever increment BeginIndex past EndIndex during a call to EvtPacketQueueAdvance.

For more information about index ownership in net rings, see Introduction to net rings.

NET_PACKET

The fields in a NET_PACKET are sensitive to the different contexts in which the data path operates. Whether the packet's Ignore field is set and whether the driver is receiving (Rx) or transmitting (Tx) the packet change the ruleset that is applied to the packet.

The following table provides directions for drivers in each scenario.

Rx or Tx Ignore field is set by... Notes
Rx Client driver
  • During Rx, client drivers set Ignore if necessary, and the framework reads it. Client drivers do not need to read Ignore at any point during Rx.
  • If a client driver sets the Ignore field during Rx, then:
    • Client drivers must write to the Ignore field when canceling Rx operations for any packet that has not been successfully programmed to hardware. For more info, see Canceling network data with net rings.
    • Client drivers must not associate resources with the packet because they will not be freed.
  • If a client driver does not set the Ignore field during Rx, then:
    • Client drivers must populate FragmentIndex, FragmentCount, and all fields in Layout.
    • FragmentIndex must be between BeginIndex inclusive and EndIndex exclusive in the fragment ring.
    • FragmentCount cannot exceed the count of fragments between BeginIndex inclusive and EndIndex exclusive in the fragment ring.
    • Client drivers must move the packet ring BeginIndex if they move the corresponding fragment ring BeginIndex.
    • After the call to EvtPacketQueueAdvance, if a client driver increments the packet ring BeginIndex then the driver must also increment the fragment ring BeginIndex past the fragments for that packet. In other words, the fragment ring BeginIndex should move to the EndIndex of the previous packet's fragments.
Tx NetAdapterCx
  • Client drivers must not modify any fields in any packet except for Scratch.
  • Client drivers can read the value of Ignore but must never write to it.
  • If a Tx packet is ignored, the driver must not read any fields except possibly for Scratch, if necessary.

NET_PACKET_LAYOUT

During Rx operations, the Layout field of the NET_PACKET is subject to the following rules:

  • All fields except for Reserved0 must be initialized by the client driver.
  • If Layer2Type is set to NetPacketLayer2TypeEthernet, then Layer2HeaderLength must be 14 or greater.
  • If Layer2Type is set to NetPacketLayer2TypeNull, then Layer2HeaderLength must be set to 0.
  • If Layer3Type is an IPv4 type, then Layer3HeaderLength must be 20 or greater.
  • If Layer3Type is an IPv6 type, then Layer3HeaderLength must be 40 or greater.
  • If Layer4Type is set to Tcp, then Layer4HeaderLength must be 40 or greater.
  • If Layer4Type is set to Udp, then Layer4HeaderLength must be 8 or greater.
  • The layer type fields must be within the appropriate enum range.

Layout is not used during Tx.

NET_FRAGMENT

NET_FRAGMENT field rules depend on whether the driver is receiving or transmitting, and on whether the fragment buffers are attached to the packets by the driver or by the framework.

Rx or Tx Notes
Rx
  • Client drivers cannot write to the OsReserved_Bounced field.
  • If the driver is not attaching, then Capacity must not be modified but ValidLength and Offset must be modified.
  • If the driver is attaching, then Capacity, ValidLength, and Offset must all be modified.
  • Offset + ValidLength must be less than Capacity.
Tx
  • Client drivers cannot modify any fields except for Scratch.