B.7. WD_xxx Structures, Types and General Definitions

This section describes basic WD_xxx structures and types, which are used by the WDC_xxx & WDS_xxx APIs. The APIs described in this section are defined in the WinDriver/include/windrvr.h header file.

B.7.1. WD_BUS_TYPE Enumeration

Bus types enumeration.

Enum ValueDescription
WD_BUS_USBUniversal Serial Bus (USB)
WD_BUS_UNKNOWNUnknown bus
WD_BUS_ISAISA bus
WD_BUS_EISAEISA (ISA Plug-and-Play) bus
WD_BUS_PCIPCI bus

B.7.2. ITEM_TYPE Enumeration

Enumeration of card item types.

Enum ValueDescription
ITEM_NONEUnknown item type
ITEM_INTERRUPTInterrupt item
ITEM_MEMORYMemory item
ITEM_IOI/O item
ITEM_BUSBus item

B.7.3. WD_PCI_ID Structure

PCI device identification information structure.

FieldTypeDescription
dwVendorIdDWORDVendor ID
dwDeviceIdDWORDDevice ID

B.7.4. WD_PCI_SLOT Structure

PCI device location information structure.

FieldTypeDescription
dwBusDWORDPCI Bus number (0 based)
dwSlotDWORDSlot number (0 based)
dwFunctionDWORDFunction number (0 based)

B.7.5. WD_PCI_CAP Structure

PCI capability information structure.

FieldTypeDescription
dwCapIdDWORDPCI capability ID
dwCapOffsetDWORDPCI capability register offset

B.7.6. WD_ITEMS Structure

Card resources information structure.

FieldTypeDescription
itemDWORD Item type — see the ITEM_TYPE enumeration [B.7.2].
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9], or the low-levelWD_PciGetCardInfo() functions (see the WinDriver PCI Low-Level API Reference).
fNotSharableDWORD
  • 1 — Non-sharable resource; should be locked for exclusive use
  • 0 — Sharable resource
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function, and can be modified manually before registering the resources using the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]) or the low-level WD_CardRegister() function; (the low-level functions are documented in the WinDriver PCI Low-Level API Reference).
Iunion Union of resources data, based on the item's type (item)
• Memstruct Memory-item descriptor (item=ITEM_MEMORY)
 * pPhysicalAddrPHYS_ADDR First address of the physical memory range.
For Plug-and-Play hardware (PCI) this field is updated by the WDC_PCIGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
NOTE: In the case of a 64-bit memory BAR the value set in this field by may be incorrect, due to the 32-bit field size. For this reason, WDC_PciDeviceOpen() [B.3.10] ignores this field and retrieves the physical address directly from the card (as does the low-level WD_CardRegister() function).
 * qwBytesUINT64 Length (in bytes) of the memory range.
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
 * pTransAddrKPTR Kernel-mode mapping of the memory range's physical base address.
This field is updated by WD_CardRegister() (see the WinDriver PCI Low-Level API Reference), which is called from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]).
 * pUserDirectAddrUPTR User-mode mapping of the memory range's physical base address.
This field is updated by WD_CardRegister() (see the WinDriver PCI Low-Level API Reference), which is called from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]).
 * dwBarDWORD Base Address Register (BAR) number.
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
 * pReservedKPTRReserved for internal use
 * dwOptionsDWORD A bit-mask of memory-item registration flags, applicable when calling one of the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]) or the low-level WD_CardRegister() function (see the WinDriver PCI Low-Level API Reference) — a combination of any of the of the following WD_ITEM_MEM_OPTIONS enumeration values:
  • WD_ITEM_MEM_DO_NOT_MAP_KERNEL: Avoid mapping the item's physical memory to the kernel address space (I.Mem.pTransAddr not set); map the memory only to the user-mode virtual address space (mapped base address: I.Mem.pUserDirectAddr). For more information, refer to Remark 2 in the documentation of WDC_PciDeviceOpen() [B.3.10]; (a similar remark is found in the documentation of the other device-open functions).
    NOTE: This flag is applicable only to memory items.
  • WD_ITEM_MEM_ALLOW_CACHE (Windows and Windows CE): Map the item's physical memory (base address: I.Mem.pPhysicalAddr) as cached.
    NOTE: This flag is applicable only to memory items that pertain to the host's RAM, as opposed to local memory on the card.
  • WD_ITEM_MEM_CE_MAP_VIRTUAL (Windows CE) — Perform the kernel mapping of the physical memory (mapped base address: I.Mem.pTransAddr) to non-static virtual system addresses, as opposed to the default static kernel address mapping.
    NOTE: Do not set this flag for items that need to be accessed in kernel mode — namely, items that will be used to create interrupt transfer commands or items that will be accessed from a Kernel PlugIn driver.
    NOTE: This flag is applicable only to memory items.
• IOstruct I/O-item descriptor (item=ITEM_IO)
 * pAddrKPTR First address of the I/O range.
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
 * dwBytesDWORD Length (in bytes) of the I/O range.
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
 * dwBarDWORD Base Address Register (BAR) number.
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
• Intstruct Interrupt-item descriptor (item=ITEM_INTERRUPT)
 * dwInterruptDWORD Physical interrupt request (IRQ) number.
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).
 * dwOptionsDWORD Interrupt bit-mask, which can consist of a combination of any of the following flags:
Interrupt type flags:
INTERRUPT_MESSAGE_X — Indicates that the hardware supports Extended Message-Signaled Interrupts (MSI-X).
This option is applicable only to PCI cards on Linux — see information in Section 9.2.4.
INTERRUPT_MESSAGE — On Linux, indicates that the hardware supports Message-Signaled Interrupts (MSI).
On Windows, indicates that the hardware supports MSI or MSI-X.
This option is applicable only to PCI cards on Linux and Windows 7 and higher — see information in Section 9.2.4.
INTERRUPT_LEVEL_SENSITIVE — Indicates that the hardware supports level-sensitive interrupts.
INTERRUPT_LATCHED — indicates that the device supports legacy edge-triggered interrupts. The value of this flag is zero, therefore it is applicable only when no other interrupt flag is set.
NOTE:
For Plug-and-Play hardware (PCI), use WinDriver's WDC_PciGetDeviceInfo() [B.3.9] (or the low-level WD_PciGetCardInfo() function) to retrieve the Plug-and-Play hardware information, including the supported interrupt types.
For non-Plug-and-Play hardware, the relevant interrupt type flag (normally — INTERRUPT_LATCHED) should be set by the user in the call to WDC_IsaDeviceOpen() or to the low-level WD_CardRegister() function. Miscellaneous interrupt options:
INTERRUPT_CE_INT_ID — On Windows CE (unlike other operating systems), there is an abstraction of the physical interrupt number to a logical one. Setting this flag within the resources information passed to the relevant WDC_xxxDeviceOpen() function will instruct WinDriver to refer to the dwInterrupt value as a logical interrupt number and convert it to a physical interrupt number.
 * hInterruptDWORD Handle to an internal WinDriver interrupt structure, required by the low-level WD_xxx() WinDriver interrupt APIs (see the WinDriver PCI Low-Level API Reference).
This field is updated by WD_CardRegister() (see the WinDriver PCI Low-Level API Reference), which is called from the WDC_xxxDeviceOpen() functions (PCI [B.3.10] / ISA [B.3.11]).
 * dwReserved1DWORDReserved for internal use
 * pReserved2KPTRReserved for internal use
• BusWD_BUS Bus-item descriptor (item=ITEM_BUS)
 * dwBusTypeWD_BUS_TYPE Device's bus type — see the WD_BUS_TYPE enumeration [B.7.1]
 * dwBusNumDWORDBus Number
 * dwSlotFuncDWORD Slot/socket and function information for the device: The lower three bits represent the function number and the remaining bits represent the slot/socket number. For example: a value of 0x80 (<=> 10000000 binary) corresponds to a function number of 0 (lower 3 bits: 000) and a slot/socket number of 0x10 (remaining bits: 10000).
This field is updated by the WDC_PciGetDeviceInfo() function  [B.3.9] or the low-level WD_PciGetCardInfo() function (see the WinDriver PCI Low-Level API Reference).

B.7.7. WD_CARD Structure

Card information structure.

FieldTypeDescription
dwItemsDWORDNumber of items (resources) on the card
ItemWD_ITEMS[WD_CARD_ITEMS] Array of card resources (items) information structures [B.7.6]

B.7.8. WD_PCI_CARD_INFO Structure

PCI card information structure.

FieldTypeDescription
pciSlotWD_PCI_SLOT PCI device location information structure [B.7.4], which can be acquired by calling WDC_PciScanDevices() [B.3.4] (or the low-level WD_PciScanCards() function — see the WinDriver PCI Low-Level API Reference)
CardWD_CARDCard information structure [B.7.7]

B.7.9. WD_DMA Structure

Direct Memory Access (DMA) information structure.

FieldTypeDescription
hDmaDWORD DMA buffer handle (or 0 for a failed allocation). This handle is returned from WDC_DMAContigBufLock() [B.3.33] and WDC_DMASGBufLock() [B.3.34] (or from the low-level WD_DMALock() function — see the WinDriver PCI Low-Level API Reference)
pUserAddrPVOID User-mode mapped address of the DMA buffer. This mapping is returned from WDC_DMAContigBufLock() [B.3.33] and WDC_DMASGBufLock() [B.3.34] (in this function the pBuf user-mode buffer provided by the caller is used), or from the low-level WD_DMALock() function (see the WinDriver PCI Low-Level API Reference). Note: if the DMA_KERNEL_ONLY flag was set in the DMA options bit-mask field (dwOptions), this field is not updated.
pKernelAddrKPTR Kernel-mode mapped address of the DMA buffer. This mapping is returned from WDC_DMAContigBufLock() [B.3.33] and WDC_DMASGBufLock() [B.3.34] (on Windows), or from the low-level WD_DMALock() function (for contiguous-buffer DMA and for Scatter/Gather DMA on Windows — see the WinDriver PCI Low-Level API Reference)
dwBytesDWORDThe size of the DMA buffer (in bytes)
dwOptionsDWORD

DMA options bit-mask, which can consist of a combination of any of the enumeration values listed below.

NOTE: Options that are also applicable to the WDC_DMASGBufLock() and WDC_DMAContigBufLock() functions (according to the descriptions below) should be set within these functions' dwOptions parameter. The dwOptions field of the WD_DMA structure returned by these functions will be updated accordingly.
DMA flags:

DMA_FROM_DEVICE: Synchronize the DMA buffer for transfers from the device to memory.
DMA_TO_DEVICE: Synchronize the DMA buffer for transfers from memory to the device.
DMA_TO_FROM_DEVICE: Synchronize the DMA buffer for transfers in both directions — i.e., from the device to memory and from memory to the device (<=> DMA_FROM_DEVICE | DMA_TO_DEVICE).
DMA_KERNEL_BUFFER_ALLOC: Allocate a contiguous DMA buffer in the physical memory.
The default behavior (when this flag is not set) is to allocate a Scatter/Gather DMA buffer.
Set this flag when calling the low-level WD_DMALock() function to allocate a contiguous DMA buffer (see the WinDriver PCI Low-Level API Reference).
When using the WDC APIs there is no need to set this flag, since WDC_DMAContigBufLock() [B.3.33] sets it automatically, and WDC_DMASGBufLock() [B.3.34] is used to allocate Scatter/Gather DMA buffers, for which this flag is not applicable.
DMA_KBUF_BELOW_16M: Allocate the physical DMA buffer within the first 16MB of the main memory.
This flag is applicable only to contiguous-buffer DMA — i.e., when calling WDC_DMAContigBufLock() [B.3.33] or when calling the low-level WD_DMALock() flag with the DMA_KERNEL_BUFFER_ALLOC flag (see the WinDriver PCI Low-Level API Reference).
DMA_LARGE_BUFFER: Enable locking of a large DMA buffer — dwBytes > 1MB.
This flag is applicable only to Scatter/Gather DMA.
Set this flag when calling the low-level WD_DMALock() function to allocate a large DMA buffer (see the WinDriver PCI Low-Level API Reference).
When using the WDC APIs there is no need to set this flag, since WDC_DMASGBufLock() [B.3.34] sets it automatically when called to allocate a large DMA buffer, and WDC_DMAContigBufLock() [B.3.33] is used to allocate contiguous DMA buffers, for which this flag is not applicable.
DMA_ALLOW_CACHE: Allow caching of the DMA buffer.
DMA_KERNEL_ONLY_MAP: Do not map the allocated DMA buffer to the user mode (i.e., map it to kernel-mode only).
This flag is applicable only in cases where the DMA_KERNEL_BUFFER_ALLOC flag is applicable — see above.
DMA_ALLOW_64BIT_ADDRESS: Allow allocation of 64-bit DMA addresses. This flag is supported on Windows and Linux.
dwPagesDWORD Number of physical memory blocks used for the allocated buffer.
For contiguous-buffer DMA this field is always set to 1.
hCardDWORD Low-level WinDriver card handle, which is acquired by WDC_xxxDeviceOpen() (by calling WD_CardRegister() — see the WinDriver PCI Low-Level API Reference) and stored in the WDC device structure
PageWD_DMA_PAGE[WD_DMA_PAGES] Array of physical memory pages information structures.
For contiguous buffer DMA this array always holds only one element (see dwPages).
• pPhysicalAddrDMA_ADDRThe page's physical address
• dwBytesDWORDThe page's size (in bytes)

B.7.10. WD_TRANSFER Structure

Memory/IO read/write transfer command information structure.

FieldTypeDescription
cmdTransDWORD

A value indicating the type of transfer to perform — refer to the definition of the WD_TRANSFER_CMD enumeration in windrvr.h.

The transfer command can be of either of the following types:

• A read/write transfer command that conforms to the following format: <dir><p>_[S]<size>
Explanation:
<dir>: R for read, W for write
<p>: P for I/O, M for memory
<S>: signifies a string (block) transfer, as opposed to a single transfer
<size>: BYTE, WORD, DWORD or QWORD

CMD_MASK: This command is applicable when passing interrupt transfer commands to the interrupt enable functions (WDC_IntEnable() [B.3.41] or the low-level InterruptEnable() or WD_IntEnable() functions — see the WinDriver PCI Low-Level API Reference).
CMD_MASK is an interrupt mask command for determining the source of the interrupt: When this command is set, upon the arrival of an interrupt in the kernel WinDriver masks the value of the previous read command in the WD_TRANSFER commands array with the mask that is set in the relevant Data field union member of the mask transfer command. For example, for a pTransCmds WD_TRANSFER array, if pTransCmds[i-1].cmdTrans is RM_BYTE, WinDriver performs the following mask: pTransCmds[i-1].Data.Byte & pTransCmds[i].Data.Byte. If the mask is successful, the driver claims ownership of the interrupt and when the control is returned to the user mode, the interrupt handler routine that was passed to the interrupt enable function is invoked; otherwise, the driver rejects ownership of the interrupt, the interrupt handler routine is not invoked and the subsequent transfer commands in the array are not executed.
(Acceptance and rejection of the interrupt is relevant only when handling legacy interrupts; since MSI/MSI-X interrupts are not shared, WinDriver will always accept control of such interrupts.)
NOTE: A CMD_MASK command must be preceded by a read transfer command (RM_XXX / RP_XXX).

pPortKPTR The I/O port address or the kernel-mapped virtual memory address, which has been stored in the relevant device (WDC_DEVICE [B.4.3]): dev.pAddrDesc[i].pAddr (where i is the index of the desired address space). (When using the low-level WD_xxx() APIs, these values are stored within the pAddr (I/O) and pTransAddr (memory) fields of the relevant cardReg.Card.Item[i] item — see the WinDriver PCI Low-Level API Reference).
dwBytesDWORDThe number of bytes to transfer
fAutoincDWORD Relevant only for string (block) transfers:
If TRUE, the I/O or memory port/address will be incremented after each block that is transferred;
If FALSE, all data is transferred to/from the same port/address.
dwOptionsDWORDMust be zero
Dataunion The data buffer for the transfer (input for write commands, output for read commands):
• ByteBYTEUsed for 8-bit transfers
• WordWORDUsed for 16-bit transfers
• DwordUINT32Used for 32-bit transfers
• QwordUINT64Used for 64-bit transfers
• pBufferPVOID Used for string (block) transfers — a pointer to the data buffer for the transfer

B.7.11. WD_KERNEL_BUFFER Structure

Kernel buffer information structure.

FieldTypeDescription
hKerBufDWORD Kernel buffer handle (or 0 for a failed allocation). This handle is returned from WDS_SharedBufferAlloc() [B.6.1] (or from the low-level WD_KernelBufLock() function — see the WinDriver PCI Low-Level API Reference)
dwOptionsDWORD

Kernel buffer options bit-mask, which can consist of a combination of any of the enumeration values listed below.

ALLOCATE_CONTIG_BUFFER:Allocates a physically contiguous buffer
ALLOCATE_CACHED_BUFFER:Allocates a cached buffer

qwBytesUINT64The requested buffer size (in bytes)
pKernelAddrKPTR Kernel-mode mapped address of the kernel buffer. This mapping is returned from WDS_SharedBufferAlloc() [B.6.1], or from the low-level WD_KernelBufLock() function (see the WinDriver PCI Low-Level API Reference)
pUserAddrUPTR User-mode mapped address of the kernel buffer. This mapping is returned from WDS_SharedBufferAlloc() [B.6.1] (or from the low-level WD_KernelBufLock() function (see the WinDriver PCI Low-Level API Reference).