Basis-belpatroon voor DMA-routines van versie 3

Als u een DMA-overdracht wilt uitvoeren die gebruikmaakt van de routines in versie 3 van de DMA-bewerkingsinterface, moet uw stuurprogramma de stappen volgen die in de volgende lijst worden beschreven. Deze stappen zijn gebruikelijk voor zowel onderliggende apparaten als bushoofdapparaten. Versie 3 van deze interface is beschikbaar vanaf Windows 8. Zie DMA_OPERATIONS voor meer informatie over de routines in deze interface.

Stap 1: een DMA-adapterobject verkrijgen

Ter voorbereiding op een DMA-overdracht roept het stuurprogramma de IoGetDmaAdapter-routine aan om een DMA-adapterobject te verkrijgen. Een DMA-adapterobject is een softwareobject dat een bus-masterapparaat of een aanvraaglijn op een systeem-DMA-controller vertegenwoordigt. Dit object bevat de DMA-bewerkingsinterface voor de bus die wordt gebruikt voor het overdragen van gegevens naar of van het apparaat. Daarnaast synchroniseert dit object de toegang van het stuurprogramma tot de gedeelde resources die nodig zijn om de overdracht uit te voeren. Zie Inleiding tot adapterobjecten voor meer informatie.

Stap 2: een beschrijving verkrijgen van de vereiste DMA-resources

Het stuurprogramma roept de GetDmaTransferInfo-routine aan om een beschrijving te krijgen van de DMA-resources die nodig zijn om de overdracht uit te voeren.

De invoerparameters voor deze aanroep beschrijven de geheugenbuffer die moet worden gebruikt voor de overdracht en de richting (lezen of schrijven) van de overdracht.

De resourcevereisten die uit deze aanroep zijn verkregen, omvatten het aantal kaartregisters en de grootte van de spreidings-/verzamellijst die nodig is om de gegevensbuffer voor de overdracht te beschrijven. In de volgende aanroep van de AllocateAdapterChannelEx-routine (zie stap 3) geeft het stuurprogramma het aantal mapregisters als invoerparameter.

Stap 3: De vereiste DMA-resources aanvragen

Het stuurprogramma roept de AssignAdapterChannelEx-routine aan om resources toe te wijzen die moeten worden toegewezen aan het DMA-adapterobject. Deze resources omvatten een DMA-kanaal en kaartregisters.

Een AllocateAdapterChannelEx-aanroep kan asynchroon of synchroon zijn.

Als de DMA_SYNCHRONOUS_CALLBACK vlag niet is ingesteld, is de aanroep asynchroon. In dit geval verwijst de parameter ExecutionRoutine naar een door de aanroeper geleverde uitvoeringsroutine die wordt aangeroepen wanneer de aangevraagde resources beschikbaar zijn. Als dit lukt, retourneert een asynchrone AllocateAdapterChannelEx-aanroep STATUS_SUCCESS zonder te wachten tot de uitvoeringsroutine wordt uitgevoerd.

Als de flag DMA_SYNCHRONOUS_CALLBACK is ingesteld, is de aanroep naar AllocateAdapterChannelEx synchroon. In dit geval is de parameter ExecutionRoutine in de aanroep optioneel en gedraagt AllocateAdapterChannelEx zich als volgt:

• Als ExecutionRoutine niet null is en de DMA-resources onmiddellijk kunnen worden toegewezen, roept AllocateAdapterChannelEx de uitvoeringsroutine aan in de context van de aanroepende thread. Nadat de uitvoeringsroutine is uitgevoerd, retourneert AllocateAdapterChannelEx STATUS_SUCCESS. Als de resources niet onmiddellijk beschikbaar zijn, mislukt AllocateAdapterChannelEx en retourneert de foutcode STATUS_INSUFFICIENT_RESOURCES.

• Als ExecutionRoutine NULL is en AllocateAdapterChannelEx de DMA-resources onmiddellijk kan toewijzen, retourneert AllocateAdapterChannelEx STATUS_SUCCESS. Als alle resources niet onmiddellijk beschikbaar zijn, mislukt de aanroep met foutcode STATUS_INSUFFICIENT_RESOURCES.

Voor synchrone aanroepen die STATUS_SUCCESS retourneren, schrijft AllocateAdapterChannelEx als de parameter MapRegisterBase niet NULL is, het basisadres van de toegewezen kaartregisters naar het adres waarnaar wordt verwezen door de parameter MapRegisterBase. Als ExecutionRoutine NULL is, moet MapRegisterBase niet-NULL zijn. Als ExecutionRoutine niet NULL is, is de parameter MapRegisterBase voor AllocateAdapterChannelEx optioneel en ontvangt de uitvoeringsroutine het basisadres van het toewijzingsregister als invoerparameter.

Voor asynchrone AllocateAdapterChannelEx-aanroepen moet ExecutionRoutine niet NULL zijn en ontvangt de uitvoeringsroutine het basisadres van het toewijzingsregister als invoerparameter.

In volgende aanroepen naar de MapTransferEx-routine (zie stap 5), levert het stuurprogramma het basisadres van het kaartregister als invoerparameter.

Als ExecutionRoutine niet NULL is, retourneert de uitvoeringsroutine een statuswaarde om de verwijdering van de toegewezen resources aan te geven. Voor systeem-DMA-overdrachten moet deze retourwaarde KeepObject zijn. Deze waarde informeert het besturingssysteem dat het adapterobject (en alle toegewezen resources) in gebruik is en niet mag worden vrijgemaakt. Als er geen uitvoeringsroutine wordt opgegeven, moet het stuurprogramma in plaats daarvan de FreeAdapterObject-routine aanroepen en KeepObject opgeven als de parameter AllocationOption .

Stap 4: Indien nodig annuleert u de resourceaanvraag die in behandeling is

Nadat een AllocateAdapterChannelEx-aanroep een DMA-adapter in de wachtrij zet om te wachten op DMA-resources, kan het stuurprogramma, indien nodig, de routine CancelAdapterChannel aanroepen om de in behandeling zijnde resourceaanvraag te annuleren.

Als CancelAdapterChannel TRUE retourneert, wordt de resourceaanvraag geannuleerd. Als er een uitvoeringsroutine is opgegeven in de call AllocateAdapterChannelEx , wordt deze routine niet uitgevoerd.

Als CancelAdapterChannel ONWAAR retourneert, kan de resourceaanvraag niet worden geannuleerd omdat deze al is verleend. Als er een uitvoeringsroutine is opgegeven in de call AllocateAdapterChannelEx , wordt deze routine aangeroepen.

Stap 5: De DMA-resources initialiseren en de DMA-overdracht starten

Het stuurprogramma roept MapTransferEx aan om de DMA-resources te initialiseren en de DMA-overdracht te starten. Deze aanroep kan zich voordoen in dezelfde stuurprogrammathread die AllocateAdapterChannelEx aanroept, of het kan optreden in de uitvoeringsroutine die het stuurprogramma levert aan AllocateAdapterChannelEx. Als er meer dan één MapTransferEx-aanroep nodig is om de volledige DMA-gegevensbuffer over te dragen, kan een latere MapTransferEx-aanroep optreden in de voltooiingsroutine voor de vorige MapTransferEx-aanroep .

MapTransferEx ondersteunt gekoppelde MCL's als invoerparameters. Elke MDL beschrijft een regio van de DMA-buffer die aaneengesloten is in het virtuele geheugen. Wanneer MapTransferEx de spreidings-/verzamellijst bouwt, worden overgangen van een virtueel aaneengesloten bufferregio automatisch afgehandeld zonder tussenkomst van het stuurprogramma. Zie De MapTransferEx-routine gebruiken voor meer informatie.

Voor een systeem-DMA-overdracht kan een aanwijzer naar een DMA-voltooiingsroutine worden doorgegeven aan MapTransferEx in de optionele parameter DmaCompletionRoutine . Deze routine wordt gepland om te worden uitgevoerd op verzendniveau als reactie op een onderbreking van de systeem-DMA-controller die aangeeft dat de DMA-overdracht is voltooid.

Als MapTransferEx de volledige aangevraagde overdrachtsgrootte niet kan toewijzen, wordt de uitvoerparameter *Length ingesteld op de lengte die is toegewezen en wordt STATUS_SUCCESS geretourneerd.

Stap 6: Voer zo nodig hardwarespecifieke bewerkingen uit

MapTransferEx retourneert STATUS_SUCCESS om aan te geven dat de DMA-overdracht is gestart. Op sommige platforms moet het stuurprogramma mogelijk extra actie ondernemen, buiten de MapTransferEx-aanroep , om de overdracht te starten, maar dit type vertraagde start is niet vereist voor alle platforms. Stuurprogramma's mogen niet afhankelijk zijn van dergelijke vertragingen voor het nemen van beslissingen over het gebruik en het vrijmaken van toegewezen bronnen.

De routines in de DMA-bewerkingsinterface behouden cacheherentie voor DMA-overdrachten op een manier die transparant is voor de stuurprogramma's die gebruikmaken van deze routines. Op platforms die geen cacheherentie in hardware afdwingen, zorgt MapTransferEx ervoor dat processorgegevenscaches worden leeggemaakt voordat gegevens worden overgedragen (geheugen-naar-apparaat). Voor leesoverdrachten (apparaat-naar-geheugen) worden de caches ongeldig gemaakt tijdens het aanroepen van de FlushAdapterBuffersEx-routine (zie stap 8) die volgt op elke MapTransferEx-aanroep .

Stap 7: Een melding ontvangen wanneer de DMA-overdracht is voltooid

Wanneer een DMA-overdracht is voltooid, wordt het stuurprogramma op een van de volgende twee manieren op de hoogte gesteld:

• Een interrupt naar het apparaatstuurprogramma, voor een busmaster-apparaat
• Uitvoering van de door het stuurprogramma geleverde voltooiingsroutine voor een ondergeschikt apparaat dat gebruikmaakt van een systeem-DMA-controller

Voor een systeem-DMA-overdracht kan een stuurprogramma een voltooiingsroutine aan MapTransferEx leveren als invoerparameter.

Stap 8: Alle gegevens leegmaken die in de cache blijven

Nadat de DMA-overdracht is voltooid, moet het stuurprogramma de FlushAdapterBuffersEx-routine aanroepen om alle gegevens die in de cache blijven, leeg te maken. Het stuurprogramma moet FlushAdapterBuffersEx aanroepen na elke MapTransferEx-aanroep .

Als een MapTransferEx-aanroep slechts een deel van de DMA-gegevensbuffer in kaart brengt, moet het stuurprogramma MapTransferEx opnieuw aanroepen om de resterende gegevens te mappen. Voor een complexe overdracht zijn mogelijk verschillende MapTransferEx-aanroepen vereist. Herhaal stap 5 tot en met 8 voor elke extra MapTransferEx-aanroep .

Stap 9: Het DMA-kanaal en de kaartregisters vrij maken

Nadat de volledige DMA-gegevensbuffer is toegewezen en de definitieve overdracht is voltooid, moet het stuurprogramma de FreeAdapterChannel-routine aanroepen om het DMA-kanaal en eventuele eerder toegewezen kaartregisters vrij te maken.

Stap 10: Het DMA-adapterobject vrijgeven

Nadat alle DMA-overdrachten zijn voltooid en alle eerder toegewezen kaartregisters zijn vrijgemaakt, roept het stuurprogramma de PutDmaAdapter-routine aan om het adapterobject vrij te geven.