Método IWDFDevice3::MapIoSpace (wudfddi.h)

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método MapIoSpace mapeia o intervalo de endereços físico fornecido para o espaço de endereço do sistema e retorna um endereço pseudo-base.

Sintaxe

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

Parâmetros

[in] PhysicalAddress

Especifica o endereço físico inicial de 64 bits do intervalo de E/S a ser mapeado.

[in] NumberOfBytes

Especifica um valor maior que zero, indicando o número de bytes a serem mapeados.

[in] CacheType

Especifica um valor MEMORY_CACHING_TYPE , que indica o atributo de cache a ser usado para mapear o intervalo de endereços físicos. O tipo de enumeração MEMORY_CACHING_TYPE é definido em Wudfwdm.h.

[out] pPseudoBaseAddress

O endereço de um local que recebe um ponteiro para o endereço pseudo-base.

Retornar valor

O método retornará S_OK se a operação for bem-sucedida. Caso contrário, esse método retornará um dos códigos de erro definidos em Winerror.h.

Comentários

Um driver deve chamar esse método durante a inicialização do dispositivo se receber recursos traduzidos do tipo CmResourceTypeMemory em uma estrutura CM_PARTIAL_RESOURCE_DESCRIPTOR . MapIoSpace mapeia o endereço físico retornado na lista de recursos para um endereço gerenciado por estrutura conhecido como o endereço pseudo-base.

Em seguida, o driver pode usar o endereço pseudo-base para acessar registros de dispositivo com funções READ_REGISTER_Xxx e WRITE_REGISTER_Xxx . Para obter um exemplo, consulte Leitura e gravação em registros de dispositivo em drivers UMDF 1.x.

Um driver que chama MapIoSpace deve definir a diretiva INF UmdfDirectHardwareAccess como AllowDirectHardwareAccess.

Se o driver definir a diretiva INF UmdfRegisterAccessMode como RegisterAccessUsingUserModeMapping, chamar MapIoSpace também mapeará o intervalo de endereços físicos fornecido para um intervalo de endereços base no modo de usuário que o driver poderá acessar posteriormente chamando GetHardwareRegisterMappedAddress.

Para obter mais informações sobre diretivas INF que os drivers UMDF podem usar, consulte Especificando diretivas WDF em arquivos INF.

O tipo PHYSICAL_ADDRESS é definido em Wudfwdm.h, da seguinte maneira:

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

Exemplos

No exemplo de código a seguir, um driver UMDF usa sua função de retorno de chamada IPnpCallbackHardware2::OnPrepareHardware para examinar seus recursos de registro mapeados em memória e mapeá-los para o espaço de endereço no modo de usuário. Em seguida, o exemplo implementa um método WriteToDevice que acessa os locais de memória. Em seguida, o driver chama UnmapIoSpace de seu retorno de chamada IPnpCallbackHardware2::OnReleaseHardware . O arquivo INF do driver deve habilitar o recurso de acesso de hardware UMDF definindo a diretiva UmdfDirectHardwareAccess como 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;
}

Requisitos

Confira também

IWDFDevice3