NET_ADAPTER_RX_CAPABILITIES structure (netadapter.h)

  • Article

The NET_ADAPTER_RX_CAPABILITIES structure describes the receive capabilities of a net adapter.

Syntax

typedef struct _NET_ADAPTER_RX_CAPABILITIES {
  ULONG                                  Size;
  NET_RX_FRAGMENT_BUFFER_ALLOCATION_MODE AllocationMode;
  NET_RX_FRAGMENT_BUFFER_ATTACHMENT_MODE AttachmentMode;
  UINT32                                 FragmentRingNumberOfElementsHint;
  SIZE_T                                 MaximumFrameSize;
  SIZE_T                                 MaximumNumberOfQueues;
  union {
    struct {
      PFN_NET_ADAPTER_RETURN_RX_BUFFER EvtAdapterReturnRxBuffer;
    } DUMMYSTRUCTNAME;
    struct {
      NET_MEMORY_MAPPING_REQUIREMENT MappingRequirement;
      SIZE_T                         FragmentBufferAlignment;
      NET_ADAPTER_DMA_CAPABILITIES   *DmaCapabilities;
    } DUMMYSTRUCTNAME2;
  } DUMMYUNIONNAME;
} NET_ADAPTER_RX_CAPABILITIES;

Members

Size

The size of this structure, in bytes.

AllocationMode

A NET_RX_FRAGMENT_BUFFER_ALLOCATION_MODE value that specifies how the operating system should allocate receive buffers.

UMDF drivers must set this value to NetRxFragmentBufferAllocationModeSystem.

AttachmentMode

A NET_RX_FRAGMENT_BUFFER_ATTACHMENT_MODE value that specifies how the operating system should pre-attach receive buffers.

UMDF drivers must set this value to NetRxFragmentBufferAttachmentModeSystem.

FragmentRingNumberOfElementsHint

A hint indicating how many elements the adapter wants for each receive queue's ring buffer of NET_FRAGMENTs. This member must be a power of 2.

MaximumFrameSize

The maximum frame size, in bytes, that the adapter can receive. This value should include the maximum transmission unit (MTU) size that your hardware supports for an IP packet, plus additional space your driver might need for packet metadata. For more information, see the receive example in the Remarks section of EVT_PACKET_QUEUE_ADVANCE.

MaximumNumberOfQueues

The maximum number of receive queues that the adapter supports.

DUMMYUNIONNAME

A union that contains the following members:

DUMMYUNIONNAME.DUMMYSTRUCTNAME

A struct that contains the following member:

DUMMYUNIONNAME.DUMMYSTRUCTNAME.EvtAdapterReturnRxBuffer

A pointer to the driver's EVT_NET_ADAPTER_RETURN_RX_BUFFER callback function. This member is required if the AllocationMode member is set to NetRxFragmentBufferAllocationModeDriver for the operating system to invoke once the system is finished with the receive buffer.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2

A struct that contains the following members:

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.MappingRequirement

A NET_MEMORY_MAPPING_REQUIREMENT value that specifies how the operating system should map receive data buffers.

UMDF drivers must set MappingRequirement to NetMemoryMappingRequirementNone.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.FragmentBufferAlignment

The minimum alignment for packet fragments. This member must be a power of 2.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.DmaCapabilities

A pointer to a driver-allocated and initialized NET_DMA_CAPABILITIES structure that describes the adapter's DMA capabilities on the receive path. This member is ignored by NetAdapterCx if MappingRequirement is not set to NetMemoryMappingRequirementDmaMapped.

UMDF NetAdapterCX doesn't support DmaCapabilities. UMDF drivers must set this member to NULL.

Remarks

Call one of the NET_ADAPTER_RX_CAPABILITIES_INIT_XXX functions to initialize this structure. For more info about each initialization function, see the links in the See Also section. An initialized NET_ADAPTER_RX_CAPABILITIES structure is passed as a parameter to NetAdapterSetDatapathCapabilities.

Typically, a client driver either performs both allocation and attachment itself or specifies that the operating system perform both. In most cases, we recommend that the operating system allocates and attaches receive buffers.

If the client does specify driver-allocated and attached receive buffers, it must supply both a custom return context structure in the RxBufferReturnContext member of each NET_FRAGMENT during buffer allocation, as well as an EVT_NET_ADAPTER_RETURN_RX_BUFFER callback function in this NET_ADAPTER_RX_CAPABILITIES structure for the operating system to invoke once it has finished with the buffer.

Requirements

Requirement Value
Minimum KMDF version 1.25
Minimum UMDF version 2.33
Header netadapter.h (include netadaptercx.h)

See also

NET_ADAPTER_RX_CAPABILITIES_INIT_DRIVER_MANAGED

NET_ADAPTER_RX_CAPABILITIES_INIT_SYSTEM_MANAGED

NET_ADAPTER_RX_CAPABILITIES_INIT_SYSTEM_MANAGED_DMA

NetAdapterSetDatapathCapabilities