B.3.WDC High-Level API

This section describes the WDC API defined in the WinDriver/include/wdc_lib.h header file.

B.3.1.Structures, Types and General Definitions

B.3.1.1.WDC_DEVICE_HANDLE

Handle to a WDC device information structure[B.4.3].

typedef void * WDC_DEVICE_HANDLE;

B.3.1.2.WDC_DRV_OPEN_OPTIONS Definitions

typedef DWORD WDC_DRV_OPEN_OPTIONS;

Preprocessor definitions of flags that describe tasks to be performed when opening a handle to the WDC library (see WDC_DriverOpen()[B.3.2]).

NameDescription
WDC_DRV_OPEN_CHECK_VER Compare the version of the WinDriver source files used by the code with the version of the loaded WinDriver kernel
WDC_DRV_OPEN_REG_LICRegister a WinDriver license registration string

The following preprocessor definitions provide convenient WDC driver open options, which can be passed to WDC_DriverOpen()[B.3.2]:

NameDescription
WDC_DRV_OPEN_BASIC

Instructs WDC_DriverOpen()[B.3.2] to perform only the basic WDC open tasks, mainly open a handle to WinDriver's kernel module.

NOTE: The value of this option is zero (<=> no driver open flags), therefore this option cannot be combined with any of the other WDC driver open options.

WDC_DRV_OPEN_KP Convenience option when calling WDC_DriverOpen()[B.3.2] from the Kernel PlugIn. This option is equivalent to setting the WDC_DRV_OPEN_BASIC flag, which is the recommended option to set when opening a handle to the WDC library from the Kernel PlugIn.
WDC_DRV_OPEN_ALL A convenience mask of all the basic WDC driver open flags — WDC_DRV_OPEN_CHECK_VER and WDC_DRV_OPEN_REG_REG_LIC. (The basic functionality of opening a handle to WinDriver's kernel module is always performed by WDC_DriverOpen()[B.3.2], so there is no need to also set the WDC_DRV_OPEN_BASIC flag).
WDC_DRV_OPEN_DEFAULT Use the default WDC open options:
• For user-mode applications: equivalent to setting WDC_DRV_OPEN_ALL ;
• For a Kernel PlugIn: equivalent to setting WDC_DRV_OPEN_KP

B.3.1.3.WDC_DIRECTION Enumeration

Enumeration of a device's address/register access directions.

Enum ValueDescription
WDC_READRead from the address
WDC_WRITEWrite to the address
WDC_READ_WRITE Read from the address or write to it.
This value is used, for example, in the WinDriver samples and generated DriverWizard diagnostics code in order to describe a register's access mode, indicating that the register can either be read from or written to.

B.3.1.4.WDC_ADDR_MODE Enumeration

Enumeration of memory or I/O addresses/registers read/write modes.
The enumeration values are used to determine whether a memory or I/O address/register is read/written in multiples of 8, 16, 32 or 64 bits (i.e., 1, 2, 4 or 8 bytes).

Enum ValueDescription
WDC_MODE_88 bits (1 byte) mode
WDC_MODE_1616 bits (2 bytes) mode
WDC_MODE_3232 bits (4 bytes) mode
WDC_MODE_6464 bits (8 bytes) mode

B.3.1.5.WDC_ADDR_RW_OPTIONS Enumeration

Enumeration of flags that are used to determine how a memory or I/O address will be read/written.

Enum ValueDescription
WDC_ADDR_RW_DEFAULT

Use the default read/write options: memory addresses are accessed directly from the calling process; block transfers are performed from subsequent addresses (automatic increment).

NOTE: The value of this flag is zero (<=> no read/write flags), therefore it can not be combined in a bit-mask with any of the other read/write options flags.

This option is used by the WDC_ReadAddr8/16/32/64()[B.3.19] and WDC_WriteAddr8/16/32/64()[B.3.20] functions.

WDC_ADDR_RW_NO_AUTOINC Do no automatically increment the read/write address in block transfers, i.e., hold the device address constant while reading/writing a block of memory or I/O addresses (relevant only for block (string) transfers).

B.3.1.6.WDC_ADDR_SIZE Definitions

typedef DWORD WDC_ADDR_SIZE;

Preprocessor definitions that depict memory or I/O address/register sizes.

NameDescription
WDC_SIZE_88 bits (1 byte)
WDC_SIZE_1616 bits (2 bytes)
WDC_SIZE_3232 bits (4 bytes)
WDC_SIZE_6464 bits (8 bytes)

B.3.1.7.WDC_SLEEP_OPTIONS Definitions

typedef DWORD WDC_SLEEP_OPTIONS;

Preprocessor definitions that depict the sleep options that can be passed to WDC_Sleep()[B.3.54].

NameDescription
WDC_SLEEP_BUSY Delay execution by consuming CPU cycles (busy sleep)
WDC_SLEEP_NON_BUSY Delay execution without consuming CPU cycles (non-busy sleep).
Note: The accuracy of non-busy sleep is machine-dependent and cannot be guaranteed for short sleep intervals (< 1 millisecond).

B.3.1.8.WDC_DBG_OPTIONS Definitions

typedef DWORD WDC_DBG_OPTIONS;

Preprocessor definitions that depict the possible debug options for the WDC library, which are passed to WDC_SetDebugOptions()[B.3.48].

The following flags determine the output file for the WDC library's debug messages:

NameDescription
WDC_DBG_OUT_DBM Send debug messages from the WDC library to the Debug Monitor[6.2]
WDC_DBG_OUT_FILE Send debug messages from the WDC library to a debug file. By default, the debug file will be stderr, unless a different file is set in the sDbgFile parameter of the WDC_SetDebugOptions() function[B.3.48].
This option is only supported from the user mode (as opposed to the Kernel PlugIn).

The following flags determine the debug level — i.e., what type of WDC debug messages to display, if at all:

NameDescription
WDC_DBG_LEVEL_ERRDisplay only WDC error debug messages
WDC_DBG_LEVEL_TRACEDisplay both error and trace WDC debug messages
WDC_DBG_NONEDo not display WDC debug messages

The following preprocessor definitions provide convenient debug flags combinations, which can be passed to WDC_SetDebugOptions()[B.3.48]:

• User-mode and Kernel PlugIn convenience debug options:

NameDescription
WDC_DBG_DEFAULT WDC_DBG_OUT_DBM | WDC_DBG_LEVEL_TRACE:
Use the default debug options — send WDC error and trace messages to the Debug Monitor[6.2].
WDC_DBG_DBM_ERR WDC_DBG_OUT_DBM | WDC_DBG_LEVEL_ERR:
Send WDC error debug messages to the Debug Monitor[6.2].
WDC_DBG_DBM_TRACE WDC_DBG_OUT_DBM | WDC_DBG_LEVEL_TRACE:
Send WDC error and trace debug messages to the Debug Monitor[6.2].
WDC_DBG_FULL Full WDC debugging:
• From the user mode:
WDC_DBG_OUT_DBM | WDC_DBG_OUT_FILE | WDC_DBG_LEVEL_TRACE:
Send WDC error and trace debug messages both to the Debug Monitor[6.2] and to a debug output file (default file: stderr)
• From the Kernel PlugIn:
WDC_DBG_OUT_DBM | WDC_DBG_LEVEL_TRACE:
Send WDC error and trace messages to the Debug Monitor[6.2]

• User-mode only convenience debug options:

NameDescription
WDC_DBG_FILE_ERR WDC_DBG_OUT_FILE | WDC_DBG_LEVEL_ERR:
Send WDC error debug messages to a debug file (default file: stderr)
WDC_DBG_FILE_TRACE WDC_DBG_OUT_FILE | WDC_DBG_LEVEL_TRACE:
Send WDC error and trace debug messages to a debug file (default file: stderr)
WDC_DBG_DBM_FILE_ERR WDC_DBG_OUT_DBM | WDC_DBG_OUT_FILE | WDC_DBG_LEVEL_ERR:
Send WDC error debug messages both to the Debug Monitor[6.2] and to a debug file (default file: stderr)
WDC_DBG_DBM_FILE_TRACE WDC_DBG_OUT_DBM | WDC_DBG_OUT_FILE | WDC_DBG_LEVEL_TRACE:
Send WDC error and trace debug messages both to the Debug Monitor[6.2] and to a debug file (default file: stderr)

B.3.1.9.WDC_SLOT_U Union

WDC PCI device location information union.

FieldTypeDescription
pciSlotWD_PCI_SLOT PCI device location information structure[B.7.4]

B.3.1.10.WDC_PCI_SCAN_RESULT Structure

Structure for holding the results of a PCI bus scan (see WDC_PciScanDevices()[B.3.4]).

FieldTypeDescription
dwNumDevicesDWORD Number of devices found on the PCI bus that match the search criteria (vendor & device IDs)
deviceIdWD_PCI_ID[WD_PCI_CARDS] Array of matching vendor and device IDs found on the PCI bus[B.7.3]
deviceSlotWD_PCI_SLOT[WD_PCI_CARDS] Array of PCI device location information structures[B.7.4] for the detected devices matching the search criteria

B.3.1.11.WDC_PCI_SCAN_CAPS_RESULT Structure

Structure for holding the results of a PCI capabilities scan (see WDC_PciScanCaps()[B.3.7] and WDC_PciScanExtCaps()[B.3.8]).

FieldTypeDescription
dwNumCapsDWORD Number of capabilities found that match the search criteria (capability ID and capabilities group — basic[B.3.7] or extended[B.3.8])
pciCapsWD_PCI_CAP[WD_PCI_MAX_CAPS]Array of matching PCI capabilities[B.7.5]

B.3.2.WDC_DriverOpen()

Purpose

Opens and stores a handle to WinDriver's kernel module and initializes the WDC library according to the open options passed to it.
This function should be called once before calling any other WDC API.

Prototype
DWORD DLLCALLCONV WDC_DriverOpen(
    WDC_DRV_OPEN_OPTIONS openOptions,
    const CHAR *sLicense);
Parameters
NameTypeInput/Output
openOptionsWDC_DRV_OPEN_OPTIONSInput
sLicenseconst CHAR*Input
Description
NameDescription
openOptions A mask of any of the supported open flags[B.3.1.2], which determines the initialization actions that will be performed by the function.
sLicense WinDriver license registration string.
This argument is ignored if the WDC_DRV_OPEN_REG_LIC flag is not[B.3.1.2] set in the openOptions argument.
If this parameter is a NULL pointer or an empty string, the function will attempt to register the demo WinDriver evaluation license. Therefore, when evaluating WinDriver pass NULL as this parameter. After registering your WinDriver toolkit, modify the code to pass your WinDriver license registration string.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.3.WDC_DriverClose()

Purpose

Closes the WDC WinDriver handle (acquired and stored by a previous call to WDC_DriverOpen()[B.3.2]) and uninitializes the WDC library.

Every WDC_DriverOpen() call should have a matching WDC_DriverClose() call, which should be issued when you no longer need to use the WDC library.

Prototype
DWORD DLLCALLCONV WDC_DriverClose(void);
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.4.WDC_PciScanDevices()

Purpose

Scans the PCI bus for all devices with the specified vendor and device ID combination and returns information regarding the matching devices that were found and their locations. The function performs the scan by iterating through all possible PCI buses on the host platform, then through all possible PCI slots, and then through all possible PCI functions.

[Note]Scan-By-Topology Note
On rare occasions, as a result of malfunctioning hardware, the scan information may contain repeated instances of the same device. As a result, the function might fail to return valid scan data. In such cases, if you cannot remove the malfunctioning device, you can scan the PCI bus using WDC_PciScanDevicesByTopology()[B.3.5] or WDC_PciScanRegisteredDevices()[B.3.6].
Prototype
DWORD DLLCALLCONV WDC_PciScanDevices(
    DWORD dwVendorId,
    DWORD dwDeviceId,
    WDC_PCI_SCAN_RESULT *pPciScanResult);
Parameters
NameTypeInput/Output
dwVendorIdDWORDInput
dwDeviceIdDWORDInput
pPciScanResultWDC_PCI_SCAN_RESULT*Output
Description
NameDescription
dwVendorIdVendor ID to search for, or 0 to search for all vendor IDs
dwDeviceIdDevice ID to search for, or 0 to search for all device IDs
pPciScanResult A pointer to a structure that will be updated by the function with the results of the PCI bus scan[B.3.1.10]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • If you set both the vendor and device IDs to zero, the function will return information regarding all connected PCI devices.

B.3.5.WDC_PciScanDevicesByTopology()

Purpose

Scans the PCI bus for all devices with the specified vendor and device ID combination and returns information regarding the matching devices that were found and their locations. The function performs the scan by topology — i.e., for each located bridge the function scans the connected devices and functions reported by the bridge, and only then proceeds to scan the next bridge.

[Note]
  • In the case of multiple host controllers, WDC_PciScanDevicesByTopology() will perform the scan only for the first host controller.
  • By default, use WDC_PciScanDevices()[B.3.4] to scan the PCI bus, unless a device malfunction intererferes — refer to the note in the description of PciScanDevices().
Prototype
DWORD DLLCALLCONV WDC_PciScanDevicesByTopology(
    DWORD dwVendorId,
    DWORD dwDeviceId,
    WDC_PCI_SCAN_RESULT *pPciScanResult);
Parameters
NameTypeInput/Output
dwVendorIdDWORDInput
dwDeviceIdDWORDInput
pPciScanResultWDC_PCI_SCAN_RESULT*Output
Description
NameDescription
dwVendorIdVendor ID to search for, or 0 to search for all vendor IDs
dwDeviceIdDevice ID to search for, or 0 to search for all device IDs
pPciScanResult A pointer to a structure that will be updated by the function with the results of the PCI bus scan[B.3.1.10]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • If you set both the vendor and device IDs to zero, the function will return information regarding all connected PCI devices.

B.3.6.WDC_PciScanRegisteredDevices()

Purpose

Scans the PCI bus for all devices with the specified vendor and device ID combination that have been registered to work with WinDriver, and returns information regarding the matching devices that were found and their locations. The function performs the scan by iterating through all possible PCI buses on the host platform, then through all possible PCI slots, and then through all possible PCI functions.

[Note]
  • By default, use WDC_PciScanDevices()[B.3.4] to scan the PCI bus, unless a device malfunction intererferes — refer to the note in the description of PciScanDevices().
Prototype
DWORD DLLCALLCONV WDC_PciScanRegisteredDevices(
    DWORD dwVendorId,
    DWORD dwDeviceId,
    WDC_PCI_SCAN_RESULT *pPciScanResult);
Parameters
NameTypeInput/Output
dwVendorIdDWORDInput
dwDeviceIdDWORDInput
pPciScanResultWDC_PCI_SCAN_RESULT*Output
Description
NameDescription
dwVendorIdVendor ID to search for, or 0 to search for all vendor IDs
dwDeviceIdDevice ID to search for, or 0 to search for all device IDs
pPciScanResult A pointer to a structure that will be updated by the function with the results of the PCI bus scan[B.3.1.10]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • If you set both the vendor and device IDs to zero, the function will return information regarding all connected PCI devices that are registered with WinDriver.

B.3.7.WDC_PciScanCaps()

Purpose

Scans the basic PCI capabilities of the given device for the specified capability (or for all capabilities).

Prototype
DWORD DLLCALLCONV WDC_PciScanCaps(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwCapId,
    WDC_PCI_SCAN_CAPS_RESULT *pScanCapsResult);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwCapIdDWORDInput
pScanCapsResultWDC_PCI_SCAN_CAPS_RESULT*Output
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
dwCapId ID of the basic PCI capability for which to search, or WD_PCI_CAP_ID_ALL to search for all basic PCI capabilities
pScanCapsResult A pointer to a structure that will be updated by the function with the results of the basic PCI capabilities scan[B.3.1.11]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.8.WDC_PciScanExtCaps()

Purpose

Scans the extended (PCI Express) PCI capabilities of the given device for the specified capability (or for all capabilities).

Prototype
DWORD DLLCALLCONV WDC_PciScanExtCaps(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwCapId,
    WDC_PCI_SCAN_CAPS_RESULT *pScanCapsResult);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwCapIdDWORDInput
pScanCapsResultWDC_PCI_SCAN_CAPS_RESULT*Output
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
dwCapId ID of the extended PCI capability for which to search, or WD_PCI_CAP_ID_ALL to search for all extended PCI capabilities
pScanCapsResult A pointer to a structure that will be updated by the function with the results of the extended (PCI Express) PCI capabilities scan[B.3.1.11]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.9.WDC_PciGetDeviceInfo()

Purpose

Retrieves a PCI device's resources information (memory and I/O ranges and interrupt information).

Prototype
DWORD DLLCALLCONV WDC_PciGetDeviceInfo(
    WD_PCI_CARD_INFO *pDeviceInfo);
Parameters
NameTypeInput/Output
pDeviceInfoWD_PCI_CARD_INFO*Input/Output
pciSlotWD_PCI_SLOTInput
CardWD_CARDOutput
Description
NameDescription
pDeviceInfo Pointer to a PCI device information structure[B.7.8]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • The resources information is obtained from the operating system's Plug-and-Play manager, unless the information is not available, in which case it is read directly from the PCI configuration registers.
    Note: On Windows, you must install an INF file file, which registers your device with WinDriver, before calling this function (see Section15.1 regarding creation of INF files with WinDriver).
  • If the interrupt request (IRQ) number is obtained from the Plug-and-Play manager, it is mapped, and therefore may differ from the physical IRQ number.

B.3.10.WDC_PciDeviceOpen()

Purpose

Allocates and initializes a WDC PCI device structure, registers the device with WinDriver, and returns a handle to the device.

This function

  • Verifies that none of the registered device resources (set in pDeviceInfo->Card.Item) are already locked for exclusive use.
    [Note]
    A resource can be locked for exclusive use by setting the fNotSharable field of its WD_ITEMS structure[B.7.6] to 1, before calling WDC_PciDeviceOpen().
  • Maps the physical memory ranges found on the device both to kernel-mode and user-mode address space, and stores the mapped addresses in the allocated device structure for future use.
  • Saves device resources information required for supporting the communication with the device. For example, the function saves the interrupt request (IRQ) number and the interrupt type, as well as retrieves and saves an interrupt handle, and this information is later used when the user calls functions to handle the device's interrupts.
  • If the caller selects to use a Kernel PlugIn driver to communicate with the device, the function opens a handle to this driver and stores it for future use.

Prototype
DWORD DLLCALLCONV WDC_PciDeviceOpen(
    WDC_DEVICE_HANDLE *phDev,
    const WD_PCI_CARD_INFO *pDeviceInfo,
    const PVOID pDevCtx);
Parameters
NameTypeInput/Output
phDevWDC_DEVICE_HANDLE*Output
pDeviceInfoconst WD_PCI_CARD_INFO*Input
pciSlotWD_PCI_SLOTInput
CardWD_CARDInput
*dwItemsDWORDInput
*ItemWD_ITEMS[WD_CARD_ITEMS]Input
itemDWORDInput
fNotSharableDWORDInput
IunionInput
*MemstructInput
pPhysicalAddrPHYS_ADDRN/A
qwBytesUINT64Input
pTransAddrKPTRN/A
pUserDirectAddrUPTRN/A
dwBarDWORDInput
dwOptionsDWORDInput
pReservedKPTRN/A
*IOstructInput
pAddrKPTRInput
dwBytesDWORDInput
dwBarDWORDInput
*IntstructInput
dwInterruptDWORDInput
dwOptionsDWORDInput
hInterruptDWORDN/A
dwReserved1DWORDN/A
pReserved2KPTRN/A
*BusstructInput
dwBusTypeWD_BUS_TYPEInput
dwBusNumDWORDInput
dwSlotFuncDWORDInput
pDevCtxconst PVOIDInput
Description
NameDescription
phDev Pointer to a handle to the WDC device allocated by the function
pDeviceInfo Pointer to a PCI device information structure[B.7.8], which contains information regarding the device to open
pDevCtx Pointer to device context information, which will be stored in the device structure
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  1. This function may be called only from the user mode.
  2. If your card has a large memory range that cannot be fully mapped to the kernel address space, you can set the WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag in the I.Mem.dwOptions field of the relevant WD_ITEMS memory resource structure[B.7.6] (pDeviceInfo->Card.Item[i].I.Mem.dwOptions), received from WDC_PciGetDeviceInfo(), before passing it to the device-open function. This flag instructs the function to map the memory range only to the user-mode virtual address space, and not to the kernel address space.

    [Note]
    Note that if you select to set the WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag, the device information structure that will be created by the function will not hold a kernel-mapped address for this resource (the pAddrDesc[i].pAddr base address kernel mapping field of the relevant memory range in the WDC_DEVICE structure[B.4.3] will not be updated), and you will therefore not be able to rely on this mapping in calls to WinDriver APIs — namely interrupt handling APIs or any API called from a KernelPlugIn driver.

B.3.11.WDC_IsaDeviceOpen()

Purpose

Allocates and initializes a WDC ISA device structure, registers the device with WinDriver, and returns a handle to the device.

This function

  • Verifies that none of the registered device resources (set in pDeviceInfo->Card.Item) are already locked for exclusive use.
    [Note]
    A resource can be locked for exclusive use by setting the fNotSharable field of its WD_ITEMS structure[B.7.6] to 1, before calling WDC_IsaDeviceOpen().
  • Maps the device's physical memory ranges device both to kernel-mode and user-mode address space, and stores the mapped addresses in the allocated device structure for future use.
  • Saves device resources information required for supporting the communication with the device. For example, the function saves the interrupt request (IRQ) number and the interrupt type, as well as retrieves and saves an interrupt handle, and this information is later used when the user calls functions to handle the device's interrupts.
  • If the caller selects to use a Kernel PlugIn driver to communicate with the device, the function opens a handle to this driver and stores it for future use.

Prototype
DWORD DLLCALLCONV WDC_IsaDeviceOpen(
    WDC_DEVICE_HANDLE *phDev,
    const WD_CARD *pDeviceInfo,
    const PVOID pDevCtx);
Parameters
NameTypeInput/Output
phDevWDC_DEVICE_HANDLE*Output
pDeviceInfoconst WD_CARD*Input
dwItemsDWORDInput
ItemWD_ITEMS[WD_CARD_ITEMS]Input
*itemDWORDInput
*fNotSharableDWORDInput
*IunionInput
MemstructInput
*pPhysicalAddrPHYS_ADDRInput
*qwBytesUINT64Input
*pTransAddrKPTRN/A
*pUserDirectAddrUPTRN/A
*dwBarDWORDInput
*dwOptionsDWORDInput
*pReservedKPTRN/A
IOstructInput
*pAddrKPTRInput
*dwBytesDWORDInput
*dwBarDWORDInput
IntstructInput
*dwInterruptDWORDInput
*dwOptionsDWORDInput
*hInterruptDWORDN/A
*dwReserved1DWORDN/A
*pReserved2KPTRN/A
BusstructInput
*dwBusTypeWD_BUS_TYPEInput
*dwBusNumDWORDInput
*dwSlotFuncDWORDInput
pDevCtxconst PVOIDInput
Description
NameDescription
phDevPointer to a handle to the WDC device allocated by the function
pDeviceInfo Pointer to a card information structure[B.7.7], which contains information regarding the device to open
pDevCtx Pointer to device context information, which will be stored in the device structure
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  1. This function may be called only from the user mode.
  2. If your card has a large memory range that cannot be fully mapped to the kernel address space, you can set the WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag in the I.Mem.dwOptions field of the relevant WD_ITEMS memory resource structure[B.7.6] (pDeviceInfo->Card.Item[i].I.Mem.dwOptions) before passing it to the device-open function. This flag instructs the function to map the memory range only to the user-mode virtual address space, and not to the kernel address space.

    [Note]
    Note that if you select to set the WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag, the device information structure that will be created by the function will not hold a kernel-mapped address for this resource (the pAddrDesc[i].pAddr base address kernel mapping field of the relevant memory range in the WDC_DEVICE structure[B.4.3] will not be updated), and you will therefore not be able to rely on this mapping in calls to WinDriver APIs — namely interrupt handling APIs or any API called from a KernelPlugIn driver.

B.3.12.WDC_PciDeviceClose()

Purpose

Uninitializes a WDC PCI device structure and frees the memory allocated for it.

Prototype
DWORD DLLCALLCONV WDC_PciDeviceClose(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function can be called from the user mode only.

B.3.13.WDC_IsaDeviceClose()

Purpose

Uninitializes a WDC ISA device structure and frees the memory allocated for it.

Prototype
DWORD DLLCALLCONV WDC_IsaDeviceClose(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a WDC ISA device structure, returned by WDC_IsaDeviceOpen()[B.3.11]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function can be called from the user mode only.

B.3.14.WDC_CardCleanupSetup()

Purpose

Sets a list of transfer cleanup commands to be performed for the specified card on any of the following occasions:

  • The application exits abnormally.
  • The application exits normally but without closing the specified card.
  • If the bForceCleanup parameter is set to TRUE, the cleanup commands will also be performed when the specified card is closed.

Prototype
DWORD WDC_CardCleanupSetup(
    WDC_DEVICE_HANDLE hDev,
    WD_TRANSFER *Cmd,
    DWORD dwCmds,
    BOOL bForceCleanup);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
CmdWD_TRANSFER*Input
dwCmdsDWORDInput
bForceCleanupBOOLInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
Cmd Pointer to an array of cleanup transfer commands to be performed[B.7.10]
dwCmdsNumber of cleanup commands in the Cmd array
bForceCleanup

If FALSE: The cleanup transfer commands (Cmd) will be performed in either of the following cases:
• When the application exits abnormally.
• When the application exits normally without closing the card by calling one of the WDC_xxxDeviceClose() functions (PCI[B.3.12] / ISA[B.3.13]).

If TRUE: The cleanup transfer commands will be performed both in the two cases described above, as well as in the following case:
• When the relevant WD_xxxDeviceClose() function is called for the card.

Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.15.WDC_KernelPlugInOpen()

Purpose

Opens a handle to a Kernel PlugIn driver.

Prototype
DWORD DLLCALLCONV WDC_KernelPlugInOpen(
    WDC_DEVICE_HANDLE hDev,
    const CHAR *pcKPDriverName,
    PVOID pKPOpenData);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput/Output
pcKPDriverNameconst CHAR*Input
pKPOpenDataPVOIDInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
pcKPDriverNameKernel PlugIn driver name
pKPOpenData Kernel PlugIn driver open data to be passed to WD_KernelPlugInOpen() (see the WinDriver PCI Low-Level API Reference)
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks

It's also possible to use the WDC_xxxDeviceOpen() functions (PCI[B.3.10] / ISA[B.3.11]) to open a handle to a Kernel PlugIn driver, as part of the device-open operation. However, this method cannot be used to open a handle to a 64-bit Kernel PlugIn driver from a 32-bit user-mode application. Therefore, to ensure that your code works in all the supported configurations, it is recommended that you use WDC_KernelPlugInOpen() to open the Kernel PlugIn driver handle. This is also the only supported method for opening a Kernel PlugIn handle from a .NET application. (See detailed information in Section12.4.)

B.3.16.WDC_CallKerPlug()

Purpose

Sends a message from a user-mode application to a Kernel PlugIn driver. The function passes a message ID from the application to the Kernel PlugIn's KP_Call[B.8.4] function, which should be implemented to handle the specified message ID, and returns the result from the Kernel PlugIn to the user-mode application.

Prototype
DWORD DLLCALLCONV WDC_CallKerPlug(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwMsg,
    PVOID pData,
    PDWORD pdwResult);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwMsgDWORDInput
pDataPVOIDInput/Output
pdwResultpdwResultOutput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
dwMsg A message ID to pass to the Kernel PlugIn driver (specifically to KP_Call[B.8.4])
pData Pointer to data to pass between the Kernel PlugIn driver and the user-mode application
pdwResult Result returned by the Kernel PlugIn driver (KP_Call) for the operation performed in the kernel as a result of the message that was sent
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.17.WDC_ReadMemXXX()

Purpose

WDC_ReadMem8/16/32/64() reads 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, from a specified memory address. The address is read directly in the calling context (user mode / kernel mode).

Prototype
BYTE WDC_ReadMem8(addr, off);
WORD WDC_ReadMem16(addr, off);
UINT32 WDC_ReadMem32(addr, off);
UINT64 WDC_ReadMem64(addr, off);

Note: The WDC_ReadMemXXX APIs are implemented as macros. The prototypes above use functions declaration syntax to emphasize the expected return values.

Parameters
NameTypeInput/Output
addrDWORDInput
offDWORDInput
Description
NameDescription
addrThe memory address space to read from
off The offset from the beginning of the specified address space (addr) to read from
Return Value

Returns the data that was read from the specified address.

B.3.18.WDC_WriteMemXXX()

Purpose

WDC_WriteMem8/16/32/64() writes 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, to a specified memory address. The address is written to directly in the calling context (user mode / kernel mode).

Prototype
void WDC_WriteMem8(addr, off, val);
void WDC_WriteMem16(addr, off, val);
void WDC_WriteMem32(addr, off, val);
void WDC_WriteMem64(addr, off, val);

Note: The WDC_WriteMemXXX APIs are implemented as macros. The prototypes above use functions declaration syntax to emphasize the expected return values.

Parameters
NameTypeInput/Output
addrDWORDInput
offDWORDInput
valBYTE / WORD / UINT32 / UINT64Input
Description
NameDescription
addrThe memory address space to read from
off The offset from the beginning of the specified address space (addr) to read from
valThe data to write to the specified address
Return Value

None

B.3.19.WDC_ReadAddrXXX()

Purpose

WDC_ReadAddr8/16/32/64() reads 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, from a specified memory or I/O address.

Prototype
DWORD DLLCALLCONV WDC_ReadAddr8(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, BYTE *val);

DWORD DLLCALLCONV WDC_ReadAddr16(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, WORD *val);

DWORD DLLCALLCONV WDC_ReadAddr32(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, UINT32 *val);

DWORD DLLCALLCONV WDC_ReadAddr64(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, UINT64 *val);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwAddrSpaceDWORDInput
dwOffsetKPTRInput
valBYTE* / WORD* / UINT32* / UINT64*Output
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
dwAddrSpaceThe memory or I/O address space to read from
dwOffset The offset from the beginning of the specified address space (dwAddrSpace) to read from
val Pointer to a buffer to be filled with the data that is read from the specified address
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.20.WDC_WriteAddrXXX()

Purpose

WDC_WriteAddr8/16/32/64() writes 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, to a specified memory or I/O address.

Prototype
DWORD DLLCALLCONV WDC_WriteAddr8(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, BYTE val)

DWORD DLLCALLCONV WDC_WriteAddr16(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, WORD val);

DWORD DLLCALLCONV WDC_WriteAddr32(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, UINT32 val);

DWORD DLLCALLCONV WDC_WriteAddr64(WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace, KPTR dwOffset, UINT64 val);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwAddrSpaceDWORDInput
dwOffsetKPTRInput
val BYTE / WORD / UINT32 / UINT64 Input
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
dwAddrSpaceThe memory or I/O address space to write to
dwOffset The offset from the beginning of the specified address space (dwAddrSpace) to write to
valThe data to write to the specified address
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.21.WDC_ReadAddrBlock()

Purpose

Reads a block of data from the device.

Prototype
DWORD DLLCALLCONV WDC_ReadAddrBlock(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace,
    KPTR dwOffset,
    DWORD dwBytes,
    PVOID pData,
    WDC_ADDR_MODE mode,
    WDC_ADDR_RW_OPTIONS options);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwAddrSpaceDWORDInput
dwOffsetKPTRInput
dwBytesDWORDInput
pDataPVOIDOutput
modeWDC_ADDR_MODEInput
optionsWDC_ADDR_RW_OPTIONSInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
dwAddrSpaceThe memory or I/O address space to read from
dwOffset The offset from the beginning of the specified address space (dwAddrSpace) to read from
dwBytesThe number of bytes to read
pData Pointer to a buffer to be filled with the data that is read from the device
modeThe read access mode — see WDC_ADDR_MODE[B.3.1.4]
options A bit mask that determines how the data will be read — see WDC_ADDR_RW_OPTIONS[B.3.1.5].
The function automatically sets the WDC_RW_BLOCK flag.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.22.WDC_WriteAddrBlock()

Purpose

Writes a block of data to the device.

Prototype
DWORD DLLCALLCONV WDC_WriteAddrBlock(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace,
    KPTR dwOffset,
    DWORD dwBytes,
    PVOID pData,
    WDC_ADDR_MODE mode,
    WDC_ADDR_RW_OPTIONS options);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwAddrSpaceDWORDInput
dwOffsetKPTRInput
dwBytesDWORDInput
pDataPVOIDInput
modeWDC_ADDR_MODEInput
optionsWDC_ADDR_RW_OPTIONSInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
dwAddrSpaceThe memory or I/O address space to write to
dwOffset The offset from the beginning of the specified address space (dwAddrSpace) to write to
dwBytesThe number of bytes to write
pDataPointer to a buffer that holds the data to write to the device
modeThe write access mode — see WDC_ADDR_MODE[B.3.1.4]
options A bit mask that determines how the data will be written — see WDC_ADDR_RW_OPTIONS[B.3.1.5].
The function automatically sets the WDC_RW_BLOCK flag.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.23.WDC_MultiTransfer()

Purpose

Performs a group of memory and/or I/O read/write transfers.

Prototype
DWORD DLLCALLCONV WDC_MultiTransfer(
    WD_TRANSFER *pTrans,
    DWORD dwNumTrans);
Parameters
NameTypeInput/Output
pTransWD_TRANSFER*
dwNumTransDWORDInput
Description
NameDescription
pTrans Pointer to an array of transfer commands information structures[B.7.10]
dwNumTransNumber of transfer commands in the pTrans array
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • The transfers are performed using the low-level WD_MultiTransfer() WinDriver function, which reads/writes the specified addresses in the kernel (see the WinDriver PCI Low-Level API Reference for details).
  • Memory addresses are read/written in the kernel (like I/O addresses) and NOT directly in the user mode, therefore the port addresses passed to this function, for both memory and I/O addresses, must be the kernel-mode mappings of the physical addresses, which are stored in the device structure[B.4.3].

B.3.24.WDC_AddrSpaceIsActive()

Purpose

Checks if the specified memory or I/O address space is active — i.e., if its size is not zero.

Prototype
BOOL DLLCALLCONV WDC_AddrSpaceIsActive(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwAddrSpace);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwAddrSpaceDWORDInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
dwAddrSpaceThe memory or I/O address space to look for
Return Value

Returns TRUE if the specified address space is active; otherwise returns FALSE.

B.3.25.WDC_PciReadCfgBySlot()

Purpose

Reads data from a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.
The device is identified by its location on the PCI bus.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciReadCfgBySlot(
    WD_PCI_SLOT *pPciSlot,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);
Parameters
NameTypeInput/Output
pPciSlotWD_PCI_SLOT*Input
dwOffsetDWORDInput
pDataPVOIDOutput
dwBytesDWORDInput
Description
NameDescription
pPciSlot Pointer to a PCI device location information structure[B.7.4], which can be acquired by calling WDC_PciScanDevices()[B.3.4]
dwOffset The offset from the beginning of the PCI configuration space to read from
pData Pointer to a buffer to be filled with the data that is read from the PCI configuration space
dwBytesThe number of bytes to read
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.26.WDC_PciWriteCfgBySlot()

Purpose

Write data to a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.
The device is identified by its location on the PCI bus.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciWriteCfgBySlot(
    WD_PCI_SLOT *pPciSlot,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);
Parameters
NameTypeInput/Output
pPciSlotWD_PCI_SLOT*Input
dwOffsetDWORDInput
pDataPVOIDInput
dwBytesDWORDInput
Description
NameDescription
pPciSlot Pointer to a PCI device location information structure[B.7.4], which can be acquired by calling WDC_PciScanDevices()[B.3.4]
dwOffset The offset from the beginning of the PCI configuration space to write to
pDataPointer to a data buffer that holds the data to write
dwBytesThe number of bytes to write
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.27.WDC_PciReadCfg()

Purpose

Reads data from a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciReadCfg(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwOffsetDWORDInput
pDataPVOIDOutput
dwBytesDWORDInput
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
dwOffset The offset from the beginning of the PCI configuration space to read from
pData Pointer to a buffer to be filled with the data that is read from the PCI configuration space
dwBytesThe number of bytes to read
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.28.WDC_PciWriteCfg()

Purpose

Writes data to a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciWriteCfg(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwOffsetDWORDInput
pDataPVOIDInput
dwBytesDWORDInput
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
dwOffset The offset from the beginning of the PCI configuration space to write to
pDataPointer to a data buffer that holds the data to write
dwBytesThe number of bytes to write
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.29.WDC_PciReadCfgBySlotXXX()

Purpose

WDC_PciReadCfgBySlot8/16/32/64() reads 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, from a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.
The device is identified by its location on the PCI bus.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciReadCfgRegBySlot8(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, BYTE *val);

DWORD DLLCALLCONV WDC_PciReadCfgReg1BySlot6(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, WORD *val);

DWORD DLLCALLCONV WDC_PciReadCfgReg32BySlot(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, UINT32 *val);

DWORD DLLCALLCONV WDC_PciReadCfgReg64BySlot(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, UINT64 *val);
Parameters
NameTypeInput/Output
pPciSlotWD_PCI_SLOT*Input
dwOffsetDWORDInput
valBYTE* / WORD* / UINT32* / UINT64*Output
Description
NameDescription
pPciSlot Pointer to a PCI device location information structure[B.7.4], which can be acquired by calling WDC_PciScanDevices()[B.3.4]
dwOffset The offset from the beginning of the PCI configuration space to read from
val Pointer to a buffer to be filled with the data that is read from the PCI configuration space
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.30.WDC_PciWriteCfgBySlotXXX()

Purpose

WDC_PciWriteCfgBySlot8/16/32/64() writes 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, to a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.
The device is identified by its location on the PCI bus.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciWriteCfgRegBySlot8(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, BYTE val);

DWORD DLLCALLCONV WDC_PciWriteCfgRegBySlot16(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, WORD val);

DWORD DLLCALLCONV WDC_PciWriteCfgRegBySlot32(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, UINT32 val);

DWORD DLLCALLCONV WDC_PciWriteCfgRegBySlot64(
    WD_PCI_SLOT *pPciSlot, DWORD dwOffset, UINT64 val);
Parameters
NameTypeInput/Output
pPciSlotWD_PCI_SLOT*Input
dwOffsetDWORDInput
valBYTE / WORD / UINT32 / UINT64Input
Description
NameDescription
pPciSlot Pointer to a PCI device location information structure[B.7.4], which can be acquired by calling WDC_PciScanDevices()[B.3.4]
dwOffset The offset from the beginning of the PCI configuration space to read from
valThe data to write to the PCI configuration space
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.31.WDC_PciReadCfgXXX()

Purpose

WDC_PciReadCfg8/16/32/64() reads 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, from a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciReadCfgReg8(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, BYTE *val);

DWORD DLLCALLCONV WDC_PciReadCfgReg16(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, WORD *val);

DWORD DLLCALLCONV WDC_PciReadCfgReg32(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, UINT32 *val);

DWORD DLLCALLCONV WDC_PciReadCfgReg64(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, UINT64 *val);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwOffsetDWORDInput
valBYTE* / WORD* / UINT32* / UINT64*Output
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
dwOffset The offset from the beginning of the PCI configuration space to read from
val Pointer to a buffer to be filled with the data that is read from the PCI configuration space
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.32.WDC_PciWriteCfgXXX()

Purpose

WDC_PciWriteCfg8/16/32/64() writes 1 byte (8 bits) / 2 bytes (16 bits) / 4 bytes (32 bits) / 8 bytes (64 bits), respectively, to a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space.

[Note]
Access to the PCI Express extended configuration space is supported on target platforms that support such access (e.g., Windows and Linux). For such platforms, all PCI references in the following documentation include PCI Express as well.
Prototype
DWORD DLLCALLCONV WDC_PciWriteCfgReg8(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, BYTE val);

DWORD DLLCALLCONV WDC_PciWriteCfgReg16(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, WORD val);

DWORD DLLCALLCONV WDC_PciWriteCfgReg32(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, UINT32 val);

DWORD DLLCALLCONV WDC_PciWriteCfgReg64(WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset, UINT64 val);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwOffsetDWORDInput
valBYTE / WORD / UINT32 / UINT64Input
Description
NameDescription
hDevHandle to a WDC PCI device structure, returned by WDC_PciDeviceOpen()[B.3.10]
dwOffset The offset from the beginning of the PCI configuration space to read from
valThe data to write to the PCI configuration space
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.33.WDC_DMAContigBufLock()

Purpose

Allocates a contiguous DMA buffer, locks it in physical memory, and returns mappings of the allocated buffer to physical address space and to user-mode and kernel virtual address spaces.

Prototype
DWORD DLLCALLCONV WDC_DMAContigBufLock(
    WDC_DEVICE_HANDLE hDev,
    PVOID *ppBuf,
    DWORD dwOptions,
    DWORD dwDMABufSize,
    WD_DMA **ppDma);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
ppBufPVOID*Output
dwOptionsDWORDInput
dwDMABufSizeDWORDInput
ppDmaWD_DMA**Output
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11]).
ppBuf Pointer to a pointer to be filled by the function with the user-mode mapped address of the allocated DMA buffer
dwOptions A bit mask of any of the following flags (defined in an enumeration in windrvr.h):
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_ALLOW_CACHE: Allow caching of the memory.
DMA_KBUF_BELOW_16M: Allocate the physical DMA buffer within the lower 16MB of the main memory.
DMA_ALLOW_64BIT_ADDRESS: Allow allocation of 64-bit DMA addresses. This flag is supported on Windows and Linux.
dwDMABufSizeThe size (in bytes) of the DMA buffer
ppDma Pointer to a pointer to a DMA buffer information structure[B.7.9], which is allocated by the function.
The pointer to this structure (*ppDma) should be passed to WDC_DMABufUnlock()[B.3.36] when the DMA buffer is no longer needed.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • When calling this function you do not need to set the
    DMA_KERNEL_BUFFER_ALLOC flag, since the function sets this flag automatically.
  • This function is currently only supported from the user mode.
  • On Windows x86 and x86_64 platforms, you should normally set the DMA_ALLOW_CACHE flag in the DMA options bitmask parameter (dwOptions).
  • If the device supports 64-bit DMA addresses, it is recommended to set the DMA_ALLOW_64BIT_ADDRESS flag in dwOptions. Otherwise, when the physical memory on the target platform is larger than 4GB, the operating system may only allow allocation of relatively small 32-bit DMA buffers (such as 1MB buffers, or even smaller).

B.3.34.WDC_DMASGBufLock()

Purpose

Locks a pre-allocated user-mode memory buffer for DMA and returns the corresponding physical mappings of the locked DMA pages. On Windows the function also returns a kernel-mode mapping of the buffer.

Prototype
DWORD DLLCALLCONV WDC_DMASGBufLock(
    WDC_DEVICE_HANDLE hDev,
    PVOID pBuf,
    DWORD dwOptions,
    DWORD dwDMABufSize,
    WD_DMA **ppDma);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
pBufPVOIDInput
dwOptionsDWORDInput
dwDMABufSizeDWORDInput
ppDmaWD_DMA**Output
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
pBuf Pointer to a user-mode buffer to be mapped to the allocated physical DMA buffer(s)
dwOptions A bit mask of any of the following flags (defined in an enumeration in windrvr.h):
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_ALLOW_CACHE: Allow caching of the memory.
DMA_ALLOW_64BIT_ADDRESS: Allow allocation of 64-bit DMA addresses. This flag is supported on Windows and Linux.
dwDMABufSizeThe size (in bytes) of the DMA buffer
ppDma Pointer to a pointer to a DMA buffer information structure[B.7.9], which is allocated by the function.
The pointer to this structure (*ppDma) should be passed to WDC_DMABufUnlock()[B.3.36] when the DMA buffer is no longer needed.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • When calling the function to allocate large buffers (> 1MB) you do not need to set the DMA_LARGE_BUFFER flag, which is used for allocation of large Scatter/Gather DMA buffers using the low-level WinDriver WD_DMALock() function (see the WinDriver PCI Low-Level API Reference), since WDC_DMASGBufLock() handles this for you.
  • This function is currently only supported from the user mode.
  • On Windows x86 and x86_64 platforms, you should normally set the DMA_ALLOW_CACHE flag in the DMA options bitmask parameter (dwOptions).
  • If the device supports 64-bit DMA addresses, it is recommended to set the DMA_ALLOW_64BIT_ADDRESS flag in dwOptions. Otherwise, when the physical memory on the target platform is larger than 4GB, the operating system may only allow allocation of relatively small 32-bit DMA buffers (such as 1MB buffers, or even smaller).

B.3.35.WDC_DMAReservedBufLock()

Purpose

Locks a physical reserved memory buffer for DMA and returns the corresponding user mode address of locked DMA buffer.

[Note]
The physical address returned from this API (ppDma->Page[0].pPhysicalAddr) may be different then the address supplied by the caller (qwAddr) when the system uses IOMMU. When performing DMA transfer using this mapped buffer, make sure to use the returned address.
Prototype
DWORD DLLCALLCONV WDC_DMAReservedBufLock(
    WDC_DEVICE_HANDLE hDev,
    PHYS_ADDR qwAddr,
    PVOID *ppBuf,
    DWORD dwOptions,
    DWORD dwDMABufSize,
    WD_DMA **ppDma);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
qwAddrPHYS_ADDRInput
ppBufPVOID *Output
dwOptionsDWORDInput
dwDMABufSizeDWORDInput
ppDmaWD_DMA**Output
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
qwAddrPhysical address of the reserved buffer to lock
ppBuf Pointer to a pointer to be filled by the function with the user-mode mapped address of the locked DMA buffer
dwOptions A bit mask of any of the following flags (defined in an enumeration in windrvr.h):
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_ALLOW_64BIT_ADDRESS: Allow allocation of 64-bit DMA addresses. This flag is supported on Windows and Linux.
dwDMABufSizeThe size (in bytes) of the DMA buffer
ppDma Pointer to a pointer to a DMA buffer information structure[B.7.9], which is allocated by the function.
The pointer to this structure (*ppDma) should be passed to WDC_DMABufUnlock()[B.3.36] when the DMA buffer is no longer needed.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.36.WDC_DMABufUnlock()

Purpose

Unlocks and frees the memory allocated for a DMA buffer by a previous call to WDC_DMAContigBufLock()[B.3.33], WDC_DMASGBufLock()[B.3.34] or WDC_DMAReservedBufLock()[B.3.35].

Prototype
DWORD DLLCALLCONV WDC_DMABufUnlock(WD_DMA *pDma);
Parameters
NameTypeInput/Output
pDmaWD_DMA*Input
Description
NameDescription
pDma Pointer to a DMA information structure[B.7.9], received from a previous call to WDC_DMAContigBufLock()[B.3.33] (for a contiguous DMA buffer) or WDC_DMASGBufLock()[B.3.34] (for a Scatter/Gather DMA buffer) — *ppDma returned by these functions
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function is currently only supported from the user mode.

B.3.37.WDC_DMABufGet()

Purpose

Retrieves a contiguous DMA buffer which was allocated by another process.

Prototype
DWORD DLLCALLCONV WDC_DMABufGet(DWORD hDma, WD_DMA **ppDma);
[Note]
Before calling this API, the calling process should recieve the global buffer handle via WinDriver IPC mechanism from the process that allocated the buffer.
[Note]
Once the process finish using the shared buffer, it should release it using the regular unlock method- WDC_DMABufUnlock()[B.3.36].
Parameters
NameTypeInput/Output
hDmaDWORDInput
ppDmaWD_DMA**Output
Description
NameDescription
hDma DMA buffer handle.
ppDma Pointer to a pointer to a DMA buffer information structure[B.7.9], which is associated with hDma.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.38.WDC_DMAGetGlobalHandle Macro

Purpose

Utility macro that returns a contiguous DMA global handle that can be used for buffer sharing between multiple processes.

Prototype
WDC_DMAGetGlobalHandle(pDma)
Parameters
NameTypeInput/Output
pDmaWD_DMA*Input
Description
NameDescription
pDma Pointer to a DMA information structure[B.7.9], received from a previous call to WDC_DMAContigBufLock()[B.3.33]
Return Value

DMA buffer handle of pDma.

B.3.39.WDC_DMASyncCpu()

Purpose

Synchronizes the cache of all CPUs with the DMA buffer, by flushing the data from the CPU caches.

[Note]
This function should be called before performing a DMA transfer (see Remarks below).
Prototype
DWORD DLLCALLCONV WDC_DMASyncCpu(WD_DMA *pDma);
Parameters
NameTypeInput/Output
pDmaWD_DMA*Input
Description
NameDescription
pDma Pointer to a DMA information structure[B.7.9], received from a previous call to WDC_DMAContigBufLock()[B.3.33] (for a contiguous DMA buffer) or WDC_DMASGBufLock()[B.3.34] (for a Scatter/Gather DMA buffer) — *ppDma returned by these functions
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • An asynchronous DMA read or write operation accesses data in memory, not in the processor (CPU) cache, which resides between the CPU and the host's physical memory. Unless the CPU cache has been flushed, by calling WDC_DMASyncCpu(), just before a read transfer, the data transferred into system memory by the DMA operation could be overwritten with stale data if the CPU cache is flushed later. Unless the CPU cache has been flushed by calling WDC_DMASyncCpu() just before a write transfer, the data in the CPU cache might be more up-to-date than the copy in memory.
  • This function is currently only supported from the user mode.

B.3.40.WDC_DMASyncIo()

Purpose

Synchronizes the I/O caches with the DMA buffer, by flushing the data from the I/O caches and updating the CPU caches.

[Note]
This function should be called after performing a DMA transfer (see Remarks below).
Prototype
DWORD DLLCALLCONV WDC_DMASyncIo(WD_DMA *pDma);
Parameters
NameTypeInput/Output
pDmaWD_DMA*Input
Description
NameDescription
pDma Pointer to a DMA information structure, received from a previous call to WDC_DMAContigBufLock()[B.3.33] (for a contiguous DMA buffer) or WDC_DMASGBufLock()[B.3.34] (for a Scatter/Gather DMA buffer) — *ppDma returned by these functions
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • After a DMA transfer has been completed, the data can still be in the I/O cache, which resides between the host's physical memory and the bus-master DMA device, but not yet in the host's main memory. If the CPU accesses the memory, it might read the wrong data from the CPU cache. To ensure a consistent view of the memory for the CPU, you should call WDC_DMASyncIo() after a DMA transfer in order to flush the data from the I/O cache and update the CPU cache with the new data. The function also flushes additional caches and buffers between the device and memory, such as caches associated with bus extenders or bridges.
  • This function is currently only supported from the user mode.

B.3.41.WDC_IntEnable()

Purpose

Enables interrupt handling for the device.

On Linux and Windows 7 and higher, when attempting to enable interrupts for a PCI device that supports Extended Message-Signaled Interrupts (MSI-X) or Message-Signaled Interrupts (MSI) (and was installed with a relevant INF file — on Windows[9.2.7.1]), the function first tries to enable MSI-X or MSI; if this fails, or if the target OS does not support MSI/MSI-X, the function attempts to enable legacy level-sensitive interrupts (if supported by the device).
On Linux, you can use the function's dwOptions parameter to specify the types of PCI interrupts that may be enabled for the device (see the explanation in the parameter description).
For other types of hardware (PCI with no MSI/MSI-X support / ISA), the function attempts to enable the legacy interrupt type supported by the device (Level Sensitive / Edge Triggered) — see further information in Section9.2.

[Note]
When enabling interrupts using a Kernel PlugIn driver (fUseKP=TRUE), the Kernel PlugIn functions used to handle the interrupts are derived from the type of interrupts enabled for the device: for MSI/MSI-X, the KP_IntAtIrqlMSI and KP_IntAtDpcMSI functions are used; otherwise, the KP_IntAtIrql and KP_IntAtDpc functions are used.

If the caller selects to handle the interrupts in the kernel, using a Kernel PlugIn driver, the Kernel PlugIn KP_IntAtIrql[B.8.8] (legacy interrupts) or KP_IntAtIrqlMSI[B.8.10] (MSI/MSI-X) function, which runs at high interrupt request level (IRQL), will be invoked immediately when an interrupt is received.

The function can receive transfer commands information, which will be performed by WinDriver at the kernel, at high IRQ level, when an interrupt is received (see further information in Section9.2.6). If a Kernel PlugIn driver is used to handle the interrupts, any transfer commands set by the caller will be executed by WinDriver after the Kernel PlugIn KP_IntAtDpc or KP_IntAtDpcMSI function completes its execution.
When handling level-sensitive interrupts (such as legacy PCI interrupts) from the user mode, without a Kernel PlugIn driver, you must prepare and pass to the function transfer commands for acknowledging the interrupt. When using a Kernel PlugIn driver, the information for acknowledging the interrupts should be implemented in the Kernel PlugIn KP_IntAtIrql function[B.8.8], so the transfer commands in the call to WDC_IntEnable() are not required (although they can still be used).

The function receives a user-mode interrupt handler routine, which will be called by WinDriver after the kernel-mode interrupt processing is completed.
If the interrupts are handled using a Kernel PlugIn driver, the return value of the Kernel PlugIn deferred interrupt handler function — KP_IntAtDpc[B.8.9] (legacy interrupts) or KP_IntAtDpcMSI[B.8.11] (MSI/MSI-X) — will determine how many times (if at all) the user-mode interrupt handler will be called (provided KP_IntAtDpc or KP_IntAtDpcMSI itself is executed — which is determined by the return value of the Kernel PlugIn KP_IntAtIrql[B.8.8] or KP_IntAtIrqlMSI[B.8.10] function).

Prototype
DWORD DLLCALLCONV WDC_IntEnable(
    WDC_DEVICE_HANDLE hDev,
    WD_TRANSFER *pTransCmds,
    DWORD dwNumCmds,
    DWORD dwOptions,
    INT_HANDLER funcIntHandler,
    PVOID pData,
    BOOL fUseKP);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
pTransCmdsWD_TRANSFER*Input
dwNumCmdsDWORDInput
dwOptionsDWORDInput
funcIntHandler typedef void (*INT_HANDLER)(
  PVOID pData);
Input
pDataPVOIDInput
fUseKPBOOLInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
pTransCmds

An array of transfer commands information structures that define the operations to be performed at the kernel level upon the detection of an interrupt, or NULL if no transfer commands are required.

NOTE:
• Memory allocated for the transfer commands must remain available until the interrupts are disabled .
• When handling level-sensitive interrupts (such as legacy PCI interrupts) without a Kernel PlugIn[11], you must use this array to define the hardware-specific commands for acknowledging the interrupts in the kernel, immediately when they are received — see further information in Section9.2.

For an explanation on how to set the transfer commands, refer to the description of WD_TRANSFER in SectionB.7.10, and to the explanation in Section9.2.6.

dwNumCmds Number of transfer commands in the pTransCmds array
dwOptions A bit mask of interrupt handling flags — can be set to zero for no options, or to a combination of any of the following flags:
  • INTERRUPT_CMD_COPY: If set, WinDriver will copy any data read in the kernel as a result of a read transfer command, and return it to the user within the relevant transfer command structure.
    The user will be able to access the data from his user-mode interrupt handler routine (funcIntHandler).
The following flags are applicable only to PCI interrupts on Linux. If set, these flags determine the types of interrupts that may be enabled for the device — the function will attempt to enable only interrupts of the specified types, using the following precedence order, provided the type is reported as 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
funcIntHandler A user-mode interrupt handler callback function, which will be executed after an interrupt is received and processed in the kernel. (The prototype of the interrupt handler — INT_HANDLER — is defined in windrvr_int_thread.h).
pData Data for the user-mode interrupt handler callback routine (funcIntHandler)
fUseKP If TRUE — The device's Kernel PlugIn driver's KP_IntAtIrql[B.8.8] or KP_IntAtIrqlMSI[B.8.10] function, which runs at high interrupt request level (IRQL), will be executed immediately when an interrupt is received. The Kernel PlugIn driver to be used for the device is passed to WDC_xxxDeviceOpen() and stored in the WDC device structure.
If the caller also passes transfer commands to the function (pTransCmds), these commands will be executed by WinDriver at the kernel, at high IRQ level, after KP_IntAtIrql or KP_IntAtIrqlMSI completes its execution.
If the high-IRQL handler returns TRUE, the Kernel PlugIn deferred interrupt processing routine — KP_IntAtDpc[B.8.9] or KP_IntAtDpcMSI[B.8.11] — will be invoked. The return value of this function determines how many times (if at all) the user-mode interrupt handler (funcIntHandler) will be executed once the control returns to the user mode.
If FALSE — When an interrupt is received, any transfer commands set by the user in pTransCmds will be executed by WinDriver at the kernel, at high IRQ level, and the user-mode interrupt handler routine (funcIntHandler) will be executed when the control returns to the user mode.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function can be called from the user mode only.
  • The function enables interrupt handling in the software. After it returns successfully you must physically enable generation of interrupts in the hardware (you should be able to do so by writing to the device from the code).
  • A successful call to this function must be followed with a call to WDC_IntDisable() later on in the code, in order to disable the interrupts.
    The WDC_xxxDriverClose() functions (PCI:[B.3.12], ISA:[B.3.13]) call WDC_IntDisable() if the device's interrupts are enabled.
  • WinDriver must be registered with the OS as the driver of the device before enabling interrupts. For Plug-and-Play hardware (PCI/PCIExpress) on Windows platforms, this association is made by installing an INF file for the device[15.1]. If the INF file is not installed, WDC_IntEnable() will fail with a WD_NO_DEVICE_OBJECT error[B.11].

B.3.42.WDC_IntDisable()

Purpose

Disables interrupt interrupt handling for the device, pursuant to a previous call to WDC_IntEnable()[B.3.41].

Prototype
DWORD DLLCALLCONV WDC_IntDisable(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function can be called from the user mode only.

B.3.43.WDC_IntIsEnabled()

Purpose

Checks if a device's interrupts are currently enabled.

Prototype
BOOL DLLCALLCONV WDC_IntIsEnabled(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
Return Value

Returns TRUE if the device's interrupts are enabled; otherwise returns FALSE.

B.3.44.WDC_IntType2Str()

Purpose

Converts interrupt type to string.

Prototype
const CHAR * DLLCALLCONV WDC_IntType2Str(DWORD dwIntType);
Parameters
NameTypeInput/Output
dwIntTypeDWORDInput
Description
NameDescription
dwIntTypeInterrupt types bit-mask
Return Value

Returns the string representation that corresponds to the specified numeric code.

B.3.45.WDC_EventRegister()

Purpose

Registers the application to receive Plug-and-Play and power management events notifications for the device.

Prototype
DWORD DLLCALLCONV WDC_EventRegister(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwActions,
    EVENT_HANDLER funcEventHandler,
    PVOID pData,
    BOOL fUseKP);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
dwActionsDWORDInput
funcEventHandler typedef void (*EVENT_HANDLER)(
  WD_EVENT *pEvent,
  void *pData);
Input
pDataPVOIDInput
fUseKPBOOLInput
Description
NameDescription
hDevHandle to a Plug-and-Play WDC device, returned by WDC_PciDeviceOpen()[B.3.10]
dwActions A bit mask of flags indicating which events to register to:
Plug-and-Play events:
WD_INSERT — Device inserted
WD_REMOVE — Device removed
Device power state change events:
WD_POWER_CHANGED_D0 — Full power
WD_POWER_CHANGED_D1 — Low sleep
WD_POWER_CHANGED_D2 — Medium sleep
WD_POWER_CHANGED_D3 — Full sleep
WD_POWER_SYSTEM_WORKING — Fully on
Systems power state:
WD_POWER_SYSTEM_SLEEPING1 — Fully on but sleeping
WD_POWER_SYSTEM_SLEEPING2 — CPU off, memory on, PCI on
WD_POWER_SYSTEM_SLEEPING3 — CPU off, Memory is in refresh, PCI on aux power
WD_POWER_SYSTEM_HIBERNATE — OS saves context before shutdown
WD_POWER_SYSTEM_SHUTDOWN — No context saved
funcEventHandler A user-mode event handler callback function, which will be called when an event for which the caller registered to receive notifications (see dwActions) occurs. (The prototype of the event handler — EVENT_HANDLER — is defined in windrvr_events.h.)
pData Data for the user-mode event handler callback routine (funcEventHandler)
fUseKP If TRUE — When an event for which the caller registered to receive notifications (dwActions) occurs, the device's Kernel PlugIn driver's KP_Event function[B.8.5] will be called. (The Kernel PlugIn driver to be used for the device is passed to WDC_xxxDeviceOpen() and stored in the WDC device structure).
If this function returns TRUE, the user-mode events handler callback function (funcEventHandler) will be called when the kernel-mode event processing is completed.
If FALSE — When an event for which the caller registered to receive notifications (dwActions) occurs, the user-mode events handler callback function will be called.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function can be called from the user mode only.
  • A successful call to this function must be followed with a call to WDC_EventUnregister()[B.3.46] later on in the code, in order to unregister from receiving Plug-and-play and power management notifications from the device.

B.3.46.WDC_EventUnregister()

Purpose

Unregisters an application from a receiving Plug-and-Play and power management notifications for a device, pursuant to a previous call to WDC_EventRegister()[B.3.45].

Prototype
DWORD DLLCALLCONV WDC_EventUnregister(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a Plug-and-Play WDC device, returned by WDC_PciDeviceOpen()[B.3.10]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

Remarks
  • This function can be called from the user mode only.

B.3.47.WDC_EventIsRegistered()

Purpose

Checks if the application is currently registered to receive Plug-and-Play and power management notifications for the device.

Prototype
BOOL DLLCALLCONV WDC_EventIsRegistered(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a Plug-and-Play WDC device, returned by WDC_PciDeviceOpen()[B.3.10]
Return Value

Returns TRUE if the application is currently registered to receive Plug-and-Play and power management notifications for the device; otherwise returns FALSE.

B.3.48.WDC_SetDebugOptions()

Purpose

Sets debug options for the WDC library — see the description of WDC_DBG_OPTIONS[B.3.1.8] for details regarding the possible debug options to set.

This function is typically called at the beginning of the application, after the call to WDC_DriverOpen()[B.3.2], and can be re-called at any time while the WDC library is in use (i.e., WDC_DriverClose()[B.3.3] has not been called) in order to change the debug settings.

Until the function is called, the WDC library uses the default debug options — see WDC_DBG_DEFAULT[B.3.1.8].

When the function is recalled, it performs any required cleanup for the previous debug settings and sets the default debug options before attempting to set the new options specified by the caller.

Prototype
DWORD DLLCALLCONV WDC_SetDebugOptions(
    WDC_DBG_OPTIONS dbgOptions,
    const CHAR *sDbgFile);
Parameters
NameTypeInput/Output
dbgOptionsWDC_DBG_OPTIONSInput
sDbgFileconst CHAR*Input
Description
NameDescription
dbgOptions A bit mask of flags indicating the desired debug settings — see WDC_DBG_OPTIONS[B.3.1.8].
If this parameter is set to zero, the default debug options will be used — see WDC_DBG_DEFAULT[B.3.1.8].
sDbgFile WDC debug output file.
This parameter is relevant only if the WDC_DBG_OUT_FILE flag is set in the debug options (dbgOptions) (either directly or via one of the convenience debug options combinations — see WDC_DBG_OPTIONS[B.3.1.8]).
If the WDC_DBG_OUT_FILE debug flag is set and sDbgFile is NULL, WDC debug messages will be logged to the default debug file — stderr.
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.49.WDC_Err()

Purpose

Displays debug error messages according to the WDC debug options — see WDC_DBG_OPTIONS[B.3.1.8] and WDC_SetDebugOptions()[B.3.48].

Prototype
void DLLCALLCONV WDC_Err(
    const CHAR *format
    [, argument] ...);
Parameters
NameTypeInput/Output
formatconst CHAR*Input
argumentInput
Description
NameDescription
format Format-control string, which contains the error message to display. The string is limited to 256 characters (CHAR)
argumentOptional arguments for the format string
Return Value

None

B.3.50.WDC_Trace()

Purpose

Displays debug trace messages according to the WDC debug options — see WDC_DBG_OPTIONS[B.3.1.8] and WDC_SetDebugOptions()[B.3.48].

Prototype
void DLLCALLCONV WDC_Trace(
    const CHAR *format
    [, argument] ...);
Parameters
NameTypeInput/Output
formatconst CHAR*Input
argumentInput
Description
NameDescription
format Format-control string, which contains the trace message to display. The string is limited to 256 characters (CHAR)
argumentOptional arguments for the format string
Return Value

None

B.3.51.WDC_GetWDHandle()

Purpose

Returns a handle to WinDriver's kernel module, which is required by the basic WD_xxx WinDriver PCI/ISA API, described in the WinDriver PCI Low-Level API Reference (see Remarks below).

Prototype
HANDLE DLLCALLCONV WDC_GetWDHandle(void);
Return Value

Returns a handle to WinDriver's kernel module, or INVALID_HANDLE_VALUE in case of a failure

Remarks
  • When using only the WDC API, you do not need to get a handle to WinDriver, since the WDC library encapsulates this for you. This function enables you to get the WinDriver handles used by the WDC library so you can pass it to low-level WD_xxx API, if such APIs are used from your code. In such cases, take care not to close the handle you received (using WD_Close()). The handle will be closed by the WDC library when it is closed, using WDC_DriverClose()[B.3.3]. The low-level WD_xxx API is described in the WinDriver PCI Low-Level API Reference.

B.3.52.WDC_GetDevContext()

Purpose

Returns the device's user context information.

Prototype
PVOID DLLCALLCONV WDC_GetDevContext(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
Return Value

Returns a pointer to the device's user context, or NULL if no context has been set.

B.3.53.WDC_GetBusType()

Purpose

Returns the device's bus type: WD_BUS_PCI, WD_BUS_ISA or WD_BUS_UNKNOWN.

Prototype
WD_BUS_TYPE DLLCALLCONV WDC_GetBusType(WDC_DEVICE_HANDLE hDev);
Parameters
NameTypeInput/Output
hDevWDC_DEVICE_HANDLEInput
Description
NameDescription
hDevHandle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI[B.3.10] / ISA[B.3.11])
Return Value

Returns the device's bus type[B.7.1].

B.3.54.WDC_Sleep()

Purpose

Delays execution for the specified duration of time (in microseconds).
By default the function performs a busy sleep (consumes CPU cycles).

Prototype
DWORD DLLCALLCONV WDC_Sleep(
    DWORD dwMicroSecs,
    WDC_SLEEP_OPTIONS options);
Parameters
NameTypeInput/Output
dwMicroSecsDWORDInput
optionsWDC_SLEEP_OPTIONSInput
Description
NameDescription
dwMicroSecsThe number of microseconds to sleep
optionsSleep options[B.3.1.7]
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].

B.3.55.WDC_Version()

Purpose

Returns the version number of the WinDriver kernel module used by the WDC library.

Prototype
DWORD DLLCALLCONV WDC_Version(
    CHAR *sVersion,
    DWORD *pdwVersion);
Parameters
NameTypeInput/Output
sVersionCHAR*Output
pdwVersionDWORD*Output
Description
NameDescription
sVersion Pointer to a pre-allocated buffer to be filled by the function with the driver's version information string.
The size of the version string buffer must be at least 128 bytes (characters).
pdwVersion Pointer to a value indicating the version number of the WinDriver kernel module used by the WDC library
Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise[B.11].