CardMapWindow

The CardMapWindow function maps an area in PC Card memory or I/O space to system memory, and returns a pointer used to access the mapped region. Accessing a PC Card through a mapped memory window is faster than accessing the card through other PC Card Services functions; since the access is direct there is no time taken by an additional function call.

Syntax

PVOID CardMapWindow( CARD_WINDOW_HANDLE hCardWindow UINT32 uCardAddress UINT32 uSize PUINT32 pGranularity );

Parameters

hCardWindow
Specifies a handle to a memory window returned by a call to CardRequestWindow.
uCardAddress
Specifies a PC Card offset address.
uSize
Specifies the number of bytes to map.
pGranularity
Pointer to memory granularity of the mapped region. If the granularity is not one, then contiguous bytes on the PC Card cannot be accessed by contiguous memory addresses. If, for example, the granularity is four, then the bytes in the PC Card's memory is accessed as follows, where byte_number is the byte you wish to access:
pMemoryPointer[byte_number * pGranularity]

Return Values

If successful, CardMapWindow returns a PVOID pointer mapped to the requested region; otherwise the return value is NULL. If the return value is NULL, GetLastError returns one of the following values.

Value Description
CERR_BAD_ARGS Indicates an invalid uCardAddress specification or pGranularity pointer.
CERR_BAD_HANDLE Indicates an invalid hCardWindow driver handle.
CERR_BAD_SIZE Indicates the value specified for uSize is invalid.
CERR_OUT_OF_RESOURCE Indicates Card Services is unable to set up a memory window to read the CIS.

Remarks

If this function fails, a previous mapping of the window might be invalid.

The offset from the returned mapped virtual address must be multiplied by the value pointed to by pGranularity.

The address returned by CardMapWindow can be used to directly access the PC Card. Drivers should access the memory in a try/except routine to avoid faulting the system on card removal.

The returned pointer to the mapped PC Card memory is marked as non-cached shared memory. This guarantees that a PC Card device and its driver detect the same information when they access the same memory location.

To provide reliable access to the mapped PC Card memory, driver code should declare the pointer to the PC Card memory with the volatile type qualifier.

Most Windows CE plstforms uses three fixed memory mapped ranges to access the PC Card address spaces (attribute memory, I/O and common memory). The address returned from CardMapWindow is a virtual address mapped to the physical address that corresponds to the caller's request. Multiple drivers are prevented from allocating overlapping ranges within each address space, though multiple allocations are allowed within each space. A single driver is allowed to map a range that overlaps its own previously allocated ranges.

On Windows CE platforms that support programmable windows via a standard PC Card socket controller, a combination of fixed memory mapped ranges and programmable ranges is used. If the requested range cannot be mapped within one of the fixed regions, then one of the programmable regions might be used. To avoid memory contention, Windows CE ensures that only one mapped range exists within a programmable range. The programmable ranges are not large (about 32K), but they can access anywhere within the 64M PC Card address space.

See Also

CARD_WINDOW_HANDLE, CardRequestWindow