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 中定義的其中一個錯誤碼。

備註

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

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

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

如果驅動程式將 UmdfRegisterAccessMode INF 指示詞設定為 RegisterAccessUsingUserModeMapping，則呼叫 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