IWDFDevice3::MapIoSpace-Methode (wudfddi.h)

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 für neuere Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die MapIoSpace-Methode ordnet den angegebenen physischen Adressbereich dem Systemadressraum zu und gibt eine Pseudobasisadresse zurück.

Syntax

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

Parameter

[in] PhysicalAddress

Gibt die physische Startadresse von 64 Bit des E/A-Bereichs an, der zugeordnet werden soll.

[in] NumberOfBytes

Gibt einen Wert größer als 0 an, der die Anzahl der bytes angibt, die zugeordnet werden sollen.

[in] CacheType

Gibt einen MEMORY_CACHING_TYPE Wert an, der das Cache-Attribut angibt, das zum Zuordnen des physischen Adressbereichs verwendet werden soll. Der MEMORY_CACHING_TYPE Enumerationstyp ist in Wudfwdm.h definiert.

[out] pPseudoBaseAddress

Die Adresse eines Speicherorts, der einen Zeiger auf die Pseudobasisadresse empfängt.

Rückgabewert

Die Methode gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode einen der Fehlercodes zurück, die in Winerror.h definiert sind.

Hinweise

Ein Treiber muss diese Methode während des Gerätestarts aufrufen, wenn er übersetzte Ressourcen des Typs CmResourceTypeMemory in einer CM_PARTIAL_RESOURCE_DESCRIPTOR Struktur empfängt. MapIoSpace ordnet die in der Ressourcenliste zurückgegebene physische Adresse einer vom Framework verwalteten Adresse zu, die als Pseudobasisadresse bezeichnet wird.

Der Treiber kann dann die Pseudobasisadresse verwenden, um auf Geräteregister mit READ_REGISTER_Xxx - und WRITE_REGISTER_Xxx-Funktionen zuzugreifen. Ein Beispiel finden Sie unter Lesen und Schreiben in Geräteregister in UMDF 1.x-Treibern.

Ein Treiber, der MapIoSpace aufruft, muss die InF-Anweisung UmdfDirectHardwareAccess auf AllowDirectHardwareAccess festlegen.

Wenn der Treiber die Inf-Anweisung UmdfRegisterAccessAccessMode aufRegisterAccessUsingUserModeMapping festlegt, ordnet der Aufruf von MapIoSpace auch den angegebenen physischen Adressbereich einem Basisadressbereich im Benutzermodus zu, auf den der Treiber anschließend durch Aufrufen von GetHardwareRegisterMappedAddress zugreifen kann.

Weitere Informationen zu INF-Anweisungen, die UMDF-Treiber verwenden können, finden Sie unter Angeben von WDF-Direktiven in INF-Dateien.

Der PHYSICAL_ADDRESS-Typ wird in Wudfwdm.h wie folgt definiert:

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

Beispiele

Im folgenden Codebeispiel verwendet ein UMDF-Treiber seine IPnpCallbackHardware2::OnPrepareHardware-Rückruffunktion , um die speicherseitig zugeordneten Registerressourcen zu untersuchen und sie dem Adressraum im Benutzermodus zuzuordnen. Im Beispiel wird dann eine WriteToDevice-Methode implementiert, die auf die Speicherspeicherorte zugreift. Der Treiber ruft dann UnmapIoSpace über seinen IPnpCallbackHardware2::OnReleaseHardware-Rückruf auf. Die INF-Datei des Treibers muss das UMDF-Hardwarezugriffsfeature aktivieren, indem die UmdfDirectHardwareAccess-Direktive auf AllowDirectHardwareAccess festgelegt wird.

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;
}

Anforderungen

Weitere Informationen

IWDFDevice3