Metode IWDFDevice3::MapIoSpace (wudfddi.h)

Artikel
02/27/2024

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode MapIoSpace memetakan rentang alamat fisik yang diberikan ke ruang alamat sistem dan mengembalikan alamat dasar semu.

Sintaks

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

Parameter

[in] PhysicalAddress

Menentukan alamat fisik 64-bit awal rentang I/O yang akan dipetakan.

[in] NumberOfBytes

Menentukan nilai yang lebih besar dari nol, menunjukkan jumlah byte yang akan dipetakan.

[in] CacheType

Menentukan nilai MEMORY_CACHING_TYPE , yang menunjukkan atribut cache yang akan digunakan untuk memetakan rentang alamat fisik. Jenis enumerasi MEMORY_CACHING_TYPE didefinisikan dalam Wudfwdm.h.

[out] pPseudoBaseAddress

Alamat lokasi yang menerima penunjuk ke alamat dasar pseudo.

Nilai kembali

Metode mengembalikan S_OK jika operasi berhasil. Jika tidak, metode ini mengembalikan salah satu kode kesalahan yang ditentukan dalam Winerror.h.

Keterangan

Driver harus memanggil metode ini selama start-up perangkat jika menerima sumber daya terjemahan jenis CmResourceTypeMemory dalam struktur CM_PARTIAL_RESOURCE_DESCRIPTOR . MapIoSpace memetakan alamat fisik yang dikembalikan dalam daftar sumber daya ke alamat yang dikelola kerangka kerja yang disebut sebagai alamat dasar pseudo.

Driver kemudian dapat menggunakan alamat dasar pseudo untuk mengakses register perangkat dengan fungsi READ_REGISTER_Xxx dan WRITE_REGISTER_Xxx . Misalnya, lihat Membaca dan Menulis ke Daftar Perangkat di Driver UMDF 1.x.

Driver yang memanggil MapIoSpace harus mengatur arahan UmdfDirectHardwareAccess INF ke AllowDirectHardwareAccess.

Jika driver mengatur arahan UmdfRegisterAccessMode INF ke RegisterAccessUsingUserModeMapping, memanggil MapIoSpace juga memetakan rentang alamat fisik yang diberikan ke rentang alamat dasar mode pengguna yang kemudian dapat diakses driver dengan memanggil GetHardwareRegisterMappedAddress.

Untuk informasi selengkapnya tentang arahan INF yang dapat digunakan driver UMDF, lihat Menentukan Arahan WDF dalam File INF.

Jenis PHYSICAL_ADDRESS didefinisikan dalam Wudfwdm.h, sebagai berikut:

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

Contoh

Dalam contoh kode berikut, driver UMDF menggunakan fungsi panggilan balik IPnpCallbackHardware2::OnPrepareHardware untuk memeriksa sumber daya register yang dipetakan memorinya dan memetakannya ke ruang alamat mode pengguna. Contohnya kemudian mengimplementasikan metode WriteToDevice yang mengakses lokasi memori. Driver kemudian memanggil UnmapIoSpace dari panggilan balik IPnpCallbackHardware2::OnReleaseHardware . File INF driver harus mengaktifkan fitur akses perangkat keras UMDF dengan mengatur arahan UmdfDirectHardwareAccess ke 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;
}

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1.11
Header	wudfddi.h
DLL	WUDFx.dll

Lihat juga

IWDFDevice3

Bagikan melalui