IWDFDevice3：：MapIoSpace 方法 （wudfddi.h）

[警告： UMDF 2 是最新版本的 UMDF，並取代 UMDF 1。 所有新的UMDF驅動程式都應該使用UMDF 2撰寫。 未將新功能新增至 UMDF 1，而且較新版本的 Windows 10 上對 UMDF 1 的支援有限。 通用 Windows 驅動程式必須使用 UMDF 2。 如需詳細資訊，請參閱 開始使用 UMDF。]

MapIoSpace 方法會將指定的實體位址範圍對應至系統地址空間，並傳回虛擬基位址。

語法

HRESULT MapIoSpace(
  [in]  PHYSICAL_ADDRESS    PhysicalAddress,
  [in]  SIZE_T              NumberOfBytes,
  [in]  MEMORY_CACHING_TYPE CacheType,
  [out] void                **pPseudoBaseAddress
);

參數

[in] PhysicalAddress

指定要對應之 I/O 範圍的起始 64 位實體位址。

[in] NumberOfBytes

指定大於零的值，表示要對應的位元元組數目。

[in] CacheType

指定 MEMORY_CACHING_TYPE 值，指出用來對應實體位址範圍的快取屬性。 MEMORY_CACHING_TYPE列舉類型定義於 Wudfwdm.h 中。

[out] pPseudoBaseAddress

接收虛擬基位址指標的位置位址。

傳回值

如果作業成功，此方法會傳回S_OK。 否則，此方法會傳回 Winerror.h 中定義的其中一個錯誤碼。

言論

如果驅動程式在裝置啟動時收到 CmResourceTypeMemory 類型的翻譯資源，則驅動程式必須在裝置啟動期間呼叫這個方法，CM_PARTIAL_RESOURCE_DESCRIPTOR 結構中。 MapIoSpace 將資源清單中傳回的實體位址對應至稱為虛擬基位址的架構管理位址。

然後，驅動程式可以使用虛擬基位址來存取READ_REGISTER_Xxx 和WRITE_REGISTER_Xxx 函式的裝置緩存器。 如需範例，請參閱在 UMDF 1.x 驅動程式中 讀取和寫入至裝置快取器。

呼叫 MapIoSpace 的驅動程式必須將 UmdfDirectHardwareAccess INF 指示詞設定為 AllowDirectHardwareAccess。

如果驅動程式將 UmdfRegisterAccessMode INF 指示詞設定為 RegisterAccessUserModeMapping，則呼叫 MapIoSpace 也會將指定的實體位址範圍對應至驅動程式後續可透過 呼叫 getHardwareRegisterMappedAddress存取的使用者模式基地址範圍。

如需 UMDF 驅動程式可以使用之 INF 指示詞的詳細資訊，請參閱 在 INF 檔案中指定 WDF 指示詞。

PHYSICAL_ADDRESS類型定義於 Wudfwdm.h 中，如下所示：

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

例子

在下列程式代碼範例中，UMDF 驅動程式會使用其 IPnpCallbackHardware2：：OnPrepareHardware 回呼函式來檢查其記憶體對應的緩存器資源，並將其對應至使用者模式地址空間。 然後，此範例會實作可存取記憶體位置的 WriteToDevice 方法。 驅動程式接著會從其 IPnpCallbackHardware2：：OnReleaseHardware 回呼呼叫 UnmapIoSpace。 驅動程式的 INF 檔案必須啟用 UMDF 硬體存取功能，方法是將 UmdfDirectHardwareAccess 指示詞設定為 AllowDirectHardwareAccess。

HRESULT
CMyDevice::OnPrepareHardware(
    __in IWDFDevice3 * pWdfDevice,
    __in IWDFCmResourceList * pRaw,
    __in IWDFCmResourceList * pTrans
    ) 
{
    PCM_PARTIAL_RESOURCE_DESCRIPTOR desc = NULL;
    PHYSICAL_ADDRESS regBasePA = {0};
    ULONG regLength = 0;
    BOOLEAN found = FALSE;
    HRESULT hr = S_OK;

    //
    // Scan the list to identify our resource.
    //
    for (i=0; i < pWdfResTranslated->GetCount(); i++) {
        desc = (PCM_PARTIAL_RESOURCE_DESCRIPTOR) pTrans->GetDescriptor(i);

        switch (desc->Type) {
            case CmResourceTypeMemory:
                //
                // See if this is the memory resource we’re looking for.
                // 
                if (desc->u.Memory.Length == 0x200) {
                    regsBasePA = desc->u.Memory.Start;
                    regsLength = desc->u.Memory.Length;
                    found = TRUE;                    
                }
                break;

            default:
                // Ignore all other descriptors.
                break;
        }
    }

    //
    // Map the resource. Store the register base in partner device
    // object for later access.
    //
    if (found) {
            hr = pWdfDevice->MapIoSpace(regBasePA,
                                           regLengthlength, 
                                           MmNonCached,
                                          (void **)&m_RegBase);
            if (SUCCEEDED(hr)) {
            //
            // Store the register range in partner object. This will 
            // be needed for unmapping.
            //
            m_RegLength = regLength;
        }
    }

    …
}

//
// UMDF driver uses one of the register access APIs such as
// WRITE_REGISTER_Xxx or READ_REGISTER_Xxx macros to access device register.
//
VOID
CMyQueue::WriteToDevice(
    __in IWDFDevice3* pWdfDevice,
    __in UCHAR Value
    )
{
    //
    // Write the UCHAR value at offset 2 from register base.
    //
    WRITE_REGISTER_UCHAR(pWdfDevice, 
                      (m_MyDevice->m_RegBase)+2, 
                       Value);
}

HRESULT
CMyDevice::OnReleaseHardware(
    __in IWDFDevice3 * pWdfDevice,
    __in IWDFCmResourceList * pTrans
    )
{
    //
    // Unmap registers memory resource.
    //
    pWdfDevice->UnmapIoSpace(m_RegBase, m_RegLength);

    return S_OK;
}

要求

要求	價值
終止支援	UMDF 2.0 和更新版本中無法使用。
目標平臺	桌面
最低 UMDF 版本	1.11
標頭	wudfddi.h
DLL	WUDFx.dll

另請參閱

IWDFDevice3