B.5 WD_xxx Structures, Types and General Definitions

B.5 WD_xxx Structures, Types and General Definitions
	Appendix B API Reference

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

B.5.1 WD_BUS_TYP Enumeration

Bus types enumeration:

Enum Value	Description
WD_BUS_USB	Universal Serial Bus (USB)
WD_BUS_UNKNOWN	Unknown bus
WD_BUS_ISA	ISA bus
WD_BUS_EISA	EISA (ISA Plug-and-Play) bus
WD_BUS_PCI	PCI bus
WD_BUS_PCMCIA	PCMCIA bus

B.5.2 ITEM_TYPE Enumeration

Enumeration of card item types:

Enum Value	Description
ITEM_NONE	Unknown item type
ITEM_INTERRUPT	Interrupt item
ITEM_MEMORY	Memory item
ITEM_IO	I/O item
ITEM_BUS	Bus item

B.5.3 WD_PCMCIA_ACC_SPEED Enumeration

Enumeration of PCMCIA bus access speeds:

Enum Value	Description
WD_PCMCIA_ACC_SPEED_DEFAULT	Use the default PCMCIA bus access speed
WD_PCMCIA_ACC_SPEED_250NS	250 ns
WD_PCMCIA_ACC_SPEED_200NS	200 ns
WD_PCMCIA_ACC_SPEED_150NS	150 ns
WD_PCMCIA_ACC_SPEED_1000NS	100 ns

B.5.4 WD_PCMCIA_ACC_WIDTH Enumeration

Enumeration of PCMCIA bus width:

Enum Value	Description
WD_PCMCIA_ACC_WIDTH_DEFAULT	Use the default PCMCIA bus width
WD_PCMCIA_ACC_WIDTH_8BIT	8-bit
WD_PCMCIA_ACC_WIDTH_16BIT	16-bit

B.5.5 WD_PCMCIA_VPP Enumeration

Enumeration of the PCMCIA controller's Voltage Power Pin (Vpp) power levels:

Enum Value	Description
WD_PCMCIA_VPP_DEFAULT	Use the default power level of the PCMCIA Vpp pin
WD_PCMCIA_VPP_OFF	Set the voltage on the Vpp pin to zero (disable)
WD_PCMCIA_VPP_ON	Set the voltage on the Vpp pin to 12V (enable)
WD_PCMCIA_VPP_AS_VSS	Set the voltage on the Vpp pin to equal that of the Vcc pin

B.5.6 WD_PCI_ID Structure

PCI device identification information structure:

Name	Type	Description
dwVendorId	DWORD	Vendor ID
dwDeviceId	DWORD	Device ID

B.5.7 WD_PCMCIA_ID Structure

PCMCIA device identification information structure:

Name	Type	Description
wManufacturerId	WORD	Manufacturer ID
wCardId	WORD	Device ID

B.5.8 WD_PCI_SLOT Structure

PCI device location information structure:

Name	Type	Description
dwBus	DWORD	PCI Bus number (0 based)
dwSlot	DWORD	Slot number (0 based)
dwFunction	DWORD	Function number (0 based)

B.5.9 WD_PCMCIA_SLOT Structure

PCMCIA device location information structure:

Name	Type	Description
uBus	BYTE	PCMCIA Bus number (0 based)
uSocket	BYTE	Socket number (0 based)
uFunction	BYTE	Function number (0 based)

B.5.10 WD_ITEMS Structure

Card resources information structure:

Name	Type	Description
item	DWORD	Item type – see the `ITEM_TYPE` enumeration [B.5.2]. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
fNotSharable	DWORD	If `TRUE`, only one application at a time can access the memory or I/O range, or monitor the device's interrupts. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
dwOptions	DWORD	A bit-mask of item registration flags, applicable when calling one of the `WDC_xxxDeviceOpen` functions (PCI [B.3.10] / PCMCIA [B.3.11] / ISA [B.3.12]) or the low-level `WD_CardRegister` function (see the WinDriver PCI Low-Level API Reference). The mask can consist of a combination of any of the of the following `WD_ITEM_OPTIONS` enumeration values: • `WD_ITEM_DO_NOT_MAP_KERNEL`: This flag instructs the function to avoid mapping a memory address range to the kernel virtual address space and map the memory only to the user-mode virtual address space. See the Remarks to this function for more information. NOTE: This flag is applicable only to memory items. • `WD_ITEM_ALLOW_CACHE` (Windows and Windows CE): Map the item's physical memory (`I.Mem.dwPhysicalAddr`) 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.
I	union	Union of resources data, based on the item's type (`item`)
• Mem	struct	Memory item data (`item = ITEM_MEMORY`)
* dwPhysicalAddr	DWORD	First address of the physical memory range. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
* dwBytes	DWORD	Length (in bytes) of the memory range. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
* dwTransAddr	DWORD	Kernel-mode mapping of the memory range's physical base address (`dwPhysicalAddr`). 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] / PCMCIA [B.3.11] / ISA [B.3.12]).
* dwUserDirectAddr	DWORD	User-mode mapping of the memory range's physical base address (`dwPhysicalAddr`). 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] / PCMCIA [B.3.11] / ISA [B.3.12]).
* dwCpuPhysicalAddr	DWORD	Translation of the card's physical memory base address (`dwPhysicalAddr`) from bus-specific values to CPU values. 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] / PCMCIA [B.3.11] / ISA [B.3.12]).
* dwBar	DWORD	Base Address Register (BAR) number. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
• IO	struct	I/O item data (`item = ITEM_IO`)
* dwAddr	DWORD	First address of the I/O range. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
* dwBytes	DWORD	Length (in bytes) of the I/O range. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
* dwBar	DWORD	Base Address Register (BAR) number. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
• Int	struct	Interrupt item data (`item = ITEM_INTERRUPT`)
* dwInterrupt	DWORD	Physical interrupt request (IRQ) number. This field is updated by the `WDC_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
* dwOptions	DWORD	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.3. • `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 Vista and higher – see information in section 9.2.3. • `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. NOTES: • For Plug-and-Play hardware (PCI/PCMCIA), use WinDriver's `WDC_PciGetDeviceInfo` [B.3.8] (PCI) or `WDC_PcmciaGetDeviceInfo` [B.3.9] (PCMCIA) function (or the low-level `WD_PciGetCardInfo` or `WD_PcmciaGetCardInfo` 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.
* hInterrupt	DWORD	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] / PCMCIA [B.3.11] / ISA [B.3.12]).
• Bus	WD_BUS	Bus item data (`item = ITEM_BUS`)
* dwBusType	WD_BUS_TYPE	Device's bus type – see the `WD_BUS_TYPE` enumeration [B.5.1]
* dwBusNum	DWORD	Bus Number
* dwSlotFunc	DWORD	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_XXXGetDeviceInfo` functions (PCI: [B.3.8]; PCMCIA: [B.3.9]) or the low-level `WD_PciGetCardInfo` and `WD_PcmciaGetCardInfo` functions (see the WinDriver PCI Low-Level API Reference).
Val	struct	Reserved for internal use

B.5.11 WD_CARD Structure

Card information structure:

Name	Type	Description
dwItems	DWORD	Number of items (resources) on the card
Item	WD_ITEMS [WD_CARD_ITEMS]	Array of card resources (items) information structures [B.5.10]

B.5.12 WD_PCI_CARD_INFO Structure

PCI card information structure:

Name	Type	Description
pciSlot	WD_PCI_SLOT	PCI device location information structure [B.5.8], 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)
Card	WD_CARD	Card information structure [B.5.11]

B.5.13 WD_PCMCIA_CARD_INFO Structure

PCMCIA card information structure:

Name	Type	Description
pcmciaSlot	WD_PCMCIA_SLOT	PCMCIA device location information structure [B.5.9], which can be acquired by calling `WDC_PcmciaScanDevices` [B.3.7] (or the low-level `WD_PcmciaScanCards` function – see the WinDriver PCI Low-Level API Reference)
Card	WD_CARD	Card information structure [B.5.11]
cVersion	CHAR [WD_PCMCIA_VERSION_LEN]	Version string
cManufacturer	CHAR [WD_PCMCIA_ MANUFACTURER_LEN]	Manufacturer string
cProductName	CHAR [WD_PCMCIA_ PRODUCTNAME_LEN]	Product string
wManufacturerId	WORD	Manufacturer ID
wCardId	WORD	Device ID
wFuncId	WORD	Function ID

B.5.14 WD_DMA Structure

Direct Memory Access (DMA) information structure:

Name	Type	Description
hDma	DWORD	DMA buffer handle (or 0 for a failed allocation). This handle is returned from `WDC_DMAContigBufLock` [B.3.39] and `WDC_DMASGBufLock` [B.3.40] (or from the low-level `WD_DMALock` function – see the WinDriver PCI Low-Level API Reference)
pUserAddr	PVOID	User-mode mapped address of the DMA buffer. This mapping is returned from `WDC_DMAContigBufLock` [B.3.39] and `WDC_DMASGBufLock` [B.3.40] (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.
pKernelAddr	KPTR	Kernel-mode mapped address of the DMA buffer. This mapping is returned from `WDC_DMAContigBufLock` [B.3.39] and `WDC_DMASGBufLock` [B.3.40] (on Windows 7/Vista/Server 2008/Server 2003/XP/2000), or from the low-level `WD_DMALock` function (for Contiguous Buffer DMA and for Scatter/Gather DMA on Windows 7/Vista/Server 2008/Server 2003/XP/2000 – see the WinDriver PCI Low-Level API Reference)
dwBytes	DWORD	The size of the DMA buffer (in bytes)
dwOptions	DWORD	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.39] sets it automatically, and `WDC_DMASGBufLock` [B.3.40] 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.39] 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.40] sets it automatically when called to allocate a large DMA buffer, and `WDC_DMAContigBufLock` [B.3.39] 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, if supported by the target platform. This flag is supported on Windowsand Linux.
dwPages	DWORD	Number of physical memory blocks used for the allocated buffer. For Contiguous Buffer DMA this field is always set to 1.
hCard	DWORD	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
Page	WD_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`).
• pPhysicalAddr	KPTR	The page's physical address
• dwBytes	DWORD	The page's size (in bytes)

B.5.15 WD_TRANSFER Structure

Memory/IO read/write transfer command information structure:

Name	Type	Description
cmdTrans	DWORD	A value indicating the type of transfer to perform – see 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.46] 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 `pTransCmdsWD_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`).">
dwPort	KPTR	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].kptAddr` (where i is the index of the desired address space). (When using the low-level `WD_xxx` APIs, these values are stored within the `dwAddr` (I/O) and `dwTransAddr` (memory) fields of the relevant `cardReg.Card.Item[i]` item – see the WinDriver PCI Low-Level API Reference).
dwBytes	DWORD	The number of bytes to transfer
fAutoinc	DWORD	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.
dwOptions	DWORD	Must be zero
Data	union	The data buffer for the transfer (input for write commands, output for read commands):
• Byte	BYTE	Used for 8-bit transfers
• Word	WORD	Used for 16-bit transfers
• Dword	UINT32	Used for 32-bit transfers
• Qword	UINT64	Used for 64-bit transfers
• pBuffer	PVOID	Used for string (block) transfers – a pointer to the data buffer for the transfer


B.4 WDC Low Level API		B.6 Kernel PlugIn Kernel-Mode Functions