GPIO_CLIENT_PREPARE_CONTROLLER Rückruffunktion (gpioclx.h)
Die CLIENT_PrepareController Ereignisrückruffunktion führt alle Vorgänge aus, die erforderlich sind, um den GPIO-Controller (General Purpose E/O) für den Zugriff durch den GPIO-Controllertreiber bereit zu machen.
Syntax
GPIO_CLIENT_PREPARE_CONTROLLER GpioClientPrepareController;
NTSTATUS GpioClientPrepareController(
[in] WDFDEVICE Device,
[in] PVOID Context,
[in] WDFCMRESLIST ResourcesRaw,
[in] WDFCMRESLIST ResourcesTranslated
)
{...}
Parameter
[in] Device
Ein WDFDEVICE-Handle für das Frameworkgerätobjekt, das den GPIO-Controller darstellt.
[in] Context
Ein Zeiger auf den Gerätekontext des GPIO-Controllertreibers.
[in] ResourcesRaw
Ein WDFCMRESLIST-Handle für eine Auflistung von Frameworkressourcenobjekten. Diese Sammlung identifiziert die unformatierten (busrelativen) Hardwareressourcen, die der PnP-Manager (Plug & Play) dem GPIO-Controllergerät zugewiesen hat.
[in] ResourcesTranslated
Ein WDFCMRESLIST-Handle für eine Auflistung von Frameworkressourcenobjekten. Diese Sammlung identifiziert die übersetzten (system-physischen) Hardwareressourcen, die der PnP-Manager dem GPIO-Controllergerät zugewiesen hat.
Rückgabewert
Die CLIENT_PrepareController-Funktion gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehlercode zurückgegeben.
Hinweise
Diese Rückruffunktion wird vom GPIO-Controllertreiber implementiert. Die GPIO-Frameworkerweiterung (GpioClx) ruft diese Funktion auf, um die Hardwareressourcen zu initialisieren, die der GPIO-Controllertreiber benötigt, damit er auf das GPIO-Controllergerät zugreifen kann.
Die Parameter ResourcesRaw und ResourcesTranslated sind Handles für Listen mit rohen und übersetzten Ressourcen. In diesen Listen werden Hardwareressourcen beschrieben, die der PnP-Manager dem GPIO-Controllergerät zugewiesen hat, das durch den Device-Parameter angegeben wird. Weitere Informationen finden Sie unter Unformatierte und übersetzte Ressourcen.
Während des CLIENT_PrepareController Rückrufs kann der GPIO-Controllertreiber die benötigten Hardwareressourcen aus der Liste ResourcesRaw oder ResourcesTranslated abrufen. Wenn das GPIO-Controllergerät speicherseitig zugeordnet ist, sollte der Treiber den busrelativen Speicheradressbereich bzw. die Bereiche, die den Hardwareregistern des Geräts zugewiesen sind, virtuellen Systemadressen zuordnen. Weitere Informationen finden Sie unter Zuordnen Bus-Relative Adressen zu virtuellen Adressen.
Wenn der GPIO-Controller nicht arbeitsspeicherseitig zugeordnet ist, enthalten die Hardwareressourcen des Treibers eine Verbindungs-ID anstelle eines Speicherbereichs. Der Treiber verwendet diese ID, um eine logische Verbindung mit dem GPIO-Controller zu öffnen, und sendet E/A-Anforderungen über diese Verbindung, um auf die Register des Controllers zuzugreifen.
GpioClx stellt eine Verbindung mit einer beliebigen Interruptressource her (und wird später getrennt), die der PnP-Manager dem GPIO-Controller zuweist. Wenn GpioClx eine solche Interruptressource empfängt, entfernt es diese Interruptressource nicht aus den Ressourcenlisten, die an die CLIENT_PrepareController Rückruffunktion übergeben werden. Der GPIO-Controllertreiber sollte jedoch nicht versuchen, eine Verbindung mit einer Interruptressource herzustellen (oder später eine Verbindung von) herzustellen, die er in diesen Listen findet.
Die CLIENT_ReleaseController Ereignisrückruffunktion führt Vorgänge aus, die erforderlich sind, wenn auf das GPIO-Controllergerät nicht mehr zugegriffen werden kann. Während dieses Rückrufs sollte der GPIO-Controllertreiber alle Hardwareressourcen freigeben, die er während des vorherigen CLIENT_PrepareController Rückrufs erworben hat.
Um die CLIENT_PrepareController Rückruffunktion Ihres Treibers zu registrieren, rufen Sie die GPIO_CLX_RegisterClient-Methode auf. Diese Methode akzeptiert als Eingabeparameter einen Zeiger auf eine GPIO_CLIENT_REGISTRATION_PACKET-Struktur , die einen CLIENT_PrepareController Funktionszeiger enthält.
Obwohl die CLIENT_PrepareController Rückruffunktion unter IRQL = PASSIVE_LEVEL aufgerufen wird, sollten Sie diese Funktion nicht auslagerungsfähig machen. Der CLIENT_PrepareController Rückrufs befindet sich im kritischen Zeitverlauf für die Wiederherstellung der Stromversorgung der Geräte auf der Hardwareplattform und sollte aus Leistungsgründen nicht durch Seitenfehler verzögert werden.
Beispiele
Um eine CLIENT_PrepareController Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion angibt. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.
Um beispielsweise eine CLIENT_PrepareController Rückruffunktion namens MyEvtGpioPrepareControllerzu definieren, verwenden Sie den GPIO_CLIENT_PREPARE_CONTROLLER Funktionstyp, wie in diesem Codebeispiel gezeigt:
GPIO_CLIENT_PREPARE_CONTROLLER MyEvtGpioPrepareController;
Implementieren Sie dann Ihre Rückruffunktion wie folgt:
_Use_decl_annotations_
NTSTATUS
MyEvtGpioPrepareController(
WDFDEVICE Device,
PVOID Context,
WDFCMRESLIST ResourcesRaw,
WDFCMRESLIST ResourcesTranslated
)
{ ... }
Der GPIO_CLIENT_PREPARE_CONTROLLER Funktionstyp ist in der Headerdatei Gpioclx.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den GPIO_CLIENT_PREPARE_CONTROLLER Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für KMDF-Treiber. Weitere Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Wird ab Windows 8 unterstützt. |
| Zielplattform | Desktop |
| Kopfzeile | gpioclx.h |
| IRQL | Wird bei PASSIVE_LEVEL aufgerufen. |