IWDFDevice3::MapIoSpace メソッド (wudfddi.h)

  • [アーティクル]

[警告: UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、新しいバージョンのWindows 10では UMDF 1 のサポートが制限されています。 ユニバーサル 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

マップする I/O 範囲の開始 64 ビット物理アドレスを指定します。

[in] NumberOfBytes

マップするバイト数を示す、0 より大きい値を指定します。

[in] CacheType

物理アドレス範囲のマップに使用するキャッシュ属性を示すMEMORY_CACHING_TYPE値を指定します。 MEMORY_CACHING_TYPE列挙型は Wudfwdm.h で定義されています。

[out] pPseudoBaseAddress

擬似ベース アドレスへのポインターを受け取る場所のアドレス。

戻り値

メソッドは、操作が成功した場合S_OKを返します。 それ以外の場合、このメソッドは Winerror.h で定義されているエラー コードのいずれかを返します。

注釈

ドライバーは、CM_PARTIAL_RESOURCE_DESCRIPTOR構造体でCmResourceTypeMemory 型の翻訳されたリソースを受け取る場合、デバイスの起動時にこのメソッドを呼び出す必要があります。 MapIoSpace は 、リソース 一覧で返された物理アドレスを、擬似ベース アドレスと呼ばれるフレームワークで管理されるアドレスにマップします。

その後、ドライバーは擬似ベース アドレスを使用して、READ_REGISTER_Xxx 関数と WRITE_REGISTER_Xxx 関数を使用してデバイス レジスタにアクセスできます。 例については、「 UMDF 1.x ドライバーでのデバイス レジスタの読み取りと書き込み」を参照してください。

MapIoSpace を呼び出すドライバーは、UmdfDirectHardwareAccess INF ディレクティブを AllowDirectHardwareAccess に設定する必要があります。

ドライバーが UmdfRegisterAccessMode INF ディレクティブを RegisterAccessUsingUserModeMapping に設定した場合、 MapIoSpace を呼び出すと、指定された物理アドレス範囲も、 GetHardwareRegisterMappedAddress を呼び出すことによってドライバーが後でアクセスできるユーザー モードのベース アドレス範囲にマップされます。

UMDF ドライバーで使用できる INF ディレクティブの詳細については、「 INF ファイルでの WDF ディレクティブの指定」を参照してください。

PHYSICAL_ADDRESS型は、次のように Wudfwdm.h で定義されます。

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

例

次のコード例では、UMDF ドライバーは IPnpCallbackHardware2::OnPrepareHardware コールバック関数を使用して、メモリ マップされたレジスタ リソースを調べ、ユーザー モードのアドレス空間にマップします。 次に、メモリの場所にアクセスする WriteToDevice メソッドを実装します。 その後、ドライバーは IPnpCallbackHardware2::OnReleaseHardware コールバックから UnmapIoSpace を呼び出します。 ドライバーの INF ファイルは、 UmdfDirectHardwareAccess ディレクティブを AllowDirectHardwareAccess に設定することで、UMDF ハードウェア アクセス機能を有効にする必要があります。


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
Header wudfddi.h
[DLL] WUDFx.dll

こちらもご覧ください

IWDFDevice3