Méthode IWDFDevice3 ::MapIoSpace (wudfddi.h)

Article
02/27/2024

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

La méthode MapIoSpace mappe la plage d’adresses physique 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 64 bits de départ 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 physiques. 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 la pseudo adresse de base.

Valeur retournée

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 au 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 de ressources à une adresse gérée par l’infrastructure appelée pseudo-adresse de base.

Le pilote peut ensuite utiliser la pseudo adresse de base pour accéder aux registres d’appareils avec les fonctions READ_REGISTER_Xxx et WRITE_REGISTER_Xxx . Pour obtenir un exemple, consultez Lecture et écriture dans les registres de périphériques 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 de MapIoSpace mappe également la plage d’adresses physiques donnée à une plage d’adresses de base en mode utilisateur à laquelle le pilote peut ensuite accéder 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 sa fonction de rappel IPnpCallbackHardware2 ::OnPrepareHardware pour examiner ses ressources de registre 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 . 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;
}

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1.11
En-tête	wudfddi.h
DLL	WUDFx.dll

Voir aussi

IWDFDevice3

Partager via