B.4.WDC Low-Level API

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 (used for PCI devices).

FieldTypeDescription
pciIdWD_PCI_IDPCI device ID information structure[B.7.3]

B.4.2.WDC_ADDR_DESC Structure

PCI/ISA device memory or I/O address space information structure.

FieldTypeDescription
dwAddrSpaceDWORDThe address space number
fIsMemoryBOOLTRUE: memory address space.
FALSE: I/O address space.
dwItemIndexDWORD The index of the WD_ITEMS structure[B.7.6] 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]
dwBytesDWORDThe address space's size (in bytes)
pAddrKPTR 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.
pUserDirectMemAddrUPTR 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/ISA device information structure.
The WDC_xxxDeviceOpen() functions (PCI[B.3.10] / ISA[B.3.11]) allocate and return device structures of this type.

FieldTypeDescription
idWDC_ID_U Device ID information union (relevant for PCI devices) — see[B.4.1]
slotWDC_SLOT_U Device location information structure — see description of WDC_SLOT_U in SectionB.3.1.9
dwNumAddrSpacesDWORDNumber of address spaces found on the device
pAddrDescWDC_ADDR_DESC* Array of memory and I/IO address spaces information structures[B.4.2]
cardRegWD_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
kerPlugWD_KERNEL_PLUGIN Kernel PlugIn driver information structure[B.9.1].
This structure is filled by the functions used to open a handle to a Kernel PlugIn for a WDC_DEVICE[12.4] — either WDC_KernelPlugInOpen() [B.3.15], or one of the WDC_xxxDeviceOpen() functions (PCI[B.3.10] / ISA[B.3.11]) when called with the name of a Kernel PlugIn driver — and is maintained by the WDC library.
If no Kernel PlugIn handle was opened for the device, this structure is not used.
IntWD_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.
hIntThreadDWORD 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.
EventWD_EVENT WinDriver Plug-and-Play and power management events information structure — see EventRegister() description in the WinDriver PCI Low-Level API Reference for details.
hEventHANDLE 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.
pCtxPVOID 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].

typedef WDC_DEVICE *PWDC_DEVICE

[Note]
The wdc_defs.h macros cast WDC device pointer parameters (pDev) to PWDC_DEVICE. You may also pass WDC_DEVICE_HANDLE[B.3.1.1] variables for such parameters.

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
NameTypeInput/Output
pAddrDescWDC_ADDR_DESC*Input
Description
NameDescription
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->pUserDirectMemAddr);
When called from the kernel mode, returns the kernel-mode mapping of the physical memory address (pAddrDesc->pAddr).
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
NameTypeInput/Output
pAddrDescWDC_ADDR_DESC*Input
Description
NameDescription
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
NameTypeInput/Output
pDevPWDC_DEVICEInput
dwAddrSpaceDWORDInput
Description
NameDescription
pDev Pointer to a WDC device information structure[B.4.4]
dwAddrSpaceAddress 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_ADDR_SPACE_SIZE Macro

Purpose

Utility macro that retrieves a WDC address space size

Prototype
WDC_GET_ADDR_DESC(
    pDev,
    dwAddrSpace)
Parameters
NameTypeInput/Output
pDevPWDC_DEVICEInput
dwAddrSpaceDWORDInput
Description
NameDescription
pDev Pointer to a WDC device information structure[B.4.4]
dwAddrSpaceAddress space number
Return Value

Returns the size of the specified address space number

B.4.9.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.41] 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
NameTypeInput/Output
pDevPWDC_DEVICEInput
Description
NameDescription
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 APIs do not distinguish between MSI and MSI-X; therefore, on this OS the WinDriver functions set the INTERRUPT_MESSAGE flag for both MSI and MSI-X.
  • Call this macro only after calling WDC_IntEnable()[B.3.41] 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.11].

B.4.10.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
NameTypeInput/Output
pDevPWDC_DEVICEInput
Description
NameDescription
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.11].

B.4.11.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
NameTypeInput/Output
dwIntTypeDWORDInput
Description
NameDescription
dwIntTypeInterrupt 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.12.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 (on Linux and Windows 7 and higher).

Prototype
WDC_GET_ENABLED_INT_LAST_MSG(pDev)
Parameters
NameTypeInput/Output
pDevPWDC_DEVICEInput
Description
NameDescription
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.13.WDC_IS_KP Macro

Purpose

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

Prototype
WDC_IS_KP(pDev)
Parameters
NameTypeInput/Output
pDevPWDC_DEVICEInput
Description
NameDescription
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.