B.4 WDC Low Level API

B.4 WDC Low Level API
	Appendix B. API Reference

This section described the WDC types and preprocessor definitions defined in the WinDriver/include/wdc_defs.h header file.

B.4.1 WDC_ID_U Union

WDC device ID information union type (used for PCI and PCMCIA devices):

Field	Type	Description
pciId	WD_PCI_ID	PCI device ID information structure [B.5.6]
pcmciaId	WD_PCMCIA_ID	PCMCIA device ID information structure [B.5.7]

B.4.2 WDC_ADDR_DESC Structure

PCI/PCMCIA/ISA device memory or I/O address space information structure type:

Field	Type	Description
dwAddrSpace	DWORD	The address space number
fIsMemory	BOOL	• `TRUE`: memory address space. • `FALSE`: I/O address space.
dwItemIndex	DWORD	The index of the `WD_ITEMS` structure [B.5.10] for the address space, which is retrieved and stored by `WDC_xxxDeviceOpen`() in the `cardReg.Card.Item` array of the relevant WDC device information structure [B.4.3]
dwBytes	DWORD	The address space's size (in bytes)
kptAddr	KPTR	The kernel-mode mapping of the address space's physical base address. This address is used by the WDC API for accessing a memory or I/O region using the low-level `WD_Transfer`() or `WD_MultiTransfer`() APIs (described in the WinDriver PCI Low-Level API Reference), or when accessing memory address directly in the kernel.
dwUserDirectMemAddr	UPTR	The user-mode mapping of a memory address space's physical base address. This address is used for accessing memory addresses directly from the user mode

B.4.3 WDC_DEVICE Structure

PCI/PCMCIA/ISA device information structure type.
The WDC_xxxDeviceOpen() functions (PCI [B.3.10] / PCMCIA [B.3.11] / ISA [B.3.12]) allocate and return device structures of this type.

Field	Type	Description
id	WDC_ID_U	Device ID information union (relevant for PCI and PCMCIA devices) – see [B.4.1]
slot	WDC_SLOT_U	Device location information structure – see description of `WDC_SLOT_U` in section [B.3.1.9]
dwNumAddrSpaces	DWORD	Number of address spaces found on the device
pAddrDesc	WDC_ADDR_DESC*	Array of memory and I/IO address spaces information structures [B.4.2]
cardReg	WD_CARD_REGISTER	WinDriver device resources information structure, returned by the low-level `WD_CardRegister`() function (see the WinDriver PCI Low-Level API Reference), which is called by the `WDC_xxxDeviceOpen`() functions
kerPlug	WD_KERNEL_PLUGIN	Kernel PlugIn driver information structure [B.7.1]. This structure is filled by the `WDC_xxxDeviceOpen`() functions if the caller selects to use a Kernel PlugIn driver (otherwise this structure is not used) and is maintained by the WDC library.
Int	WD_INTERRUPT	Interrupt information structure. This structure is filled by the `WDC_xxxDeviceOpen`() functions for devices that have interrupts, and is maintained by the WDC library.
hIntThread	DWORD	Handle to the interrupt thread that is spawn when interrupts are enabled. This handle is passed by WDC to the low-level WinDriver interrupt APIs. When using the WDC API you do not need to access this handle directly.
Event	WD_EVENT	WinDriver Plug-and-Play and power management events information structure – see `EventRegister`() description in the WinDriver PCI Low-Level API Reference for details.
hEvent	HANDLE	Handle used by the WinDriver `EventRegister`() / `EventUnregister`() functions (see the WinDriver PCI Low-Level API Reference) When using the WDC API you do not need to access this handle directly.
pCtx	PVOID	Device context information. This information is received as a parameter by the `WDC_xxxDeviceOpen`() functions and stored in the device structure for future use by the calling application (optional)

B.4.4 PWDC_DEVICE

Pointer to a WDC_DEVICE structure [B.4.3] type:

typedef WDC_DEVICE *PWDC_DEVICE

B.4.5 WDC_MEM_DIRECT_ADDR Macro

Purpose

• Utility macro that returns a pointer that can be used for direct access to a specified memory address space from the context of the calling process.

Prototype

WDC_MEM_DIRECT_ADDR(pAddrDesc)

Parameters

Name	Type	Input/Output
pAddrDesc	WDC_ADDR_DESC*	Input

Description

Name	Description
pAddrDesc	Pointer to a WDC memory address space information structure [B.4.2]

Return Value

When called from the user mode, returns the user-mode mapping of the physical memory address (pAddrDesc->dwUserDirectMemAddr);
When called from the kernel mode, returns the kernel-mode mapping of the physical memory address (pAddrDesc->kptAddr).
The returned pointer can be used for accessing the memory directly from the user mode or kernel mode, respectively.

B.4.6 WDC_ADDR_IS_MEM Macro

Purpose

• Utility macro that checks if a given address space is a memory or I/O address space.

Prototype

WDC_ADDR_IS_MEM(pAddrDesc)

Parameters

Name	Type	Input/Output
pAddrDesc	WDC_ADDR_DESC*	Input

Description

Name	Description
pAddrDesc	Pointer to a WDC memory address space information structure [B.4.2]

Return Value

Returns pAddrDesc->fIsMemory, which is set to TRUE for a memory address space and to FALSE otherwise.

B.4.7 WDC_GET_ADDR_DESC Macro

Purpose

• Utility macro that retrieves a WDC address space information structure (WDC_ADDR_DESC [B.4.2]), which complies to the specified address space number.

Prototype

WDC_GET_ADDR_DESC(
    pDev,
    dwAddrSpace)

Parameters

Name	Type	Input/Output
pDev	PWDC_DEVICE	Input
dwAddrSpace	DWORD	Input

Description

Name	Description
pDev	Pointer to a WDC device information structure [B.4.4]
dwAddrSpace	Address space number

Return Value

Returns a pointer to the device's address information structure (WDC_ADDR_DESC [B.4.2]) for the specified address space number – pDev->pAddrDesc[dwAddrSpace].

B.4.8 WDC_GET_ENABLED_INT_TYPE Macro

Purpose

• Utility macro for retrieving the value of a WDC device's dwEnabledIntType WD_INTERRUPT field. This field is updated by WDC_IntEnable() [B.3.46] to indicate the interrupt type enabled for the device, as detailed in the description of the macro's return value below.

Prototype

WDC_GET_ENABLED_INT_TYPE(pDev)

Parameters

Name	Type	Input/Output
pDev	PWDC_DEVICE	Input

Description

Name	Description
pDev	Pointer to a WDC device information structure [B.4.4]

Return Value

Returns the interrupt type enabled for the device:

INTERRUPT_MESSAGE_X: Extended Message-Signaled Interrupts (MSI-X).
INTERRUPT_MESSAGE: Message-Signaled Interrupts (MSI).
INTERRUPT_LEVEL_SENSITIVE: Legacy level-sensitive interrupts.
INTERRUPT_LATCHED: Legacy edge-triggered interrupts.
The value of this flag is zero and it is applicable only when no other interrupt flag is set.

Remarks

The Windows and Mac OS X APIs do not distinguish between MSI and MSI-X; therefore, on these OSs the WinDriver functions set the INTERRUPT_MESSAGE flag for both MSI and MSI-X.
Call this macro only after calling WDC_IntEnable() [B.3.46] to enable interrupts on your PCI card.
This macro is normally relevant only in the case of PCI devices that support more than one type of interrupt.
You can pass the returned value to the WDC_INT_IS_MSI macro to check if MSI or MSI-X was enabled [B.4.10].

B.4.9 WDC_GET_INT_OPTIONS Macro

Purpose

• Utility macro for retrieving the value of a WDC device's interrupt options, which indicate the types of interrupts supported by the device, as detailed in the description of the macro's return value below.

Prototype

WDC_GET_INT_OPTIONS(pDev)

Parameters

Name	Type	Input/Output
pDev	PWDC_DEVICE	Input

Description

Name	Description
pDev	Pointer to a WDC device information structure [B.4.4]

Return Value

Returns a bit-mask indicating the types of interrupts supported by the device:

INTERRUPT_MESSAGE_X: Extended Message-Signaled Interrupts (MSI-X).
INTERRUPT_MESSAGE: Message-Signaled Interrupts (MSI).
INTERRUPT_LEVEL_SENSITIVE: Legacy level-sensitive interrupts.
INTERRUPT_LATCHED: Legacy edge-triggered interrupts.
The value of this flag is zero and it is applicable only when no other interrupt flag is set.

Remarks

You can pass the returned options to the WDC_INT_IS_MSI macro to check whether they include the INTERRUPT_MESSAGE (MSI) and/or INTERRUPT_MESSAGE_X (MSI-X) flags [B.4.10].

B.4.10 WDC_INT_IS_MSI Macro

Purpose

• Utility macro that checks whether a given interrupt type bit-mask contains the Message-Signaled Interrupts (MSI) or Extended Message-Signaled Interrupts (MSI-X) interrupt type flags.

Prototype

WDC_INT_IS_MSI(dwIntType)

Parameters

Name	Type	Input/Output
dwIntType	DWORD	Input

Description

Name	Description
dwIntType	Interrupt types bit-mask

Return Value

Returns TRUE if the provided interrupt type bit-mask includes the INTERRUPT_MESSAGE (MSI) and/or INTERRUPT_MESSAGE_X (MSI-X) flags; otherwise returns FALSE.

B.4.11 WDC_GET_ENABLED_INT_LAST_MSG Macro

Purpose

• Utility macro that retrieves the message data of the last received interrupt for the Message-Signaled Interrupts (MSI) / Extended Message-Signaled Interrupts (MSI-X) enabled for the device (Windows Vista and higher only).

Prototype

WDC_GET_ENABLED_INT_LAST_MSG(pDev)

Parameters

Name	Type	Input/Output
pDev	PWDC_DEVICE	Input

Description

Name	Description
pDev	Pointer to a WDC device information structure [B.4.4]

Return Value

If MSI or MSI-X was enabled for the given device, the macro returns the message data of the last message received for the device's interrupt; otherwise returns zero.

B.4.12 WDC_IS_KP Macro

Purpose

• Utility macro that checks if a WDC device uses a Kernel PlugIn driver.

Prototype

WDC_IS_KP(pDev)

Parameters

Name	Type	Input/Output
pDev	PWDC_DEVICE	Input

Description

Name	Description
pDev	Pointer to a WDC device information structure [B.4.4]

Return Value

Returns TRUE if the device uses a Kernel PlugIn driver; otherwise returns FALSE.


B.3 WDC High Level API		B.5 WD_xxx Structures, Types and General Definitions