GPIO_CLIENT_PREPARE_CONTROLLER Rückruffunktion (gpioclx.h)
Die CLIENT_PrepareController Ereignisrückruffunktion führt alle Vorgänge aus, die erforderlich sind, um den allgemeinen I/O-Controller (GPIO) 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 Framework-Geräteobjekt, das den GPIO-Controller darstellt.
[in] Context
Ein Zeiger auf den Gerätekontext des GPIO-Controllertreibers.
[in] ResourcesRaw
Ein WDFCMRESLIST-Handle zu einer Sammlung von Frameworkressourcenobjekten. Diese Sammlung identifiziert die rohen (busrelativen) Hardwareressourcen, die der Plug and Play (PnP)-Manager dem GPIO-Controllergerät zugewiesen hat.
[in] ResourcesTranslated
Ein WDFCMRESLIST-Handle zu einer Sammlung 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.
Bemerkungen
Diese Rückruffunktion wird vom GPIO-Controllertreiber implementiert. Die GPIO-Framework-Erweiterung (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 ResourcesRaw und ResourcesTranslated Parameter werden in Listen roher und übersetzter Ressourcen behandelt. Diese Listen beschreiben Hardwareressourcen, die der PnP-Manager dem GPIO-Controllergerät zugewiesen hat, das vom parameter Device angegeben wird. Weitere Informationen finden Sie unter Raw and Translated Resources.
Während des CLIENT_PrepareController Rückrufs kann der GPIO-Controllertreiber die Hardwareressourcen abrufen, die er aus der liste ResourcesRaw oder ResourcesTranslated benötigt. Wenn das GPIO-Controllergerät speichergebunden ist, sollte der Treiber den busrelativen Speicheradressenbereich oder die Bereiche zuordnen, die den Hardwareregistern des Geräts zugeordnet sind, den virtuellen Systemadressen. Weitere Informationen finden Sie unter Zuordnung Bus-Relative Adressen zu virtuellen Adressen.
Wenn der GPIO-Controller nicht im Arbeitsspeicher 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 (und später getrennt von) jeder Interruptressource her, die der PnP-Manager dem GPIO-Controller zuweist. Wenn GpioClx eine solche Interruptressource empfängt, wird diese Unterbrechungsressource nicht aus den Ressourcenlisten entfernt, die sie an die CLIENT_PrepareController Rückruffunktion übergibt. Der GPIO-Controllertreiber sollte jedoch nicht versuchen, eine Verbindung mit einer Unterbrechungsressource herzustellen (oder später zu trennen), die in diesen Listen gefunden wird.
Die CLIENT_ReleaseController Ereignisrückruffunktion führt Vorgänge aus, die benötigt werden, 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.
Rufen Sie die GPIO_CLX_RegisterClient Methode auf, um die CLIENT_PrepareController Rückruffunktion des Treibers zu registrieren. 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 bei IRQL = PASSIVE_LEVEL aufgerufen wird, sollten Sie diese Funktion nicht seitenfähig machen. Der CLIENT_PrepareController Rückruf befindet sich im kritischen Timing-Pfad zum Wiederherstellen der Energie auf den Geräten auf der Hardwareplattform und aus Leistungsgründen sollte es nicht durch Seitenfehler verzögert werden.
Beispiele
Um eine CLIENT_PrepareController Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.
Um beispielsweise eine CLIENT_PrepareController Rückruffunktion zu definieren, die MyEvtGpioPrepareControllerbenannt ist, verwenden Sie den funktionstyp GPIO_CLIENT_PREPARE_CONTROLLER, wie in diesem Codebeispiel gezeigt:
GPIO_CLIENT_PREPARE_CONTROLLER MyEvtGpioPrepareController;
Implementieren Sie dann die Rückruffunktion wie folgt:
_Use_decl_annotations_
NTSTATUS
MyEvtGpioPrepareController(
WDFDEVICE Device,
PVOID Context,
WDFCMRESLIST ResourcesRaw,
WDFCMRESLIST ResourcesTranslated
)
{ ... }
Der GPIO_CLIENT_PREPARE_CONTROLLER Funktionstyp wird in der Headerdatei "Gpioclx.h" definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp GPIO_CLIENT_PREPARE_CONTROLLER in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Wird ab Windows 8 unterstützt. |
| Zielplattform- | Desktop |
| Header- | gpioclx.h |
| IRQL- | Wird bei PASSIVE_LEVEL aufgerufen. |