2.6.WD_CardRegister()

Purpose

Card registration function.
The function

Prototype
DWORD WD_CardRegister(
    HANDLE hWD,
    WD_CARD_REGISTER *pCardReg);
Parameters
NameTypeInput/Output
hWDHANDLEInput
pCardRegWD_CARD_REGISTER*
CardWD_CARD
*dwItemsDWORDInput
*ItemWD_ITEMS[WD_CARD_ITEMS]
itemDWORDInput
fNotSharableDWORDInput
Iunion
*Memstruct
pPhysicalAddrPHYS_ADDRInput
qwBytesUINT64Input
pTransAddrKPTROutput
pUserDirectAddrUPTROutput
dwBarDWORDInput
dwOptionsDWORDInput
pReservedKPTRN/A
*IOstruct
pAddrKPTRInput
dwBytesDWORDInput
dwBarDWORDInput
*Intstruct
dwInterruptDWORDInput
dwOptionsDWORDInput
hInterruptDWORDOutput
dwReserved1DWORDN/A
pReserved2KPTRN/A
*BusWD_BUS
dwBusTypeWD_BUS_TYPEInput
dwBusNumDWORDInput
dwSlotFuncDWORDInput
fCheckLockOnlyDWORDInput
hCardDWORDOutput
dwOptionsDWORDInput
cNameCHAR[32]Input
cDescriptionCHAR[100]Input
Description
NameDescription
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open()[5.2]
pCardRegPointer to a card registration information structure:
Card Card information structure. For a PCI device it is recommended to pass the card structure received from a previous call to WD_PciGetCardInfo()[2.4] — refer to Remark1 in this section.
*dwItemsNumber of items detected on the card
*ItemCard items information structure:
item Item type — ITEM_MEMORY, ITEM_IO, ITEM_INTERRUPT, or ITEM_BUS
fNotSharable
  • 1 — Non-sharable resource; should be locked for exclusive use
  • 0 — Sharable resource
I Specific data according to the item type (pCardReg->Card.Item.item)
*Mem Memory-item descriptor (type=ITEM_MEMORY)
pPhysicalAddr First address of the physical memory range.
For PCI, this field is ignored and the physical address is retrieved directly from the card, because the 32-bit field size cannot correctly store 64-bit addresses.
qwBytesLength (in bytes) of the memory range
pTransAddr Kernel-mode mapping of the memory range's physical base address.
This address should be used when setting the memory address in calls to WD_Transfer()[2.9] or WD_MultiTransfer()[2.10] or when accessing memory directly from a Kernel PlugIn driver.
pUserDirectAddr User-mode mapping of the memory range's physical base address.
This address should be used for accessing a memory address directly from a user-mode process.
dwBarBase Address Register number of PCI card
dwOptions A bit-mask of memory-item registration flags — a combination of any of the of the following WD_ITEM_MEM_OPTIONS enumeration values:
  • WD_ITEM_MEM_DO_NOT_MAP_KERNEL: Avoid mapping the item's physical memory to the kernel address space (I.Mem.pTransAddr not set); map the memory only to the user-mode virtual address space (mapped base address: I.Mem.pUserDirectAddr). For more information, refer to Remark2 in this section.
    NOTE: This flag is applicable only to memory items.
  • WD_ITEM_MEM_ALLOW_CACHE (Windows): Map the item's physical memory (base address: I.Mem.pPhysicalAddr) as cached.
    NOTE: This flag is applicable only to memory items that pertain to the host's RAM, as opposed to local memory on the card.
*IO I/O-item descriptor (type=ITEM_IO)
pAddrFirst address of the I/O range
dwBytesLength of the I/O range, in bytes
dwBarBase Address Register (BAR) number for the I/O range
*Int Interrupt-item descriptor (type=ITEM_INTERRUPT)
dwInterruptPhysical interrupt request (IRQ) number
dwOptions Interrupt options bit-mask, which can consist of a combination of any of the following flags:
Interrupt type flags:
NOTE: In the call to WD_CardRegister() the interrupt type flags are appliable only to ISA devices. For Plug-and-Play hardware (PCI) the function retrieves the supported interrupt types independently.
INTERRUPT_LEVEL_SENSITIVE — indicates that the device supports level-sensitive interrupts.
INTERRUPT_LATCHED — indicates that the device supports legacy edge-triggered interrupts.
The value of this flag is zero, therefore it is applicable only when no other interrupt flag is set.
Miscellaneous interrupt flags:
hInterrupt An interrupt handle to be used in calls to InterruptEnable()[2.17] or WD_IntEnable()[3.2].
*Bus Bus-item descriptor (type=ITEM_BUS)
dwBusType The card's bus type — any of the following WD_BUS_TYPE enumeration values:
WD_BUS_PCI — PCI bus
WD_BUS_ISA — ISA bus
WD_BUS_EISA — EISA bus
dwBusNumBus number
dwSlotFunc A combination of the card's bus slot/socket and function numbers: the lower three bits represent the function number and the remaining bits represent the slot/socket number. For example: a value of 0x80 (<=> 10000000 binary) corresponds to a function number of 0 (lower 3 bits: 000) and a slot/socket number of 0x10 (remaining bits: 10000).
fCheckLockOnly Set to TRUE to check if the defined card resources can be locked (in which case hCard will be set to 1), or whether they are already locked for exclusive use. When this flag is set to TRUE the function doesn't actually locking the specified resources.
hCard Handle to the card resources defined in the Card field. This handle should later be passed to WD_CardUnregister()[2.8] in order to free the resources. If the card registration fails, this field is set to 0.
When fCheckLockOnly is set to TRUE, hCard is set to 1 if the card's resources can be be locked successfully (i.e., the resources aren't currently locked for exclusive use), or 0 otherwise.
dwOptionsShould always be set to zero
cName Card name (optional)
cDescriptionCard description (optional)
Return Value

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

Remarks
  1. For PCI the cardReg.Card input resources information should be retrieved from the Plug-and-Play Manager via WD_PciGetCardInfo()[2.4].
  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 that you pass to the card registration function (pCardReg->Card.Item[i].I.Mem.dwOptions). 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. (For PCI devices, you can modify the relevant item in the card information structure (pCard) that you received from WD_PciGetCardInfo()[2.4] before passing this structure to WD_CardRegister().)

    [Note]
    Note that if you select to set the WD_ITEM_MEM_DO_NOT_MAP_KERNEL flag, WD_CardRegister() will not update the item's pTransAddr field with a kernel mapping of the memory's base address, 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.
  3. WD_CardRegister() enables the user to map the card memory resources into virtual memory and access them as regular pointers.
Example
WD_CARD_REGISTER cardReg;
BZERO(cardReg);
cardReg.Card.dwItems = 1;
cardReg.Card.Item[0].item = ITEM_IO;
cardReg.Card.Item[0].fNotSharable = 1;
cardReg.Card.Item[0].I.IO.pAddr = 0x378;
cardReg.Card.Item[0].I.IO.dwBytes = 8;
WD_CardRegister(hWD, &cardReg);
if (cardReg.hCard == 0)
{
    printf("Failed locking device\n");
    return FALSE;
}