Jungo WinDriver  
Official Documentation

◆ WDC_PciDeviceOpen()

DWORD DLLCALLCONV WDC_PciDeviceOpen ( _Outptr_ WDC_DEVICE_HANDLE phDev,
_In_ const WD_PCI_CARD_INFO pDeviceInfo,
_In_ const PVOID  pDevCtx 
)

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


Open/Close device

  • Verifies that none of the registered device resources (set in pDeviceInfo->Card.Item) are already locked for exclusive use.
  • 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.
Parameters
[out]phDevPointer to a handle to the WDC device allocated by the function
[in]pDeviceInfoPointer to a card information structure, which contains information regarding the device to open
[in]pDevCtxPointer to device context information, which will be stored in the device structure
Returns
Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise
int main(void)
{
DWORD dwStatus;
WD_PCI_SLOT slot = {0, 0, 0, 0}; /* Replace domain/bus/slot/function with your own */
WD_PCI_CARD_INFO deviceInfo;
BYTE bData = 0x1;
WORD wData = 0x2;
UINT32 u32Data = 0x3;
UINT64 u64Data = 0x4;
/* Make sure to fully initialize WinDriver! */
if (!WD_DriverName(DEFAULT_DRIVER_NAME))
{
printf("Failed to set the driver name for WDC library.\n");
return WD_INTERNAL_ERROR;
}
if (WD_STATUS_SUCCESS != dwStatus)
{
printf("Failed to initialize debug options for WDC library.\n"
"Error 0x%lx - %s\n", dwStatus, Stat2Str(dwStatus));
return dwStatus;
}
/* Open a handle to the driver and initialize the WDC library */
dwStatus = WDC_DriverOpen(WDC_DRV_OPEN_DEFAULT, DEFAULT_LICENSE_STRING);
if (WD_STATUS_SUCCESS != dwStatus)
{
printf("Failed to initialize the WDC library. Error 0x%lx - %s\n",
dwStatus, Stat2Str(dwStatus));
return dwStatus;
}
BZERO(deviceInfo);
deviceInfo.pciSlot = slot;
dwStatus = WDC_PciGetDeviceInfo(&deviceInfo);
if (WD_STATUS_SUCCESS != dwStatus)
{
printf("Failed retrieving the device's resources "
"information. Error [0x%lx - %s]\n", dwStatus, Stat2Str(dwStatus));
goto Exit;
}
/* Open a device handle */
dwStatus = WDC_PciDeviceOpen(&hDev, &deviceInfo, NULL);
if (WD_STATUS_SUCCESS != dwStatus)
{
printf("Failed opening a WDC device handle. Error 0x%lx - %s\n",
dwStatus, Stat2Str(dwStatus));
goto Exit;
}
/* Read/Write memory examples: */
/* Check BYTE */
dwResult = WDC_WriteAddrBlock8(hDev, MEM_SPACE, REG, 1,
if (dwResult)
goto Exit;
dwResult = WDC_ReadAddrBlock8(hDev, MEM_SPACE, REG, 1,
if (dwResult)
goto Exit;
/* Check WORD */
dwResult = WDC_WriteAddrBlock16(hDev, MEM_SPACE, REG, 2,
if (dwResult)
goto Exit;
dwResult = WDC_ReadAddrBlock16(hDev, MEM_SPACE, REG, 2,
if (dwResult)
goto Exit;
/* Check UINT32 */
dwResult = WDC_WriteAddrBlock32(hDev, MEM_SPACE, REG, 4,
&u32Data, WDC_ADDR_RW_DEFAULT);
if (dwResult)
goto Exit;
dwResult = WDC_ReadAddrBlock32(hDev, MEM_SPACE, REG, 4,
&u32Data, WDC_ADDR_RW_DEFAULT);
if (dwResult)
goto Exit;
/* Check UINT64 */
dwResult = WDC_WriteAddrBlock64(hDev, MEM_SPACE, REG, 8,
&u64Data, WDC_ADDR_RW_DEFAULT);
if (dwResult)
goto Exit;
dwResult = WDC_ReadAddrBlock64(hDev, MEM_SPACE, REG, 8,
&u64Data, WDC_ADDR_RW_DEFAULT);
if (dwResult)
goto Exit;
Exit:
if (hDev)
{
dwStatus = WDC_PciDeviceClose(hDev);
if (WD_STATUS_SUCCESS != dwStatus)
{
printf("Failed closing a WDC device handle (0x%p). Error 0x%lx "
"- %s\n", hDev, dwStatus, Stat2Str(dwStatus));
}
}
}
#define NULL
Definition: kpstdlib.h:268
const char *DLLCALLCONV Stat2Str(_In_ DWORD dwStatus)
Retrieves the status string that corresponds to a status code.
WD_PCI_SLOT pciSlot
PCI slot information.
Definition: windrvr.h:925
#define WDC_ReadAddrBlock8(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_ReadAddrBlock with 1 byte mode.
Definition: wdc_lib.h:959
#define WDC_WriteAddrBlock8(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_WriteAddrBlock with 1 byte mode.
Definition: wdc_lib.h:983
DWORD DLLCALLCONV WDC_SetDebugOptions(_In_ WDC_DBG_OPTIONS dbgOptions, _In_ const CHAR *pcDbgFile)
Sets debug options for the WDC library - see the description of WDC_DBG_OPTIONS for details regarding...
DWORD DLLCALLCONV WDC_PciDeviceOpen(_Outptr_ WDC_DEVICE_HANDLE *phDev, _In_ const WD_PCI_CARD_INFO *pDeviceInfo, _In_ const PVOID pDevCtx)
Allocates and initializes a WDC PCI device structure, registers the device with WinDriver,...
#define WDC_WriteAddrBlock32(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_WriteAddrBlock with 4 bytes mode.
Definition: wdc_lib.h:995
#define WDC_DRV_OPEN_DEFAULT
Definition: wdc_lib.h:69
DWORD DLLCALLCONV WDC_DriverClose(void)
Closes the WDC WinDriver handle (acquired and stored by a previous call to WDC_DriverOpen()) and unin...
DWORD DLLCALLCONV WDC_PciDeviceClose(_In_ WDC_DEVICE_HANDLE hDev)
Uninitializes a WDC PCI device structure and frees the memory allocated for it.
#define WDC_ReadAddrBlock32(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_ReadAddrBlock with 4 bytes mode.
Definition: wdc_lib.h:971
#define WDC_DBG_DEFAULT
Convenient debug options combinations/defintions.
Definition: wdc_lib.h:86
DWORD DLLCALLCONV WDC_PciGetDeviceInfo(_Inout_ WD_PCI_CARD_INFO *pDeviceInfo)
Retrieves a PCI device's resources information (memory and I/O ranges and interrupt information).
@ WDC_ADDR_RW_DEFAULT
Default: memory resource - direct access; autoincrement on block transfers.
Definition: wdc_lib.h:124
#define WDC_WriteAddrBlock64(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_WriteAddrBlock with 8 bytes mode.
Definition: wdc_lib.h:1001
#define WDC_ReadAddrBlock16(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_ReadAddrBlock with 2 bytes mode.
Definition: wdc_lib.h:965
#define WDC_ReadAddrBlock64(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_ReadAddrBlock with 8 bytes mode.
Definition: wdc_lib.h:977
DWORD DLLCALLCONV WDC_DriverOpen(_In_ WDC_DRV_OPEN_OPTIONS openOptions, _In_ const CHAR *pcLicense)
Opens and stores a handle to WinDriver's kernel module and initializes the WDC library according to t...
void * WDC_DEVICE_HANDLE
Handle to device information struct.
Definition: wdc_lib.h:33
#define WDC_WriteAddrBlock16(hDev, dwAddrSpace, dwOffset, dwBytes, pData, options)
WDC_WriteAddrBlock with 2 bytes mode.
Definition: wdc_lib.h:989
unsigned short int WORD
Definition: windrvr.h:333
unsigned char BYTE
Definition: windrvr.h:332
@ WD_STATUS_SUCCESS
[0] Operation completed successfully
Definition: windrvr.h:1066
#define BZERO(buf)
Definition: windrvr.h:1553
const char *DLLCALLCONV WD_DriverName(const char *sName)
Sets the name of the WinDriver kernel module, which will be used by the calling application.
unsigned __int64 UINT64
Definition: windrvr.h:314
unsigned int UINT32
Definition: windrvr.h:337