NET_DMA_DESCRIPTOR structure (netdma.h)
Syntax
typedef struct _NET_DMA_DESCRIPTOR {
union {
ULONG TransferSize;
struct {
ULONG DCAContext : 32;
} DCAContext32;
struct {
ULONG DCAContext : 16;
ULONG Reserved : 16;
} DCAContext16;
struct {
ULONG DCAContext : 8;
ULONG Reserved : 24;
} DCAContext8;
};
ULONG ControlFlags;
PHYSICAL_ADDRESS SourceAddress;
PHYSICAL_ADDRESS DestinationAddress;
PHYSICAL_ADDRESS NextDescriptor;
union {
ULONG64 Reserved1;
PHYSICAL_ADDRESS NextSourceAddress;
};
union {
ULONG64 Reserved2;
PHYSICAL_ADDRESS NextDestinationAddress;
};
ULONG64 UserContext1;
ULONG64 UserContext2;
} NET_DMA_DESCRIPTOR, *PNET_DMA_DESCRIPTOR;
Members
TransferSize
The size, in bytes, of the memory block that is associated with this DMA descriptor.
NetDMA 2.0 and later provider drivers use the DCAContext32, DCAContext16, and DCAContext8 members of the union with TransferSize to support Direct Cache Access (DCA).
DCAContext32
A 32 bit DCA context.
DCAContext32.DCAContext
A DCA context.
DCAContext16
A 16 bit DCA context.
DCAContext16.DCAContext
A DCA context.
DCAContext16.Reserved
Reserved bits.
DCAContext8
An 8 bit DCA context.
DCAContext8.DCAContext
A DCA context.
DCAContext8.Reserved
Reserved bits.
ControlFlags
A set of flags that specify the operations that the DMA engine should perform for this DMA descriptor. This member must contain one or more of the following values (combined with a bitwise OR operation):
| Unless otherwise noted, descriptions apply to when the bit is set. | Meaning |
|---|---|
|
A NetDMA version 2.0 or later provider starts the copy from the source physical address that is specified in the SourceAddress member and when it reaches the end of the first page, it continues the copy from the physical address that is specified in the NextSourceAddress member. |
|
A NetDMA version 2.0 or later provider starts the copy to the destination physical address that is specified in the DestinationAddress member and when it reaches the end of the first page, it continues the copy to the physical address that is specified in the NextDestinationAddress member. |
|
The DMA engine should identify the descriptor as a
context change descriptor.
The NetDMA interface submits a context change descriptor to DCA-capable NetDMA providers to set the DCA target processor of the destination data for all of the DMA transfers on a NetDMA channel. The NetDMA interface uses the DCAContext8 member in a context change descriptor to specify the 8-bit advanced programmable interrupt controller (APIC) identifier of the target processor for the channel. A DCA-capable NetDMA provider must keep the DCA affinity of a DMA channel with a processor as long as it has not received a new context change descriptor. The NetDMA interface submits a context change descriptor one time after the channel has been allocated and again when NetDMA detects that the DMA provider might have lost the hardware context (for example, after a suspend and resume operation). |
|
If the DMA operation type is a standard DMA transfer, the DMA engine should send a DCA hint for
the destination data to the DCA target processor that has been assigned to the DMA channel.
To set the DCA target processor of a DMA channel, the NetDMA interface previously submitted a context change descriptor to that channel. |
|
The DMA engine should generate an interrupt for the associated DMA channel after it processes
this DMA descriptor.
When this bit is cleared, the DMA engine does not generate an interrupt. |
|
The source address should not be snooped.
When this bit is cleared, the source address is in coherent memory space, and each CPU cache line must be snooped. The DMA client must verify that snooping of CPU caches is not required for proper DMA operation. |
|
The destination address should not be snooped.
When this bit is cleared, the destination address is in coherent memory space, and each CPU cache line must be snooped. The DMA client must verify that snooping of CPU caches is not required for proper DMA operation. |
|
The
CompletionVirtualAddress and
CompletionPhysicalAddress members in the
NET_DMA_CHANNEL_PARAMETERS structure reference a completion status value. The DMA engine updates
the completion status value when it completes the processing of this descriptor.
The completion status value is a 64-bit-wide combination of the physical address of the most recent DMA descriptor that the DMA engine processed, and additional status information. When this bit is cleared, the DMA engine does not use CompletionVirtualAddress or CompletionPhysicalAddress. |
|
The DMA engine guarantees that all writes for this descriptor, including data and completion
status, are complete before it reads the data for the next descriptor.
When this bit is cleared, the DMA engine can start processing the next descriptor before it completes the processing of this descriptor. |
|
A DMA transfer is not required for this descriptor. The DMA engine is not required to check the
TransferSize,
SourceAddress, or
DestinationAddress members.
When this bit is cleared, a DMA transfer might be required or it might be a zero-length transfer. The DMA engine must check the TransferSize, SourceAddress, or DestinationAddress members. Note If this bit is set or cleared, the NetDMA client must always ensure that the descriptor defines
valid transfer parameters.
|
The following bitmasks identify the remaining bits in the ControlFlags member:
SourceAddress
The physical address of a memory block that is a source for the DMA transfer.
DestinationAddress
The physical address of a memory block that is a destination for the DMA transfer.
NextDescriptor
The physical address of the next NET_DMA_DESCRIPTOR structure in the linked list of descriptors. If this descriptor is the last descriptor in the list, NextDescriptor is NULL.
Reserved1
A ULONG64 value that is reserved for the DMA engine or the DMA provider driver to use. NetDMA 2.0 and later provider drivers use the NextSourceAddress member of the union with Reserved1 to support Source and Destination Page Break.
NextSourceAddress
The physical address of the second page of source address that is used in source page break.
Reserved2
A ULONG64 value that is reserved for use the DMA engine or the DMA provider driver to use. NetDMA 2.0 and later provider drivers use the NextDestinationAddress member of the union with Reserved2 to support Source and Destination Page Break.
NextDestinationAddress
The physical address of the second page of destination address that is used in destination page break.
UserContext1
A ULONG64 value that is reserved for the NetDMA interface to use.
UserContext2
A ULONG64 value that is reserved for the NetDMA interface to use.
Remarks
The NET_DMA_DESCRIPTOR structure specifies the source, destination, and control information for a single DMA transfer in a linked list of DMA descriptors.
To start a DMA transfer, the NetDMA interface supplies the physical address of a NET_DMA_DESCRIPTOR structure at the DescriptorPhysicalAddress parameter of the DMA provider driver's ProviderStartDma function. The DescriptorVirtualAddress parameter contains the virtual address of the descriptor.
The NextDescriptor member of a NET_DMA_DESCRIPTOR structure contains the physical address of the next NET_DMA_DESCRIPTOR structure in the linked list of descriptors.
The NetDMA interface calls a DMA provider driver's ProviderAppendDma function to append a linked list of DMA descriptors after the last descriptor on a DMA channel.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Supported for NetDMA 2.0 drivers in Windows Server 2008. (Added NextSourceAddress, NextDestinationAddress, DCAContext32, DCAContext16, and DCAContext8 members.) Supported for NetDMA 1.1 drivers in Windows Server 2008. Supported for NetDMA 1.0 drivers in Windows Server 2008 and Windows Vista. |
| Header | netdma.h (include Netdma.h) |