IWDFDevice3 ::MapIoSpace, méthode (wudfddi.h)

Article
02/07/2025

[Avertissement : UMDF 2 est la dernière version de UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide de UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et il existe une prise en charge limitée de UMDF 1 sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Bien démarrer avec UMDF.]

La méthode MapIoSpace mappe la plage d’adresses physiques donnée à l’espace d’adressage système et retourne une pseudo-adresse de base.

Syntaxe

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

Paramètres

[in] PhysicalAddress

Spécifie l’adresse physique de début 64 bits de la plage d’E/S à mapper.

[in] NumberOfBytes

Spécifie une valeur supérieure à zéro, indiquant le nombre d’octets à mapper.

[in] CacheType

Spécifie une valeur MEMORY_CACHING_TYPE, qui indique l’attribut de cache à utiliser pour mapper la plage d’adresses physique. Le type d’énumération MEMORY_CACHING_TYPE est défini dans Wudfwdm.h.

[out] pPseudoBaseAddress

Adresse d’un emplacement qui reçoit un pointeur vers l’adresse pseudo-base.

Valeur de retour

La méthode retourne S_OK si l’opération réussit. Sinon, cette méthode retourne l’un des codes d’erreur définis dans Winerror.h.

Remarques

Un pilote doit appeler cette méthode lors du démarrage de l’appareil s’il reçoit des ressources traduites de type CmResourceTypeMemory dans une structure CM_PARTIAL_RESOURCE_DESCRIPTOR. MapIoSpace mappe l’adresse physique retournée dans la liste des ressources à une adresse gérée par l’infrastructure appelée pseudo-adresse de base.

Le pilote peut ensuite utiliser l’adresse pseudo de base pour accéder aux registres d’appareils avec READ_REGISTER_fonctions xxx et WRITE_REGISTER_xxx. Pour obtenir un exemple, consultez lecture et écriture dans les registres d’appareils dans les pilotes UMDF 1.x.

Un pilote qui appelle mapIoSpace doit définir la directive INF UmdfDirectHardwareAccess sur AllowDirectHardwareAccess.

Si le pilote définit la directive INF UmdfRegisterAccessMode sur RegisterAccessUsingUserModeMapping, l’appel MapIoSpace mappe également la plage d’adresses physique donnée à une plage d’adresses de base en mode utilisateur que le pilote peut accéder par la suite en appelant GetHardwareRegisterMappedAddress.

Pour plus d’informations sur les directives INF que les pilotes UMDF peuvent utiliser, consultez Spécification de directives WDF dans les fichiers INF.

Le type PHYSICAL_ADDRESS est défini dans Wudfwdm.h, comme suit :

typedef LARGE_INTEGER PHYSICAL_ADDRESS;

Exemples

Dans l’exemple de code suivant, un pilote UMDF utilise ses IPnpCallbackHardware2 ::OnPrepareHardware fonction de rappel pour examiner ses ressources d’inscription mappées en mémoire et les mapper dans l’espace d’adressage en mode utilisateur. L’exemple implémente ensuite une méthode WriteToDevice qui accède aux emplacements de mémoire. Le pilote appelle ensuite unmapIoSpace à partir de son rappel IPnpCallbackHardware2 ::OnReleaseHardware rappel. Le fichier INF du pilote doit activer la fonctionnalité d’accès matériel UMDF en définissant la directive UmdfDirectHardwareAccess sur 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;
}

Exigences

Exigence	Valeur
fin du support	Indisponible dans UMDF 2.0 et versions ultérieures.
plateforme cible	Bureau
version minimale de UMDF	1.11
d’en-tête	wudfddi.h
DLL	WUDFx.dll

Voir aussi

IWDFDevice3

Partager via