Метод IWDFDevice3::MapIoSpace (wudfddi.h)

[Предупреждение: UMDF 2 является последней версией UMDF и заменяет UMDF 1. Все новые драйверы UMDF должны быть написаны с помощью UMDF 2. Новые функции не добавляются в UMDF 1, а поддержка UMDF 1 в более новых версиях Windows 10 ограничена. Универсальные драйверы 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

Указывает начальный 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 , должен задать для директивы INF UmdfDirectHardwareAccess значение AllowDirectHardwareAccess.

Если драйвер задает директиву INF UmdfRegisterAccessModeв значение RegisterAccessUsingUserModeMapping, вызов MapIoSpace также сопоставляет заданный диапазон физических адресов с базовым диапазоном адресов в пользовательском режиме, к которому драйвер впоследствии может получить доступ, вызвав Метод GetHardwareRegisterMappedAddress.

Дополнительные сведения о директивах INF, которые могут использоваться драйверами UMDF, см. в разделе Указание директив WDF в INF-файлах.

Тип PHYSICAL_ADDRESS определен в Wudfwdm.h следующим образом:

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

Примеры

В следующем примере кода драйвер UMDF использует функцию обратного вызова IPnpCallbackHardware2::OnPrepareHardware для проверки ресурсов регистра, сопоставленных в памяти, и сопоставления их с адресным пространством в режиме пользователя. Затем в примере реализуется метод WriteToDevice , который обращается к расположениям в памяти. Затем драйвер вызывает UnmapIoSpace из обратного вызова IPnpCallbackHardware2::OnReleaseHardware . 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