Schulung
Modul
Troubleshoot device driver failures - Training
This module focuses on the role of device drivers and troubleshooting problems that pertain to them.
Flashlight-Unterstützung
Ab Dem Windows-Schwellenwert stellen wir eine neue WinRT Lamp-API bereit, die es ermöglicht, Kamerablitz zu programmieren, ohne eine Windows.Media.Capture.MediaCapture-Instanz erstellen zu müssen. Auf diese Weise kann ein Entwickler eine Taschenlampenanwendung (nur für Beleuchtungszwecke) schreiben, indem die geringste Menge an Ressourcen einschließlich Leistung gezeichnet wird, sodass ein Computergerät für die Akkulaufzeit und Leistung optimiert werden kann.
Um dies zu erreichen, muss ein IHV/OEM einen WDM-Treiber implementieren, der die folgenden Funktionen unterstützt:
Zulassen, dass das System alle Flashgeräte aufzählt.
Aktivieren/Deaktivieren der Taschenlampe auf Gerätebasis.
Passen Sie ggf. die Lichtintensität (ähnlich powerPercent) pro Gerät an.
Falls zutreffend, geben Sie die Lichtfarbe pro Gerät an.
In Bezug auf die Funktionalität überlappt die obige Liste deutlich mit der von MediaCapture (z. B . FlashControl und TorchControl). Darüber hinaus wird die gleiche Blitzhardware sowohl für Leuchte als auch für Blitz während der Aufnahme verwendet. Daher wird empfohlen, beide Arten von Vorgängen mit einem einzigen WDM-Treiber zu unterstützen, um Flash exklusiv zu steuern. Die folgende Abbildung veranschaulicht das Konzept:
Im obigen Beispiel gibt es nur eine Flash-Hardwareinstanz (siehe siehe) und wird von einem einzelnen KMDF-Flashtreiber verwaltet. Der Flash-Treiber macht zwei Geräteschnittstellen verfügbar, die jeweils für einen bestimmten Clienttyp (oder winRT-API) vorgesehen sind. Beispiel:
Die WinRT Media Capture API und der AVStream Minidriver kommunizieren immer mit dem Flash-Treiber über die GUID_DEVINTERFACE_CAMERA_FLASH-Schnittstelle, während
Die WinRT Lamp API kommuniziert immer über die GUID_DEVINTERFACE_LAMP Schnittstelle mit dem Flash-Treiber.
Da die GUID_DEVINTERFACE_CAMERA_FLASH-Schnittstelle von einem herstellerspezifischen AVStream-Minidriver verwendet wird, kann ein IHV/OEM seine Funktionalität nach Be willen definieren – es gibt keine Einschränkung durch Windows.
Microsoft wird die Schnittstelle jedoch GUID_DEVINTERFACE_LAMP standardisieren, da sie von der WinRT Lamp-API verwendet werden soll. Weitere Informationen zu GUID_DEVINTERFACE_LAMP finden Sie unter GUID der Geräteschnittstellenklasse
Ein Kamerablitz wird in der Regel als untergeordnetes Peripheriegerät für ein Aufnahmegerät betrachtet. Es soll nicht für Nichtkameraszenarien freigegeben werden, während die Aufnahme ausgeführt wird. Um die Anzahl der Blitzgeräte auf einem Chassis weiter zu erschweren, ist dies äußerst begrenzt, sodass in der Praxis kein Ersatzblitz nur für Flashlichtzwecke vorgesehen ist.
Aus Softwareperspektive stellt der obige Schritt eine Herausforderung auf, bei der eine Kameraanwendung und eine Blitzlichtanwendung gleichzeitig vorhanden und auf Blitz zugreifen können. Theoretisch kann ein Benutzer beispielsweise den LED-Zustand über eine Taschenlampenanwendung umschalten, während ein Kamera-Sucher ausgeführt wird.
Da die Kamera präzise Kontrolle über den Blitz benötigt, um den Fokus und die Aufnahme zu unterstützen, kann es schwierig sein, dass der Treiber Flashanforderungen von widersprüchlichen Interessen löst und gleichzeitig die Bildqualität gewährleistet. Um dieses Problem zu beheben, wird die folgende Richtlinie auf Systemebene als Vertrag erzwungen:
Wenn eine Aufnahmesitzung zuerst gestartet wird, kann eine Taschenlampenanwendung den Blitz erst bearbeiten, wenn die Aufnahme beendet wird.
Eine Flashlight-Anwendung kann weiterhin ein Handle für den Flashtreiber abrufen, aber jeder Vorgang, der den Flash-Zustand ändert, führt zu einem sofortigen Fehler.
Wenn die Aufnahme beendet wird, sodass der AVStream-Minidriver den Flash freigibt, muss der Flashtreiber eine PnP-Benachrichtigung bereitstellen (siehe GUID_LAMP_RESOURCES_AVAILABLE in asynchronen Benachrichtigungen), der angibt, dass die zugrunde liegende Hardware jetzt verfügbar ist. Nach Erhalt einer solchen Benachrichtigung darf eine Taschenlampenanwendung flash entsprechend programmieren.
Wenn eine Flashlight-Anwendung zuerst startet, ist eine Aufnahmesitzung frei, die Flash-Hardware ohne ausdrückliche Zustimmung zu entführern.
Durch "Entführer" meinen wir, dass ein IHV/OEM beliebiges Protokoll (möglicherweise über die GUID_DEVINTERFACE_CAMERA_FLASH Schnittstelle) implementieren kann, so dass der AVStream Minidriver Flash erwerben darf, als ob die Hardware überhaupt nicht verwendet wird.
Wenn ein Entführer auftritt, ist der Blitztreiber erforderlich, um eine andere PnP-Benachrichtigung zu veröffentlichen (siehe GUID_LAMP_RESOURCES_LOST in asynchronen Benachrichtigungen), der angibt, dass der Blitz unfreiwillig neu zugewiesen wurde, damit die Taschenlampenanwendung entsprechend handeln kann (durch Aktualisieren der UI z. B.)
Wenn die Kamera nicht beteiligt ist und zwei Taschenlampenanwendungen nacheinander ausgeführt werden, sollte der Treiber den ersten Client warten, der die GUID_DEVINTERFACE_LAMP Schnittstelle bereits erworben hat, und alle zusätzlichen Clients ablehnen, bis die erste die Schnittstelle schließlich veröffentlicht.
Mit anderen Worten, die GUID_DEVINTERFACE_LAMP Schnittstelle erlaubt jeweils nur einen Taschenlampenclient und den ersten Client, der die Schnittstelle erwirbt, verhindert, dass andere ausgeführt werden (Kamera/AVStream ausgeschlossen).
Ein IHV/OEM Flash-Treiber, der flashlight unabhängig von MediaCapture unterstützt, muss sich bei der GuiD der Geräteschnittstellenklasse GUID_DEVINTERFACE_LAMP registrieren.
| Attribut | Einstellung |
|---|---|
| Identifier | GUID_DEVINTERFACE_LAMP |
| Klassen-GUID | {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98} |
Die GUID der Geräteschnittstellenklasse von GUID_DEVINTERFACE_CAMERA_FLASH kann von IHVs/OEMs benutzerdefinierte definiert werden. Die GuiD der Geräteschnittstellenklasse von GUID_DEVINTERFACE_LAMP wird jedoch von Windows definiert.
Vertraglich ist ein Treiber, der die Geräteschnittstelle verfügbar macht, GUID_DEVINTERFACE_LAMP, erforderlich, um die folgenden Funktionen zu unterstützen (weitere Informationen finden Sie in den nachfolgenden Abschnitten):
IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR} – Ruft alle Modi (z. B. nur weiß im Vergleich zur Farbe) ab, die von der zugrunde liegenden Hardware unterstützt werden.
IOCTL_LAMP_{GET|SET}_MODE – ruft den aktuellen Modus ab oder legt den aktuellen Modus fest.
IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR} – Ruft die Lichtintensität ab oder legt sie fest
IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT – Ruft den Blitzzustand ab oder legt den Blitzzustand fest (z. B. EIN/AUS)
Wenn ein Gerät mehr als eine Blitzhardware unterschiedlicher Typen aufweist (z. B. eine weiße LED und ein Xenon-Flash), und diese Hardware werden von verschiedenen Flashtreibern gesteuert, muss jeder Treiber dieselbe GUID_DEVINTERFACE_LAMP Schnittstelle mit einer eindeutigen Instanz-ID verfügbar machen.
Da ein Computergerät null oder mehr Flash-Geräte auf verschiedenen Panels aufweisen kann, benötigt die WinRT-Lamp-API einen Mechanismus zum Aufzählen aller Flashhardware, sodass eine Anwendung eine bestimmte Instanz programmieren kann.
Um die Geräteenumeration zu unterstützen, ähnlich wie der Kameratreiber, muss der Blitztreiber eine ACPI-_PLD v2-Struktur jeder GUID_DEVINTERFACE_LAMP Schnittstelle als Schnittstelleneigenschaftendaten zuordnen.
Die IOCTL_LAMP_GET_CAPABILITIES_WHITE E/A-Anforderung fragt die Funktionen des Blitzes ab, wenn das Gerät so konfiguriert ist, dass weißes Licht ausgegeben wird.
C++
#define IOCTL_LAMP_BASE FILE_DEVICE_UNKNOWN
#define IOCTL_LAMP_GET_CAPABILITIES_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0000, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf einen Puffer vom Typ LAMP_CAPABILITIES_WHITE. Weitere Informationen finden Sie im Abschnitt Hinweise.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength ist die Länge des Puffers (in Bytes), der im Feld "Irp-AssociatedIrp.SystemBuffer>" übergeben wird.
Irp-AssociatedIrp.SystemBuffer> ist mit allen Funktionen gefüllt, die von der Flash-Hardware unterstützt werden.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest. Irp-IoStatus.Information> wird auf die Anzahl der Bytes festgelegt, die zum Halten des Puffers erforderlich sind.
Bei Bedarf ist ein Blitz erforderlich, dessen Treiber die GUID_DEVINTERFACE_LAMP Schnittstelle unterstützt, um weißes Licht zu unterstützen. Die Nutzlast dieser IOCTL wird wie folgt definiert:
C++
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;
Das Feld "IsLightIntensityAdjustable" gibt an, ob die Leuchtdichtestufe programmiert werden kann. Wenn dieses Feld "false" auswertet, bedeutet dies, dass das zugrunde liegende Gerät nur den Ein-/Aus-Schalter unterstützt und die Lichtintensität nicht angepasst werden kann.
Die IOCTL_LAMP_GET_CAPABILITIES_COLOR E/A-Anforderung fragt die Funktionen des Blitzes ab, wenn das Gerät so konfiguriert ist, dass Farblicht ausgegeben wird.
C++
#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf einen Puffer vom Typ LAMP_CAPABILITIES_COLOR. Weitere Informationen finden Sie im Abschnitt Hinweise.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength ist die Länge des Puffers (in Bytes), der im Feld "Irp-AssociatedIrp.SystemBuffer>" übergeben wird.
Irp-AssociatedIrp.SystemBuffer> ist mit allen Funktionen gefüllt, die von der Flash-Hardware unterstützt werden.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest. Irp-IoStatus.Information> wird auf die Anzahl der Bytes festgelegt, die zum Halten des Puffers erforderlich sind.
Die Nutzlast dieser IOCTL wird wie folgt definiert:
C++
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
BOOLEAN IsSupported;
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;
Das erste Feld , IsSupported, gibt an, ob der Blitz Farblicht ausgeben kann. Wenn die Hardware kein Farblicht unterstützt, sollte der Treiber dieses Feld auf "false" festlegen.
Das zweite Feld , IsLightIntensityAdjustable, gibt an, ob die Leuchtdichtestufe programmiert werden kann. Wenn der Blitz kein Farblicht unterstützt (z. B. "IsSupported wertet false" aus), sollte ein Client den Wert von IsLightIntensityAdjustable verwerfen.
Die IOCTL_LAMP_GET_MODE-E/A-Anforderung fragt den Modus ab, mit dem der Blitz derzeit konfiguriert ist.
C++
#define IOCTL_LAMP_GET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf einen Puffer vom Typ LAMP_MODE, der wie folgt definiert ist:
C++
typedef enum LAMP_MODE
{
LAMP_MODE_WHITE = 0,
LAMP_MODE_COLOR
} LAMP_MODE;
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength ist die Länge des Puffers (in Bytes), der im Feld "Irp-AssociatedIrp.SystemBuffer>" übergeben wird.
Irp-AssociatedIrp.SystemBuffer> wird mit einem LAMP_MODE Wert gefüllt.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest. Irp-IoStatus.Information> wird auf die Anzahl der Bytes festgelegt, die zum Halten eines DWORD-Werts erforderlich sind.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Die IOCTL_LAMP_SET_MODE E/A-Anforderung legt den Modus fest, in dem der Blitz ausgeführt wird.
C++
#define IOCTL_LAMP_SET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf einen Puffer vom Typ LAMP_MODE.
Keine.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Die IOCTL_LAMP_GET_INTENSITY_WHITE E/A-Anforderung fragt die Lichtintensität ab, wenn der Blitz so konfiguriert ist, dass weißes Licht ausgegeben wird.
C++
#define IOCTL_LAMP_GET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf eine LAMP_INTENSITY_WHITE Struktur. Weitere Informationen finden Sie im Abschnitt Hinweise.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength ist die Länge des Puffers (in Bytes), der im Feld "Irp-AssociatedIrp.SystemBuffer>" übergeben wird.
Irp-AssociatedIrp.SystemBuffer> wird mit den Lichtintensitätsinformationen gefüllt.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Der Nutzlasttyp dieses IOCTL wird wie folgt definiert:
C++
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
BYTE Value;
} LAMP_INTENSITY_WHITE;
Das Feld "Wert" ist die weiße Lichtintensität in Prozent zwischen 0 und 100 einschließlich.
Die IOCTL_LAMP_SET_INTENSITY_WHITE E/A-Anforderung legt den Blitz auf die angegebene Lichtintensität fest.
C++
#define IOCTL_LAMP_SET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf eine LAMP_INTENSITY_WHITE Struktur (details finden Sie unter IOCTL_LAMP_GET_INTENSITY_WHITE ).
Keine.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Die IOCTL_LAMP_GET_INTENSITY_COLOR E/A-Anforderung fragt die Lichtintensität ab, wenn der Blitz so konfiguriert ist, dass Farblicht ausgegeben wird.
C++
#define IOCTL_LAMP_GET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf eine LAMP_INTENSITY_COLOR Struktur. Weitere Informationen finden Sie im Abschnitt Hinweise.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength ist die Länge des Puffers (in Bytes), der im Feld "Irp-AssociatedIrp.SystemBuffer>" übergeben wird.
Irp-AssociatedIrp.SystemBuffer> wird mit den Lichtintensitätsinformationen gefüllt.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Der Nutzlasttyp dieses IOCTL wird wie folgt definiert:
C++
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_COLOR.
typedef struct LAMP_INTENSITY_COLOR
{
BYTE Red; // Red light intensity in percentage (0-100)
BYTE Green; // Green light intensity in percentage (0-100)
BYTE Blue; // Blue light intensity in percentage (0-100)
} LAMP_INTENSITY_COLOR;
Die IOCTL_LAMP_SET_INTENSITY_COLOR E/A-Anforderung legt den Blitz auf die angegebene Lichtintensität fest.
C++
#define IOCTL_LAMP_SET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf eine LAMP_INTENSITY_COLOR Struktur (details finden Sie unter IOCTL_LAMP_GET_INTENSITY_COLOR ).
Keine.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Die IOCTL_LAMP_GET_EMITTING_LIGHT E/A-Anforderung fragt ab, ob die (Blitz)-Beleuchtung aktiviert ist.
C++
#define IOCTL_LAMP_GET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf einen Puffer vom Typ BOOLEAN.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength ist die Länge des Puffers (in Bytes), der im Feld "Irp-AssociatedIrp.SystemBuffer>" übergeben wird.
Irp-AssociatedIrp.SystemBuffer> ist mit dem Blitzzustand mit TRUE gefüllt, d. h. der Blitz ist eingeschaltet (z. B. emittierendes Licht); Andernfalls FALSE.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest. Irp-IoStatus.Information> wird auf die Anzahl der Bytes festgelegt, die zum Halten eines DWORD-Werts erforderlich sind.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Die IOCTL_LAMP_SET_EMITTING_LIGHT E/A-Anforderung aktiviert/deaktiviert das Licht (Blitzlicht).
C++
#define IOCTL_LAMP_SET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> verweist auf einen Puffer vom Typ BOOLEAN mit WAHR, der ON angibt; Andernfalls FALSE.
Keine.
Der Treiber legt "Irp-IoStatus.Status>" auf STATUS_SUCCESS oder den entsprechenden Fehlerstatus fest.
Wenn eine MediaCapture-Sitzung Daten streamt, zu dem diese Anforderung erfolgt, sollte der Treiber einen Fehler (STATUS_RESOURCE_IN_USE) über Irp-IoStatus.Status> zurückgeben.
Wie in Concurrency Use Cases beschrieben, muss der Flash-Treiber PnP-Benachrichtigungen senden, um die Ressourcenverfügbarkeit zu melden. Dies kann durch Aufrufen von IoReportTargetDeviceChange (oder IoReportTargetDeviceChangeAsynchronous) mit den folgenden GUIDs erfolgen, je nach Szenario:
Die Flash-Ressource wurde gelöscht, da eine Aufnahmesitzung (oder eine andere Flashlight-Anwendung) gestartet wird:
Attribut Einstellung Identifier GUID_LAMP_RESOURCES_LOST Klassen-GUID {F770E98C-4403-48C9-B1D2-4EEC3302E41F} Die Flash-Ressource ist jetzt verfügbar:
Attribut Einstellung Identifier GUID_LAMP_RESOURCES_AVAILABLE Klassen-GUID {185FE7CE-2616-481B-9094-20BB893ACD81}