Metodo IWDFDevice3::MapIoSpace (wudfddi.h)

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo MapIoSpace esegue il mapping dell'intervallo di indirizzi fisico specificato allo spazio indirizzi del sistema e restituisce uno pseudo indirizzo di base.

Sintassi

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

Parametri

[in] PhysicalAddress

Specifica l'indirizzo fisico a 64 bit iniziale dell'intervallo di I/O di cui eseguire il mapping.

[in] NumberOfBytes

Specifica un valore maggiore di zero, che indica il numero di byte di cui eseguire il mapping.

[in] CacheType

Specifica un valore MEMORY_CACHING_TYPE , che indica l'attributo della cache da usare per eseguire il mapping dell'intervallo di indirizzi fisico. Il tipo di enumerazione MEMORY_CACHING_TYPE è definito in Wudfwdm.h.

[out] pPseudoBaseAddress

Indirizzo di una posizione che riceve un puntatore all'indirizzo di base pseudo.The address of a location that receives a pointer to the pseudo base address.

Valore restituito

Il metodo restituisce S_OK se l'operazione ha esito positivo. In caso contrario, questo metodo restituisce uno dei codici di errore definiti in Winerror.h.

Commenti

Un driver deve chiamare questo metodo durante l'avvio del dispositivo se riceve risorse convertite di tipo CmResourceTypeMemory in una struttura CM_PARTIAL_RESOURCE_DESCRIPTOR . MapIoSpace esegue il mapping dell'indirizzo fisico restituito nell'elenco di risorse a un indirizzo gestito dal framework denominato pseudo indirizzo di base.

Il driver può quindi usare lo pseudo indirizzo di base per accedere ai registri dei dispositivi con funzioni READ_REGISTER_Xxx e WRITE_REGISTER_Xxx . Per un esempio, vedere Lettura e scrittura nei registri dei dispositivi nei driver UMDF 1.x.

Un driver che chiama MapIoSpace deve impostare la direttiva INF UmdfDirectHardwareAccess su AllowDirectHardwareAccess.

Se il driver imposta la direttiva UmdfRegisterAccessMode INF su RegisterAccessUsingUserModeMapping, chiamando MapIoSpace viene mappato anche l'intervallo di indirizzi fisici specificato a un intervallo di indirizzi di base in modalità utente a cui il driver può successivamente accedere chiamando GetHardwareRegisterMappedAddress.

Per altre informazioni sulle direttive INF che i driver UMDF possono usare, vedere Specifica delle direttive WDF nei file INF.

Il tipo PHYSICAL_ADDRESS è definito in Wudfwdm.h, come indicato di seguito:

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

Esempio

Nell'esempio di codice seguente, un driver UMDF usa la funzione di callback IPnpCallbackHardware2::OnPrepareHardware per esaminare le risorse di registro mappate alla memoria ed eseguirne il mapping nello spazio indirizzi in modalità utente. L'esempio implementa quindi un metodo WriteToDevice che accede ai percorsi di memoria. Il driver chiama quindi UnmapIoSpace dal callback IPnpCallbackHardware2::OnReleaseHardware . Il file INF del driver deve abilitare la funzionalità di accesso hardware UMDF impostando la direttiva UmdfDirectHardwareAccess su 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;
}

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.11
Intestazione	wudfddi.h
DLL	WUDFx.dll

Vedi anche

IWDFDevice3