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] type:

 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]):

Name	Description
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_LIC	Register 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]:

Name	Description
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: $\bullet$For user-mode applications: equivalent to setting WDC_DRV_OPEN_ALL ; $\bullet$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 Value	Description
WDC_READ	Read from the address
WDC_WRITE	Write 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 Value	Description
WDC_MODE_8	8 bits (1 byte) mode
WDC_MODE_16	16 bits (2 bytes) mode
WDC_MODE_32	32 bits (4 bytes) mode
WDC_MODE_64	64 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 Value	Description
WDC_RW_OPT_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.20] and WDC_WriteAddr8/16/32/64() [B.3.21] 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:

Name	Description
WDC_SIZE_8	8 bits (1 byte)
WDC_SIZE_16	16 bits (2 bytes)
WDC_SIZE_32	32 bits (4 bytes)
WDC_SIZE_64	64 bits (8 bytes)

B.3.1.7 WDC_SLEEP_OPTIONS Definitions

typedef DWORD WDC_SLEEP_OPTIONS;

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

Name	Description
WDC_SLEEP_BUSY	Perform busy sleep (consumes the CPU)
WDC_SLEEP_NON_BUSY	Perform non-busy sleep (does not consume the CPU)

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.49].

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

Name	Description
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.49]. 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:

Name	Description
WDC_DBG_LEVEL_ERR	Display only WDC error debug messages
WDC_DBG_LEVEL_TRACE	Display both error and trace WDC debug messages
WDC_DBG_NONE	Do not display WDC debug messages

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

$\bullet$User-mode and Kernel PlugIn convenience debug options:

Name	Description
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: $\bullet$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) $\bullet$From the Kernel PlugIn: WDC_DBG_OUT_DBM | WDC_DBG_LEVEL_TRACE : Send WDC error and trace messages to the Debug Monitor [6.2]

$\bullet$User-mode only convenience debug options:

Name	Description
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/PCMCIA device location information union type:

Name	Type	Description
$\bullet$ pciSlot	WD_PCI_SLOT	PCI device location information structure [B.5.8]
$\bullet$ pcmciaSlot	WD_PCMCIA_SLOT	PCMCIA device location information structure [B.5.9]

B.3.1.10 WDC_PCI_SCAN_RESULT Structure

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

Name	Type	Description
$\bullet$ dwNumDevices	DWORD	Number of devices found on the PCI bus that match the search criteria (vendor & device IDs)
$\bullet$ deviceId	WD_PCI_ID[WD_PCI_CARDS]	Array of matching vendor and device IDs found on the PCI bus [B.5.6]
$\bullet$ deviceSlot	WD_PCI_SLOT[WD_PCI_CARDS]	Array of PCI device location information structures [B.5.8] for the detected devices matching the search criteria

B.3.1.11 WDC_PCMCIA_SCAN_RESULT Structure

Structure type for holding the results of a PCMCIA bus scan (see WDC_PcmciaScanDevices() [B.3.6]):

Name	Type	Description
$\bullet$ dwNumDevices	DWORD	Number of devices found on the PCMCIA bus that match the search criteria (manufacturer & device IDs)
$\bullet$ deviceId	WD_PCMCIA_ID[WD_PCMCIA_CARDS]	Array of matching vendor and device IDs found on the PCMCIA bus [B.5.7]
$\bullet$ deviceSlot	WD_PCMCIA_SLOT[WD_PCMCIA_CARDS]	Array of PCMCIA device location information structures [B.5.9] for the detected devices matching the search criteria

B.3.2 WDC_DriverOpen()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$openOptions	WDC_DRV_OPEN_OPTIONS	Input
$\bullet$sLicense	const CHAR*	Input

DESCRIPTION

Name	Description
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.9].

B.3.3 WDC_DriverClose()

$\bullet$Closes the WDC WinDriver handle (acquired and stored by a previous call to WDC_DriverOpen() [B.3.2]) and un-initializes 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.9].

B.3.4 WDC_PciScanDevices()

PURPOSE

$\bullet$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 location.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciScanDevices(
    DWORD dwVendorId,
    DWORD dwDeviceId,
    WDC_PCI_SCAN_RESULT *pPciScanResult);

PARAMETERS

Name	Type	Input/Output
$\bullet$dwVendorId	DWORD	Input
$\bullet$dwDeviceId	DWORD	Input
$\bullet$pPciScanResult	WDC_PCI_SCAN_RESULT*	Output

DESCRIPTION

Name	Description
dwVendorId	Vendor ID to search for (hexadecimal). Zero (0) - all vendor IDs.
dwDeviceId	Device ID to search for (hexadecimal). Zero (0) - 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.9].

REMARKS

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

B.3.5 WDC_PciScanDevicesByTopology()

PURPOSE

$\bullet$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 location. The function performs a scan by topology.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciScanDevicesByTopology(
    DWORD dwVendorId,
    DWORD dwDeviceId,
    WDC_PCI_SCAN_RESULT *pPciScanResult);

PARAMETERS

Name	Type	Input/Output
$\bullet$dwVendorId	DWORD	Input
$\bullet$dwDeviceId	DWORD	Input
$\bullet$pPciScanResult	WDC_PCI_SCAN_RESULT*	Output

DESCRIPTION

Name	Description
dwVendorId	Vendor ID to search for (hexadecimal). Zero (0) - all vendor IDs.
dwDeviceId	Device ID to search for (hexadecimal). Zero (0) - 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.9].

REMARKS

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

B.3.6 WDC_PcmciaScanDevices()

PURPOSE

$\bullet$Scans the PCMCIA bus for all devices with the specified manufacturer and device ID combination and returns information regarding the matching devices that were found and their location.

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaScanDevices(
    WORD wManufacturerId,
    WORD wDeviceId,
    WDC_PCMCIA_SCAN_RESULT *pPcmciaScanResult);

PARAMETERS

Name	Type	Input/Output
$\bullet$wManufacturerId	WORD	Input
$\bullet$wDeviceId	WORD	Input
$\bullet$pPcmciaScanResult	WDC_PCMCIA_SCAN_RESULT*	Output

DESCRIPTION

Name	Description
wManufacturerId	Manufacturer ID to search for (hexadecimal). Zero (0) - all manufacturer IDs.
wDeviceId	Device ID to search for (hexadecimal). Zero (0) - all device IDs.
pPcmciaScanResult	A pointer to a structure that will be updated by the function with the results of the PCMCIA bus scan [B.3.1.11]

RETURN VALUE

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

REMARKS

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

B.3.7 WDC_PciGetDeviceInfo()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$pDeviceInfo	WD_PCI_CARD_INFO*	Input/Output
$\gg$ pciSlot	WD_PCI_SLOT	Input
$\gg$ Card	WD_CARD	Output

DESCRIPTION

Name	Description
pDeviceInfo	Pointer to a PCI device information structure [B.5.11]

RETURN VALUE

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

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 section 15.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.8 WDC_PcmciaGetDeviceInfo()

PURPOSE

$\bullet$Retrieves a PCMCIA device's resources information (memory and I/O ranges and interrupt information).

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaGetDeviceInfo(
    WD_PCMCIA_CARD_INFO *pDeviceInfo);

PARAMETERS

Name	Type	Input/Output
$\bullet$pDeviceInfo	WD_PCMCIA_CARD_INFO*	Input/Output
$\gg$ pcmciaSlot	WD_PCMCIA_SLOT	Input
$\gg$ Card	WD_CARD	Output
$\gg$ cVersion	CHAR	Output
$\gg$ cManufacturer	CHAR [WD_PCMCIA_ MANUFACTURER_LEN]	Output
$\gg$ cProductName	CHAR [WD_PCMCIA_ PRODUCTNAME_LEN]	Output
$\gg$ wManufacturerId	WORD	Output
$\gg$ wCardId	WORD	Output
$\gg$ wFuncId	WORD	Output

DESCRIPTION

Name	Description
pDeviceInfo	Pointer to a PCMCIA device information structure [B.5.12]

RETURN VALUE

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

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 PCMCIA configuration registers.
  Note: On Windows, you must install an INF file, which registers your device with WinDriver, before calling this function (see section 15.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.9 WDC_PciDeviceOpen()

PURPOSE

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

Among the operations performed by this function:

$\bullet$Verifies that a non-shareable memory or I/O resource on the device has not already been registered exclusively.

$\bullet$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.

$\bullet$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 (should be level sensitive for PCI), as well as retrieves and saves an interrupt handle, which are later used when the user calls functions to handle the device's interrupts.

$\bullet$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,
    PVOID reserved,
    const CHAR *pcKPDriverName,
    PVOID pKPOpenData);

PARAMETERS

Name	Type	Input/Output
$\bullet$ phDev	WDC_DEVICE_HANDLE*	Output
$\bullet$ pDeviceInfo	const WD_PCI_CARD_INFO*	Input
$\gg$ pciSlot	WD_PCI_SLOT	Input
$\gg$ Card	WD_CARD	Input
$\diamond$ dwItems	DWORD	Input
$\diamond$ Item	WD_ITEMS[WD_CARD_ITEMS]	Input
$\triangleright$ item	DWORD	Input
$\triangleright$ fNotSharable	DWORD	Input
$\triangleright$ I	union	Input
$\rightarrow$ Mem	struct	Input
$\star$ dwPhysicalAddr	DWORD	Input
$\star$ dwBytes	DWORD	Input
$\star$ dwTransAddr	DWORD	N/A
$\star$ dwUserDirectAddr	DWORD	N/A
$\star$ dwCpuPhysicalAddr	DWORD	N/A
$\star$ dwBar	DWORD	Input
$\rightarrow$ IO	struct	Input
$\star$ dwAddr	DWORD	Input
$\star$ dwBytes	DWORD	Input
$\star$ dwBar	DWORD	Input
$\rightarrow$ Int	struct	Input
$\star$ dwInterrupt	DWORD	Input
$\star$ dwOptions	DWORD	Input
$\star$ hInterrupt	DWORD	N/A
$\rightarrow$ Bus	struct	Input
$\star$ dwBusType	WD_BUS_TYPE	Input
$\star$ dwBusNum	DWORD	Input
$\star$ dwSlotFunc	DWORD	Input
$\rightarrow$ Val	struct	N/A
$\bullet$pDevCtx	const PVOID	Input
$\bullet$reserved	PVOID
$\bullet$pcKPDriverName	const CHAR*	Input
$\bullet$pKPOpenData	PVOID	Input

DESCRIPTION

Name	Description
phDev	Pointer to a handle to the WDC device allocated by the function
pDeviceInfo	Pointer to a PCI device information structure [B.5.11], which contains information regarding the device to open
pDevCtx	Pointer to device context information, which will be stored in the device structure
reserved	Reserved for future use
pcKPDriverName	Kernel PlugIn driver name. If your application does not use a Kernel PlugIn driver, pass a NULL pointer for this argument.
pKPOpenData	Kernel PlugIn driver open data to be passed to WD_KernelPlugInOpen() (see the WinDriver PCI Low-Level API Reference). If your application does not use a Kernel PlugIn driver, pass a NULL pointer for this argument.

RETURN VALUE

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

REMARKS

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

• If your card has a large memory range, which cannot be mapped entirely to the kernel virtual address space, you can modify the relevant item for this resource in the card resources information structure that you received from WDC_PciGetDeviceInfo() [B.3.7], and set the WD_ITEM_DO_NOT_MAP_KERNEL flag in the item's dwOptions field (pDeviceInfo->Card.Item[i].dwOptions) before passing the information structure (pDeviceInfo) to WDC_PciDeviceOpen(). This flag instructs the function to map the relevant memory range only to the user-mode virtual address space but not the kernel address space.

  NOTE that if you select to set the WD_ITEM_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 (pAddrDesc[i].kptAddr in the WDC_DEVICE structure [B.4.3] for the relevant memory range will not be updated) and you will therefore not be able to rely on this mapping in calls to WinDriver's API or when accessing the memory from a Kernel PlugIn driver.

B.3.10 WDC_PcmciaDeviceOpen()

PURPOSE

$\bullet$Allocates and initializes a WDC PCMCIA device structure, registers the device with WinDriver, and returns a handle to the device.

Among the operations performed by this function:

$\bullet$Verifies that a non-shareable memory or I/O resource on the device has not already been registered exclusively.

$\bullet$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.

$\bullet$Saves device resources information required for supporting future communication with the device. For example, the function saves the Interrupt Request (IRQ) number and the interrupt type (edge-triggered / level sensitive), as well as retrieves and saves an interrupt handle, which are later used when the user calls functions to handle the device's interrupts.

$\bullet$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_PcmciaDeviceOpen(
    WDC_DEVICE_HANDLE *phDev,
    const WD_PCMCIA_CARD_INFO *pDeviceInfo,
    const PVOID pDevCtx,
    PVOID reserved,
    const CHAR *pcKPDriverName,
    PVOID pKPOpenData);

PARAMETERS

Name	Type	Input/Output
$\bullet$ phDev	WDC_DEVICE_HANDLE*	Output
$\bullet$ pDeviceInfo	const WD_PCMCIA_CARD_INFO*	Input
$\gg$ pcmciaSlot	WD_PCMCIA_SLOT	Input
$\gg$ Card	WD_CARD	Input
$\diamond$ dwItems	DWORD	Input
$\diamond$ Item	WD_ITEMS[WD_CARD_ITEMS]	Input
$\triangleright$ item	DWORD	Input
$\triangleright$ fNotSharable	DWORD	Input
$\triangleright$ I	union	Input
$\rightarrow$ Mem	struct	Input
$\star$ dwPhysicalAddr	DWORD	Input
$\star$ dwBytes	DWORD	Input
$\star$ dwTransAddr	DWORD	N/A
$\star$ dwUserDirectAddr	DWORD	N/A
$\star$ dwCpuPhysicalAddr	DWORD	N/A
$\star$ dwBar	DWORD	Input
$\rightarrow$ IO	struct	Input
$\star$ dwAddr	DWORD	Input
$\star$ dwBytes	DWORD	Input
$\star$ dwBar	DWORD	Input
$\rightarrow$ Int	struct	N/A
$\star$ dwInterrupt	DWORD	Input
$\star$ dwOptions	DWORD	Input
$\star$ hInterrupt	DWORD	N/A
$\rightarrow$ Bus	struct	Input
$\star$ dwBusType	WD_BUS_TYPE	Input
$\star$ dwBusNum	DWORD	Input
$\star$ dwSlotFunc	DWORD	Input
$\rightarrow$ Val	struct	N/A
$\gg$ cVersion	CHAR	Input
$\gg$ cManufacturer	CHAR [WD_PCMCIA_ MANUFACTURER_LEN]	Input
$\gg$ cProductName	CHAR [WD_PCMCIA_ PRODUCTNAME_LEN]	Input
$\gg$ wManufacturerId	WORD	Input
$\gg$ wCardId	WORD	Input
$\gg$ wFuncId	WORD	Input
$\bullet$pDevCtx	const PVOID	Input
$\bullet$reserved	PVOID
$\bullet$pcKPDriverName	const CHAR*	Input
$\bullet$pKPOpenData	PVOID	Input

DESCRIPTION

Name	Description
phDev	Pointer to a handle to the WDC device allocated by the function
pDeviceInfo	Pointer to a PCMCIA device information structure [B.5.12], which contains information regarding the device to open
pDevCtx	Pointer to device context information, which will be stored in the device structure
reserved	Reserved for future use
pcKPDriverName	Kernel PlugIn driver name. If your application does not use a Kernel PlugIn driver, pass a NULL pointer for this argument.
pKPOpenData	Kernel PlugIn driver open data to be passed to WD_KernelPlugInOpen() (see the WinDriver PCI Low-Level API Reference). If your application does not use a Kernel PlugIn driver, pass a NULL pointer for this argument.

RETURN VALUE

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

REMARKS

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

• If your card has a large memory range, which cannot be mapped entirely to the kernel virtual address space, you can modify the relevant item for this resource in the card resources information structure that you received from WDC_PcmciaGetDeviceInfo() [B.3.8], and set the WD_ITEM_DO_NOT_MAP_KERNEL flag in the item's dwOptions field (pDeviceInfo->Card.Item[i].dwOptions) before passing the information structure (pDeviceInfo) to WDC_PcmciaDeviceOpen(). This flag instructs the function to map the relevant memory range only to the user-mode virtual address space but not the kernel address space.

  NOTE that if you select to set the WD_ITEM_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 (pAddrDesc[i]kptAddr in the WDC_DEVICE structure [B.4.3] for the relevant memory range will not be updated) and you will therefore not be able to rely on this mapping in calls to WinDriver's API or when accessing the memory from a Kernel PlugIn driver.

B.3.11 WDC_IsaDeviceOpen()

PURPOSE

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

Among the operations performed by this function:

$\bullet$Verifies that a non-shareable memory or I/O resource on the device has not already been registered exclusively.

$\bullet$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.

$\bullet$Saves device resources information required for supporting future communication with the device. For example, the function saves the Interrupt Request (IRQ) number and the interrupt type (edge-triggered / level sensitive), as well as retrieves and saves an interrupt handle, which are later used when the user calls functions to handle the device's interrupts.

$\bullet$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,
    PVOID reserved,
    const CHAR *pcKPDriverName,
    PVOID pKPOpenData);

PARAMETERS

Name	Type	Input/Output
$\bullet$ phDev	WDC_DEVICE_HANDLE*	Output
$\bullet$ pDeviceInfo	const WD_CARD*	Input
$\gg$ dwItems	DWORD	Input
$\gg$ Item	WD_ITEMS[WD_CARD_ITEMS]	Input
$\diamond$ item	DWORD	Input
$\diamond$ fNotSharable	DWORD	Input
$\diamond$ dwOptions	DWORD	Input
$\diamond$ I	union	Input
$\triangleright$ Mem	struct	Input
$\rightarrow$ dwPhysicalAddr	DWORD	Input
$\rightarrow$ dwBytes	DWORD	Input
$\rightarrow$ dwTransAddr	DWORD	N/A
$\rightarrow$ dwUserDirectAddr	DWORD	N/A
$\rightarrow$ dwCpuPhysicalAddr	DWORD	N/A
$\rightarrow$ dwBar	DWORD	Input
$\triangleright$ IO	struct	Input
$\rightarrow$ dwAddr	DWORD	Input
$\rightarrow$ dwBytes	DWORD	Input
$\rightarrow$ dwBar	DWORD	Input
$\triangleright$ Int	struct	Input
$\rightarrow$ dwInterrupt	DWORD	Input
$\rightarrow$ dwOptions	DWORD	Input
$\rightarrow$ hInterrupt	DWORD	N/A
$\triangleright$ Bus	struct	Input
$\rightarrow$ dwBusType	WD_BUS_TYPE	Input
$\rightarrow$ dwBusNum	DWORD	Input
$\rightarrow$ dwSlotFunc	DWORD	Input
$\triangleright$ Val	struct	N/A
$\bullet$pDevCtx	const PVOID	Input
$\bullet$reserved	PVOID	N/A
$\bullet$pcKPDriverName	const CHAR*	Input
$\bullet$pKPOpenData	PVOID	Input

DESCRIPTION

Name	Description
phDev	Pointer to a handle to the WDC device allocated by the function
pDeviceInfo	Pointer to a card information structure [B.5.10], which contains information regarding the device to open
pDevCtx	Pointer to device context information, which will be stored in the device structure
reserved	Reserved for future use
pcKPDriverName	Kernel PlugIn driver name. If your application does not use a Kernel PlugIn driver, pass a NULL pointer for this argument.
pKPOpenData	Kernel PlugIn driver open data to be passed to WD_KernelPlugInOpen() (see the WinDriver PCI Low-Level API Reference). If your application does not use a Kernel PlugIn driver, pass a NULL pointer for this argument.

RETURN VALUE

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

REMARKS

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

• If your card has a large memory range, which cannot be mapped entirely to the kernel virtual address space, you can set the WD_ITEM_DO_NOT_MAP_KERNEL flag for the relevant memory WD_ITEMS structure (pDeviceInfo->Card.Item[i].dwOptions) in order to instruct the function to map this memory range only to the user-mode virtual address space but not the kernel address space.

  NOTE that if you select to set the WD_ITEM_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 (pAddrDesc[i]kptAddr in the WDC_DEVICE structure [B.4.3] for the relevant memory range will not be updated) and you will therefore not be able to rely on this mapping in calls to WinDriver's API or when accessing the memory from a Kernel PlugIn driver.

B.3.12 WDC_PciDeviceClose()

PURPOSE

$\bullet$Un-initializes a WDC PCI device structure and frees the memory allocated for it.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciDeviceClose(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCI device structure, returned by WDC_PciDeviceOpen() [B.3.9]

RETURN VALUE

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

REMARKS

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

B.3.13 WDC_PcmciaDeviceClose()

PURPOSE

$\bullet$Un-initializes a WDC PCMCIA device structure and frees the memory allocated for it.

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaDeviceClose(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCMCIA device structure, returned by WDC_PcmciaDeviceOpen() [B.3.10]

RETURN VALUE

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

REMARKS

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

B.3.14 WDC_IsaDeviceClose()

PURPOSE

$\bullet$Un-initializes a WDC ISA device structure and frees the memory allocated for it.

PROTOTYPE

DWORD DLLCALLCONV WDC_IsaDeviceClose(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle 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.9].

REMARKS

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

B.3.15 WDC_CardCleanupSetup()

PURPOSE

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

• The application exists 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

Name	Type	Input/Output
$\bullet$ hDev	WDC_DEVICE_HANDLE	Input
$\bullet$ Cmd	WD_TRANSFER*	Input
$\bullet$ dwCmds	DWORD	Input
$\bullet$ bForceCleanup	BOOL	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
Cmd	Pointer to an array of cleanup transfer commands to be performed [B.5.14]
dwCmds	Number of cleanup commands in the Cmd array
bForceCleanup	If FALSE: The cleanup transfer commands (Cmd) will be performed in either of the following cases: $\bullet$When the application exist abnormally. $\bullet$When the application exits normally without closing the card by calling the relevant WDC_xxxDeviceClose() function (PCI [B.3.12] / PCMCIA [B.3.13] / ISA [B.3.14]). If TRUE: The cleanup transfer commands will be performed both in the two cases described above, as well as in the following case: $\bullet$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.9].

B.3.16 WDC_KernelPlugInOpen()

PURPOSE

$\bullet$Opens a handle to a Kernel PlugIn driver.

PROTOTYPE

DWORD DLLCALLCONV WDC_KernelPlugInOpen(
    WDC_DEVICE_HANDLE hDev,
    const CHAR *pcKPDriverName,
    PVOID pKPOpenData);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input/Output
$\bullet$pcKPDriverName	const CHAR*	Input
$\bullet$pKPOpenData	PVOID	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
pcKPDriverName	Kernel 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.9].

REMARKS

• Normally you do not need to call this function, since you can open a handle to a Kernel PlugIn driver when opening the handle to your device, as explained in the description of the WDC_xxxDeviceOpen() device open functions (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11]).
  This function is used for opening a handle to the Kernel PlugIn from a .NET application. The WinDriver Kernel PlugIn samples pass the address of the device handle to be allocated, i.e. the open function's phDev parameter, also as the the Kernel PlugIn's open data parameter (pKPOpenData). This is not supported in .NET, therefore the handle to the Kernel PlugIn is opened in a separate function call.

B.3.17 WDC_CallKerPlug()

PURPOSE

$\bullet$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.6.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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwMsg	DWORD	Input
$\bullet$pData	PVOID	Input/Output
$\bullet$pdwResult	pdwResult	Output

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
dwMsg	A message ID to pass to the Kernel PlugIn driver (specifically to KP_Call() [B.6.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.9].

B.3.18 WDC_ReadMemXXX()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$addr	DWORD	Input
$\bullet$off	DWORD	Input

DESCRIPTION

Name	Description
addr	The 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.19 WDC_WriteMemXXX()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$addr	DWORD	Input
$\bullet$off	DWORD	Input
$\bullet$val	BYTE / WORD / UINT32 / UINT64	Input

DESCRIPTION

Name	Description
addr	The memory address space to read from
off	The offset from the beginning of the specified address space (addr) to read from
val	The data to write to the specified address

RETURN VALUE

None

B.3.20 WDC_ReadAddrXXX()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwAddrSpace	DWORD	Input
$\bullet$dwOffset	KPTR	Input
$\bullet$val	BYTE* / WORD* / UINT32* / UINT64*	Output

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
dwAddrSpace	The 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.9].

B.3.21 WDC_WriteAddrXXX()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwAddrSpace	DWORD	Input
$\bullet$dwOffset	KPTR	Input
$\bullet$val	BYTE / WORD / UINT32 / UINT64	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
dwAddrSpace	The memory or I/O address space to write to
dwOffset	The offset from the beginning of the specified address space (dwAddrSpace) to write to
val	The data to write to the specified address

RETURN VALUE

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

B.3.22 WDC_ReadAddrBlock()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwAddrSpace	DWORD	Input
$\bullet$dwOffset	KPTR	Input
$\bullet$dwBytes	DWORD	Input
$\bullet$pData	PVOID	Output
$\bullet$mode	WDC_ADDR_MODE	Input
$\bullet$options	WDC_ADDR_RW_OPTIONS	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
dwAddrSpace	The memory or I/O address space to read from
dwOffset	The offset from the beginning of the specified address space (dwAddrSpace) to read from
dwBytes	The number of bytes to read
pData	Pointer to a buffer to be filled with the data that is read from the device
mode	The 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.9].

B.3.23 WDC_WriteAddrBlock()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwAddrSpace	DWORD	Input
$\bullet$dwOffset	KPTR	Input
$\bullet$dwBytes	DWORD	Input
$\bullet$pData	PVOID	Input
$\bullet$mode	WDC_ADDR_MODE	Input
$\bullet$options	WDC_ADDR_RW_OPTIONS	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
dwAddrSpace	The memory or I/O address space to write to
dwOffset	The offset from the beginning of the specified address space (dwAddrSpace) to write to
dwBytes	The number of bytes to write
pData	Pointer to a buffer that holds the data to write to the device
mode	The 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.9].

B.3.24 WDC_MultiTransfer()

PURPOSE

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

PROTOTYPE

DWORD DLLCALLCONV WDC_MultiTransfer(
    WD_TRANSFER *pTrans,
    DWORD dwNumTrans);

PARAMETERS

Name	Type	Input/Output
$\bullet$pTrans	WD_TRANSFER*
$\bullet$dwNumTrans	DWORD	Input

DESCRIPTION

Name	Description
pTrans	Pointer to an array of transfer commands information structures [B.5.14]
dwNumTrans	Number of transfer commands in the pTrans array

RETURN VALUE

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

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.25 WDC_AddrSpaceIsActive()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwAddrSpace	DWORD	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])
dwAddrSpace	The 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.26 WDC_PciReadCfgBySlot()

PURPOSE

$\bullet$Reads data from a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space (on Windows/Linux).
The device is identified by its location on the PCI bus.

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciReadCfgBySlot(
    WD_PCI_SLOT *pPciSlot,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);

PARAMETERS

Name	Type	Input/Output
$\bullet$pPciSlot	WD_PCI_SLOT*	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$pData	PVOID	Output
$\bullet$dwBytes	DWORD	Input

DESCRIPTION

Name	Description
pPciSlot	Pointer to a PCI device location information structure [B.5.8], 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
dwBytes	The number of bytes to read

RETURN VALUE

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

B.3.27 WDC_PciWriteCfgBySlot()

PURPOSE

$\bullet$Write data to a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space (on Windows/Linux).
The device is identified by its location on the PCI bus.

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciWriteCfgBySlot(
    WD_PCI_SLOT *pPciSlot,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);

PARAMETERS

Name	Type	Input/Output
$\bullet$pPciSlot	WD_PCI_SLOT*	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$pData	PVOID	Input
$\bullet$dwBytes	DWORD	Input

DESCRIPTION

Name	Description
pPciSlot	Pointer to a PCI device location information structure [B.5.8], 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
pData	Pointer to a data buffer that holds the data to write
dwBytes	The number of bytes to write

RETURN VALUE

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

B.3.28 WDC_PciReadCfg()

PURPOSE

$\bullet$Reads data from a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space (on Windows/Linux).
For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciReadCfg(
    WDC_DEVICE_HANDLE hDev, 
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$pData	PVOID	Output
$\bullet$dwBytes	DWORD	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCI device structure, returned by WDC_PciDeviceOpen() [B.3.9]
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
dwBytes	The number of bytes to read

RETURN VALUE

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

B.3.29 WDC_PciWriteCfg()

PURPOSE

$\bullet$Writes data to a specified offset in a PCI device's configuration space or a PCI Express device's extended configuration space (on Windows/Linux).

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

PROTOTYPE

DWORD DLLCALLCONV WDC_PciWriteCfg(
    WDC_DEVICE_HANDLE hDev, 
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$pData	PVOID	Input
$\bullet$dwBytes	DWORD	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCI device structure, returned by WDC_PciDeviceOpen() [B.3.9]
dwOffset	The offset from the beginning of the PCI configuration space to write to
pData	Pointer to a data buffer that holds the data to write
dwBytes	The number of bytes to write

RETURN VALUE

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

B.3.30 WDC_PciReadCfgBySlotXXX()

PURPOSE

$\bullet$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 (on Windows/Linux). The device is identified by its location on the PCI bus.

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

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

Name	Type	Input/Output
$\bullet$pPciSlot	WD_PCI_SLOT*	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$val	BYTE* / WORD* / UINT32* / UINT64*	Output

DESCRIPTION

Name	Description
pPciSlot	Pointer to a PCI device location information structure [B.5.8], 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.9].

B.3.31 WDC_PciWriteCfgBySlotXXX()

PURPOSE

$\bullet$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 (on Windows/Linux). The device is identified by its location on the PCI bus.

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

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

Name	Type	Input/Output
$\bullet$pPciSlot	WD_PCI_SLOT*	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$val	BYTE / WORD / UINT32 / UINT64	Input

DESCRIPTION

Name	Description
pPciSlot	Pointer to a PCI device location information structure [B.5.8], 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	The data to write to the PCI configuration space

RETURN VALUE

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

B.3.32 WDC_PciReadCfgXXX()

PURPOSE

$\bullet$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 (on Windows/Linux).

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$val	BYTE* / WORD* / UINT32* / UINT64*	Output

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCI device structure, returned by WDC_PciDeviceOpen() [B.3.9]
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.9].

B.3.33 WDC_PciWriteCfgXXX()

PURPOSE

$\bullet$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 (on Windows/Linux).

For Windows/Linux, all references to ''PCI'' in the description below also include PCI Express.

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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$val	BYTE / WORD / UINT32 / UINT64	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCI device structure, returned by WDC_PciDeviceOpen() [B.3.9]
dwOffset	The offset from the beginning of the PCI configuration space to read from
val	The data to write to the PCI configuration space

RETURN VALUE

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

B.3.34 WDC_PcmciaReadAttribSpace()

PURPOSE

$\bullet$Reads data from a specified offset in a PCMCIA device's attribute space.

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaReadAttribSpace(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$pData	PVOID	Output
$\bullet$dwBytes	DWORD	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCMCIA device structure, returned by WDC_PcmciaDeviceOpen() [B.3.10]
dwOffset	The offset from the beginning of the PCMCIA attribute space to read from
pData	Pointer to a buffer to be filled with the data that is read from the PCMCIA attribute space
dwBytes	The number of bytes to read

RETURN VALUE

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

B.3.35 WDC_PcmciaWriteAttribSpace()

PURPOSE

$\bullet$Writes data to a specified offset in a PCMCIA device's attribute space.

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaWriteAttribSpace(
    WDC_DEVICE_HANDLE hDev,
    DWORD dwOffset,
    PVOID pData,
    DWORD dwBytes);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwOffset	DWORD	Input
$\bullet$pData	PVOID	Input
$\bullet$dwBytes	DWORD	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCMCIA device structure, returned by WDC_PcmciaDeviceOpen() [B.3.10]
dwOffset	The offset from the beginning of the PCMCIA attribute space to write to
pData	Pointer to a data buffer that holds the data to write
dwBytes	The number of bytes to write

RETURN VALUE

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

B.3.36 WDC_PcmciaSetWindow()

PURPOSE

$\bullet$Modifies the settings of the PCMCIA bus controller's memory window.

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaSetWindow(
    WDC_DEVICE_HANDLE hDev,
    WD_PCMCIA_ACC_SPEED speed,
    WD_PCMCIA_ACC_WIDTH width,
    DWORD dwCardBase);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$speed	WD_PCMCIA_ACC_SPEED	Input
$\bullet$width	WD_PCMCIA_ACC_WIDTH	Input
$\bullet$dwCardBase	DWORD	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCMCIA device structure, returned by WDC_PcmciaDeviceOpen() [B.3.10]
speed	The access speed to the PCMCIA bus - see the WD_PCMCIA_ACC_SPEED enumeration [B.5.3]
width	The PCMCIA bus width - see the WD_PCMCIA_ACC_WIDTH enumeration [B.5.4]
dwCardBase	The offset in the PCMCIA device's memory from which the memory mapping begins

RETURN VALUE

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

B.3.37 WDC_PcmciaSetVpp()

PURPOSE

$\bullet$Modifies the power level of the PCMCIA bus controller's Voltage Power Pin (Vpp).

PROTOTYPE

DWORD DLLCALLCONV WDC_PcmciaSetVpp(
    WDC_DEVICE_HANDLE hDev,
    WD_PCMCIA_VPP vpp);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$vpp	WD_PCMCIA_VPP	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC PCMCIA device structure, returned by WDC_PcmciaDeviceOpen() [B.3.10]
vpp	The power level of the PCMCIA controller's Voltage Power Pin (Vpp) - see the WD_PCMCIA_VPP enumeration [B.5.5]

RETURN VALUE

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

B.3.38 WDC_DMAContigBufLock()

PURPOSE

$\bullet$Allocates a DMA buffer 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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$ppBuf	PVOID*	Output
$\bullet$dwOptions	DWORD	Input
$\bullet$dwDMABufSize	DWORD	Input
$\bullet$ppDma	WD_DMA**	Output

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11]). NOTE: This field can also be set to NULL in order to lock a contiguous physical memory buffer with no relation to a specific device.
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): $\bullet$DMA_FROM_DEVICE: Synchronize the DMA buffer for transfers from the device to memory. $\bullet$DMA_TO_DEVICE: Synchronize the DMA buffer for transfers from memory to the device. $\bullet$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). $\bullet$DMA_ALLOW_CACHE: Allow caching of the memory. $\bullet$DMA_CTG_KBUF_BELOW_16M: Allocate the physical DMA buffer within the lower 16MB of the main memory. $\bullet$DMA_ALLOW_64BIT_ADDRESS: Allow allocation of 64-bit DMA addresses, if supported by the target platform. This flag is supported on Windows, Linux and Solaris.
dwDMABufSize	The size (in bytes) of the DMA buffer
ppDma	Pointer to a pointer to a DMA buffer information structure [B.5.13], which is allocated by the function. The pointer to this structure (*ppDma) should be passed to WDC_DMABufUnlock() [B.3.40] when the DMA buffer is no longer needed.

RETURN VALUE

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

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 Solaris x86 platforms, for an allocation of a Contiguous DMA Buffer that is larger than the physical page size (4K), call WDC_DMAContigBufLock() with the DMA_KERNEL_ONLY_MAP flag (set within the dwOptions parameter). Then access the buffer by passing its kernel mapping, which is returned by the function in (*ppDma)->pKernelAddr [B.5.13], to WDC_ReadAddrBlock() [B.3.22] / WDC_WriteAddrBlock() [B.3.23] / WDC_MultiTransfer() [B.3.24], or to the low-level WD_Transfer() / WD_MultiTransfer() functions (see the WinDriver PCI Low-Level API Reference).

B.3.39 WDC_DMASGBufLock()

PURPOSE

$\bullet$Locks a pre-allocated user-mode memory buffer for DMA and returns the corresponding physical mappings of the locked DMA pages. On Windows 98/Me/2000/XP/Server 2003/Vista 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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$pBuf	PVOID	Input
$\bullet$dwOptions	DWORD	Input
$\bullet$dwDMABufSize	DWORD	Input
$\bullet$ppDma	WD_DMA**	Output

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [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): $\bullet$DMA_FROM_DEVICE: Synchronize the DMA buffer for transfers from the device to memory. $\bullet$DMA_TO_DEVICE: Synchronize the DMA buffer for transfers from memory to the device. $\bullet$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). $\bullet$DMA_ALLOW_CACHE: Allow caching of the memory. $\bullet$DMA_ALLOW_64BIT_ADDRESS: Allow allocation of 64-bit DMA addresses, if supported by the target platform. This flag is supported on Windows, Linux and Solaris.
dwDMABufSize	The size (in bytes) of the DMA buffer
ppDma	Pointer to a pointer to a DMA buffer information structure [B.5.13], which is allocated by the function. The pointer to this structure (*ppDma) should be passed to WDC_DMABufUnlock() [B.3.40] when the DMA buffer is no longer needed.

RETURN VALUE

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

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 Solaris, the user buffer address and size must be aligned on system memory page boundary. Use the aligned memory allocation function, valloc() (similar to malloc(), except the allocated memory blocks are aligned). On SPARC platforms, the virtual page size is usually 8 KB, and on x86 platforms, it is 4 KB.

B.3.40 WDC_DMABufUnlock()

PURPOSE

$\bullet$Unlocks and frees the memory allocated for a DMA buffer by a previous call to WDC_DMAContigBufLock() [B.3.38] or WDC_DMASGBufLock() [B.3.39].

PROTOTYPE

DWORD DLLCALLCONV WDC_DMABufUnlock(WD_DMA *pDma);

PARAMETERS

Name	Type	Input/Output
$\bullet$pDma	WD_DMA*	Input

DESCRIPTION

Name	Description
pDma	Pointer to a DMA information structure [B.5.13], received from a previous call to WDC_DMAContigBufLock() [B.3.38] (for a Contiguous DMA buffer) or WDC_DMASGBufLock() [B.3.39] (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.9].

REMARKS

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

B.3.41 WDC_DMASyncCpu()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$pDma	WD_DMA*	Input

DESCRIPTION

Name	Description
pDma	Pointer to a DMA information structure [B.5.13], received from a previous call to WDC_DMAContigBufLock() [B.3.38] (for a Contiguous DMA buffer) or WDC_DMASGBufLock() [B.3.39] (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.9].

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.42 WDC_DMASyncIo()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$pDma	WD_DMA*	Input

DESCRIPTION

Name	Description
pDma	Pointer to a DMA information structure, received from a previous call to WDC_DMAContigBufLock() [B.3.38] (for a Contiguous DMA buffer) or WDC_DMASGBufLock() [B.3.39] (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.9].

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.43 WDC_IntEnable()

PURPOSE

$\bullet$Enable interrupt handling for the device.

$\bullet$If the caller selects to handle the interrupts in the kernel, using a Kernel PlugIn driver, the Kernel PlugIn KP_IntAtIrql() function [B.6.8], which runs at high IRQ (Interrupt Request) level, will be invoked immediately when an an interrupt is received.

$\bullet$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. 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_IntAtIrql() function [B.6.8] completes its execution.
When handling level sensitive interrupts (such as 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.6.8], so the transfer commands are not required.

$\bullet$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.6.9]) will determine how many times (if at all) the user-mode interrupt handler will be called (provided KP_IntAtDpc() itself is executed - which is determined by the return value of the Kernel PlugIn KP_IntAtIrql() function [B.6.8]).

PROTOTYPE

DWORD DLLCALLCONV WDC_IntEnable(
    WDC_DEVICE_HANDLE hDev,
    WD_TRANSFER *pTransCmds,
    DWORD dwNumCmds,
    DWORD dwOptions,
    INT_HANDLER funcIntHandler,
    PVOID pData,
    BOOL fUseKP);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$pTransCmds	WD_TRANSFER*	Input
$\bullet$dwNumCmds	DWORD	Input
$\bullet$dwOptions	DWORD	Input
$\bullet$funcIntHandler	INT_HANDLER	Input
$\bullet$pData	PVOID	Input
$\bullet$fUseKP	BOOL	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [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: When handling level sensitive interrupts (such as PCI interrupts) without a Kernel PlugIn [], you must use this array to define the hardware-specific commands for acknowledging the interrupts in the kernel, immediately when they are received - see section 9.2 for details. For an explanation on how to set the transfer commands, refer to the description of WD_TRANSFER in section B.5.14.
dwNumCmds	Number of transfer commands in the pTransCmds array
dwOptions	A bit mask of interrupt handling flags. Can be zero for no option, or: $\bullet$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
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() function [B.6.8], which runs at high IRQ (Interrupt Request) level, 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() completes its execution. If KP_IntAtIrql() returns TRUE, the Kernel PlugIn deferred interrupt processing routine - KP_IntAtDpc() [B.6.9] - 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.9].

REMARKS

• This function can be called from the user mode only.
• The function enables interrupt handling in the software. After a successful call to this function you must physically enable generation of interrupts in the hardware (which you should be able to do by writing to the device from your 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], PCMCIA: [B.3.13], ISA: [B.3.14]) call WDC_IntDisable() if the device's interrupts are enabled.

B.3.44 WDC_IntDisable()

PURPOSE

$\bullet$Disables interrupt interrupt handling for the device, pursuant to a previous call to WDC_IntEnable() [B.3.43].

PROTOTYPE

DWORD DLLCALLCONV WDC_IntDisable(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])

RETURN VALUE

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

REMARKS

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

B.3.45 WDC_IntIsEnabled()

PURPOSE

$\bullet$Checks if a device's interrupts are currently enabled.

PROTOTYPE

BOOL DLLCALLCONV WDC_IntIsEnabled(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])

RETURN VALUE

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

B.3.46 WDC_EventRegister()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input
$\bullet$dwActions	DWORD	Input
$\bullet$funcEventHandler	WDC_EVENT_HANDLER	Input
$\bullet$pData	PVOID	Input
$\bullet$fUseKP	BOOL	Input

DESCRIPTION

Name	Description
hDev	Handle to a Plug and Play WDC device, returned by WDC_PciDeviceOpen() [B.3.9] or WDC_PcmciaDeviceOpen() [B.3.10]
dwActions	A bit mask of flags indicating which events to register to: Plug and Play events: $\bullet$WD_INSERT - Device inserted $\bullet$WD_REMOVE - Device removed Device power state change events: $\bullet$WD_POWER_CHANGED_D0 - Full power $\bullet$WD_POWER_CHANGED_D1 - Low sleep $\bullet$WD_POWER_CHANGED_D2 - Medium sleep $\bullet$WD_POWER_CHANGED_D3 - Full sleep $\bullet$WD_POWER_SYSTEM_WORKING - Fully on Systems power state: $\bullet$WD_POWER_SYSTEM_SLEEPING1 - Fully on but sleeping $\bullet$WD_POWER_SYSTEM_SLEEPING2 - CPU off, memory on, PCI/PCMCIA on $\bullet$WD_POWER_SYSTEM_SLEEPING3 - CPU off, Memory is in refresh, PCI/PCMCIA on aux power $\bullet$WD_POWER_SYSTEM_HIBERNATE - OS saves context before shutdown $\bullet$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.6.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.9].

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.47] later on in the code, in order to un-register from receiving Plug-and-play and power management notifications from the device.

B.3.47 WDC_EventUnregister()

PURPOSE

$\bullet$Un-registers 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.46].

PROTOTYPE

DWORD DLLCALLCONV WDC_EventUnregister(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a Plug and Play WDC device, returned by WDC_PciDeviceOpen() [B.3.9] or WDC_PcmciaDeviceOpen() [B.3.10]

RETURN VALUE

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

REMARKS

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

B.3.48 WDC_EventIsRegistered()

PURPOSE

$\bullet$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

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a Plug and Play WDC device, returned by WDC_PciDeviceOpen() [B.3.9] or WDC_PcmciaDeviceOpen() [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.49 WDC_SetDebugOptions()

PURPOSE

$\bullet$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.

$\bullet$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.

$\bullet$Until the function is called, the WDC library uses the default debug options - see WDC_DEBG_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

Name	Type	Input/Output
$\bullet$dbgOptions	WDC_DBG_OPTIONS	Input
$\bullet$sDbgFile	const CHAR*	Input

DESCRIPTION

Name	Description
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.9].

B.3.50 WDC_Err()

PURPOSE

$\bullet$Displays debug error messages according to the WDC debug options - see WDC_DBG_OPTIONS [B.3.1.8] and WDC_SetDebugOptions() [B.3.49].

PROTOTYPE

void DLLCALLCONV WDC_Err(
    const CHAR *format
     ...);

PARAMETERS

Name	Type	Input/Output
$\bullet$format	const CHAR*	Input
$\bullet$argument		Input

DESCRIPTION

Name	Description
format	Format-control string, which contains the error message to display. The string is limited to 256 characters (CHAR)
argument	Optional arguments for the format string

RETURN VALUE

None

B.3.51 WDC_Trace()

PURPOSE

$\bullet$Displays debug trace messages according to the WDC debug options - see WDC_DBG_OPTIONS [B.3.1.8] and WDC_SetDebugOptions() [B.3.49].

PROTOTYPE

void DLLCALLCONV WDC_Trace(
    const CHAR *format
     ...);

PARAMETERS

Name	Type	Input/Output
$\bullet$format	const CHAR*	Input
$\bullet$argument		Input

DESCRIPTION

Name	Description
format	Format-control string, which contains the trace message to display. The string is limited to 256 characters (CHAR)
argument	Optional arguments for the format string

RETURN VALUE

None

B.3.52 WDC_GetWDHandle()

PURPOSE

$\bullet$Returns a handle to WinDriver's kernel module, which is required by the basic WD_xxx WinDriver PCI/PCMCIA/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.53 WDC_GetDevContext()

PURPOSE

$\bullet$Returns the device's user context information.

PROTOTYPE

PVOID DLLCALLCONV WDC_GetDevContext(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])

RETURN VALUE

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

B.3.54 WDC_GetBusType()

PURPOSE

$\bullet$Returns the device's bus type: WD_BUS_PCI, WD_BUS_PCMCIA, WD_BUS_ISA or WD_BUS_UNKNOWN.

PROTOTYPE

WD_BUS_TYPE DLLCALLCONV WDC_GetBusType(WDC_DEVICE_HANDLE hDev);

PARAMETERS

Name	Type	Input/Output
$\bullet$hDev	WDC_DEVICE_HANDLE	Input

DESCRIPTION

Name	Description
hDev	Handle to a WDC device, returned by WDC_xxxDeviceOpen() (PCI [B.3.9] / PCMCIA [B.3.10] / ISA [B.3.11])

RETURN VALUE

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

B.3.55 WDC_Sleep()

PURPOSE

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

PROTOTYPE

DWORD DLLCALLCONV WDC_Sleep(
    DWORD dwMicroSecs,
    WDC_SLEEP_OPTIONS options);

PARAMETERS

Name	Type	Input/Output
$\bullet$dwMicroSecs	DWORD	Input
$\bullet$options	WDC_SLEEP_OPTIONS	Input

DESCRIPTION

Name	Description
dwMicroSecs	The number of microseconds to sleep
options	Sleep options [B.3.1.7]

RETURN VALUE

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

B.3.56 WDC_Version()

PURPOSE

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

PROTOTYPE

DWORD DLLCALLCONV WDC_Version(
    CHAR *sVersion,
    DWORD *pdwVersion);

PARAMETERS

Name	Type	Input/Output
$\bullet$sVersion	CHAR*	Output
$\bullet$pdwVersion	DWORD*	Output

DESCRIPTION

Name	Description
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.9].