Formazione
Modulo
Troubleshoot device driver failures - Training
This module focuses on the role of device drivers and troubleshooting problems that pertain to them.
Supporto della torcia
A partire da Windows Threshold, verrà esposta una nuova API Lamp WinRT che consente di programmare flash della fotocamera senza la necessità di creare un'istanza di Windows.Media.Capture.MediaCapture. In questo modo, uno sviluppatore può scrivere un'applicazione torcia (solo a scopo di illuminazione) disegnando meno quantità di risorse, inclusa la potenza, in modo che un dispositivo di calcolo possa essere ottimizzato per la durata della batteria e le prestazioni.
A tale scopo, un IHV/OEM implementa un driver WDM che supporta le funzioni seguenti:
Consentire al sistema di enumerare tutti i dispositivi flash.
Attivare/disattivare la torcia per dispositivo.
Se applicabile, regolare l'intensità della luce (simile a PowerPercent) per dispositivo.
Se applicabile, specificare il colore chiaro per dispositivo.
In termini di funzionalità, l'elenco precedente si sovrappone in modo significativo a quello di MediaCapture (ad esempio, FlashControl e TorchControl). Inoltre, lo stesso hardware flash viene usato sia per la luce che per l'acquisizione flash-during-capture. Di conseguenza, un IHV/OEM è consigliabile supportare entrambi i tipi di operazioni usando un singolo driver WDM per controllare il flash esclusivamente. La figura seguente illustra il concetto:
Nell'esempio precedente è presente una sola istanza hardware flash (mostrata come) ed è gestita da un singolo driver flash KMDF. Il driver flash espone due interfacce del dispositivo, ognuna delle quali è destinata a un tipo specifico di client (o API WinRT). Ad esempio, data la figura precedente:
L'API di acquisizione multimediale WinRT e il minidriver AVStream comunicano sempre con il driver flash tramite l'interfaccia GUID_DEVINTERFACE_CAMERA_FLASH, mentre
L'API Lamp WinRT comunica sempre con il driver flash tramite l'interfaccia GUID_DEVINTERFACE_LAMP.
Poiché l'interfaccia GUID_DEVINTERFACE_CAMERA_FLASH viene usata da un minidriver AVStream specifico del fornitore, un IHV/OEM è libero di definirne le funzionalità in modo che non vi sarà alcuna restrizione imposta da Windows.
Tuttavia, Microsoft standardizzerà l'interfaccia, GUID_DEVINTERFACE_LAMP, in quanto verrà usata dall'API Lamp WinRT. Per altre informazioni su GUID_DEVINTERFACE_LAMP, vedere GUID della classe dell'interfaccia del dispositivo
Un flash della fotocamera viene in genere considerato come una periferica subordinata a un dispositivo di acquisizione . Non è progettato per essere condiviso con scenari non fotocamera durante l'esecuzione dell'acquisizione. Per complicare ulteriormente, il numero di dispositivi flash su uno chassis è estremamente limitato in modo che, in pratica, non ci sarà flash risparmiato dedicato solo allo scopo della torcia.
Dal punto di vista del software, il precedente impone una sfida in cui un'applicazione fotocamera e un'applicazione torcia possono coesistere e accedere al flash contemporaneamente. Ad esempio, in teoria, un utente può attivare o disattivare lo stato del LED tramite un'applicazione torcia mentre è in esecuzione un mirino della fotocamera.
Poiché la fotocamera richiede controlli precisi sul flash per supportare lo stato attivo e l'acquisizione, può essere difficile per il driver risolvere le richieste flash di interessi in conflitto garantendo al tempo stesso la qualità dell'immagine. Per risolvere questo problema, i criteri seguenti vengono applicati a livello di sistema come contratto:
Se una sessione di acquisizione viene avviata per la prima volta, un'applicazione flashlight non può modificare il flash fino all'arresto dell'acquisizione.
Un'applicazione flashlight può comunque acquisire un handle per il driver flash, ma qualsiasi operazione che modifica lo stato flash restituisce un errore immediato.
Quando l'acquisizione si arresta in modo che il minidriver AVStream rilasci il flash, il driver flash è necessario per pubblicare una notifica PnP (vedere GUID_LAMP_RESOURCES_AVAILABLE in Notifiche asincrone) che indica che l'hardware sottostante è ora diventato disponibile. Dopo aver ricevuto tale notifica, un'applicazione torcia può programmare il flashing di conseguenza.
Se un'applicazione flashlight viene avviata per la prima volta, una sessione di acquisizione è libera di dirottare l'hardware flash senza consenso esplicito.
Con "hijacking", si intende che un IHV/OEM può implementare un protocollo arbitrario (possibilmente tramite l'interfaccia GUID_DEVINTERFACE_CAMERA_FLASH) in modo che il minidriver AVStream sia autorizzato ad acquisire flash come se l'hardware non venga usato affatto.
Quando si verifica un hijack, il driver flash è necessario per pubblicare un'altra notifica PnP (vedere GUID_LAMP_RESOURCES_LOST in Notifiche asincrone) che indica che il flash è stato riassegnato involontariamente in modo che l'applicazione flashlight possa agire di conseguenza (aggiornando ad esempio l'interfaccia utente)
Se la fotocamera non è coinvolta e due applicazioni flashlight vengono eseguite in successione, il driver deve mantenere la manutenzione del primo client che ha già acquisito l'interfaccia GUID_DEVINTERFACE_LAMP e rifiutare tutti i client aggiuntivi fino alla prima versione finale dell'interfaccia.
In altre parole, l'interfaccia GUID_DEVINTERFACE_LAMP consente solo un client torcia alla volta e il primo client che acquisisce l'interfaccia impedisce ad altri utenti di eseguire (fotocamera/AVStream escluso).
Un driver flash IHV/OEM in grado di supportare la torcia indipendente da MediaCapture deve registrarsi con il GUID della classe device interface, GUID_DEVINTERFACE_LAMP.
| Attributo | Impostazione |
|---|---|
| Identifier | GUID_DEVINTERFACE_LAMP |
| GUID classe | {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98} |
Il GUID della classe dell'interfaccia del dispositivo di GUID_DEVINTERFACE_CAMERA_FLASH può essere definito dagli IHVs/OEM. Tuttavia, il GUID della classe dell'interfaccia del dispositivo di GUID_DEVINTERFACE_LAMP è definito da Windows.
Per contratto, un driver che espone l'interfaccia del dispositivo, GUID_DEVINTERFACE_LAMP, è necessario per supportare le funzioni seguenti (vedere le sezioni successive per informazioni dettagliate):
IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR} : ottiene tutte le modalità (ad esempio, solo bianco e colore) supportate dall'hardware sottostante
IOCTL_LAMP_{GET|SET}_MODE : ottiene o imposta la modalità corrente
IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR} : ottiene o imposta l'intensità della luce
IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT : ottiene o imposta lo stato flash (ad esempio, ON/OFF)
Se un dispositivo ha più di un hardware flash di tipi diversi (ad esempio, sia un LED bianco che un flash Xenon) e questi hardware sono controllati da driver flash diversi, ogni driver espone la stessa interfaccia GUID_DEVINTERFACE_LAMP con un ID istanza univoco.
Poiché un dispositivo di calcolo può avere zero o più dispositivi flash su pannelli diversi, l'API Lamp WinRT necessita di un meccanismo per enumerare tutto l'hardware flash in modo che un'applicazione possa programmare un'istanza specifica.
Per supportare l'enumerazione del dispositivo, analogamente al driver della fotocamera, il driver flash è necessario per associare una struttura ACPI _PLD v2 a ogni interfaccia GUID_DEVINTERFACE_LAMP come dati delle proprietà dell'interfaccia.
La richiesta di I/O IOCTL_LAMP_GET_CAPABILITIES_WHITE esegue una query sulle funzionalità del flash quando il dispositivo è configurato per generare luce bianca.
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> punta a un buffer di tipo LAMP_CAPABILITIES_WHITE. Pe altri dettagli, vedere la sezione Osservazioni.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp-AssociatedIrp.SystemBuffer>.
Irp-AssociatedIrp.SystemBuffer> è pieno di tutte le funzionalità supportate dall'hardware flash.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato. Imposta Irp-IoStatus.Information> sul numero di byte necessari per contenere il buffer.
Per requisito, è necessario un flash il cui driver supporta l'interfaccia GUID_DEVINTERFACE_LAMP per supportare l'emissione di luce bianca. Il payload di questo IOCTL è definito come segue:
C++
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;
Il campo IsLightIntensityAdjustable indica se è possibile programmare il livello di luminanza. Se questo campo restituisce false, significa che il dispositivo sottostante supporta solo l'interruttore on/off e l'intensità della luce non può essere modificata.
La richiesta di I/O IOCTL_LAMP_GET_CAPABILITIES_COLOR esegue una query sulle funzionalità del flash quando il dispositivo è configurato per generare luce del colore.
C++
#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_CAPABILITIES_COLOR. Pe altri dettagli, vedere la sezione Osservazioni.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp-AssociatedIrp.SystemBuffer>.
Irp-AssociatedIrp.SystemBuffer> è pieno di tutte le funzionalità supportate dall'hardware flash.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato. Imposta Irp-IoStatus.Information> sul numero di byte necessari per contenere il buffer.
Il payload di questo IOCTL è definito come segue:
C++
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
BOOLEAN IsSupported;
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;
Il primo campo IsSupported indica se il flash può generare luce di colore. Se l'hardware non supporta la luce del colore, il driver deve impostare questo campo su false.
Il secondo campo IsLightIntensityAdjustable indica se è possibile programmare il livello di luminanza. Se il flash non supporta la luce del colore (ad esempio, IsSupported valuta false), un client deve eliminare il valore di IsLightIntensityAdjustable.
Il IOCTL_LAMP_GET_MODE richiesta di I/O esegue una query sulla modalità con cui il flash è attualmente configurato.
C++
#define IOCTL_LAMP_GET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_MODE, definito come segue:
C++
typedef enum LAMP_MODE
{
LAMP_MODE_WHITE = 0,
LAMP_MODE_COLOR
} LAMP_MODE;
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp-AssociatedIrp.SystemBuffer>.
Irp-AssociatedIrp.SystemBuffer> viene riempito con un valore LAMP_MODE.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato. Imposta Irp-IoStatus.Information> sul numero di byte necessari per contenere un valore DWORD.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
La richiesta di I/O IOCTL_LAMP_SET_MODE imposta la modalità di funzionamento del flash.
C++
#define IOCTL_LAMP_SET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo LAMP_MODE.
Nessuno.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
La richiesta di I/O IOCTL_LAMP_GET_INTENSITY_WHITE esegue una query sull'intensità della luce quando il flash è configurato per generare luce bianca.
C++
#define IOCTL_LAMP_GET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a una struttura LAMP_INTENSITY_WHITE. Pe altri dettagli, vedere la sezione Osservazioni.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp-AssociatedIrp.SystemBuffer>.
Irp-AssociatedIrp.SystemBuffer> viene riempito con le informazioni sull'intensità della luce.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
Il tipo di payload di questo IOCTL è definito come segue:
C++
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
BYTE Value;
} LAMP_INTENSITY_WHITE;
Il campo Valore è l'intensità della luce bianca in percentuale compresa tra 0 e 100 inclusi.
La richiesta di I/O IOCTL_LAMP_SET_INTENSITY_WHITE imposta il flash sull'intensità di luce specificata.
C++
#define IOCTL_LAMP_SET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a una struttura LAMP_INTENSITY_WHITE (vedere IOCTL_LAMP_GET_INTENSITY_WHITE per informazioni dettagliate).
Nessuno.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
La richiesta di I/O IOCTL_LAMP_GET_INTENSITY_COLOR esegue una query sull'intensità della luce quando il flash è configurato per generare la luce del colore.
C++
#define IOCTL_LAMP_GET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a una struttura LAMP_INTENSITY_COLOR. Pe altri dettagli, vedere la sezione Osservazioni.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp-AssociatedIrp.SystemBuffer>.
Irp-AssociatedIrp.SystemBuffer> viene riempito con le informazioni sull'intensità della luce.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
Il tipo di payload di questo IOCTL è definito come segue:
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;
La richiesta di I/O IOCTL_LAMP_SET_INTENSITY_COLOR imposta il flash sull'intensità di luce specificata.
C++
#define IOCTL_LAMP_SET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a una struttura LAMP_INTENSITY_COLOR (vedere IOCTL_LAMP_GET_INTENSITY_COLOR per informazioni dettagliate).
Nessuno.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
La IOCTL_LAMP_GET_EMITTING_LIGHT query di richiesta di I/O se la luce (flash) è attivata.
C++
#define IOCTL_LAMP_GET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo BOOLEAN.
IO_STACK_LOCATION. Parameters.DeviceIoControl.OutputBufferLength è la lunghezza del buffer (in byte) passato nel campo Irp-AssociatedIrp.SystemBuffer>.
Irp-AssociatedIrp.SystemBuffer> viene riempito con lo stato flash con TRUE, il che significa che il flash è attivato (ad esempio, emettendo luce); FALSE in caso contrario.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato. Imposta Irp-IoStatus.Information> sul numero di byte necessari per contenere un valore DWORD.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
La richiesta di I/O IOCTL_LAMP_SET_EMITTING_LIGHT attiva/disattiva la luce (flash).
C++
#define IOCTL_LAMP_SET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)
Irp-AssociatedIrp.SystemBuffer> punta a un buffer di tipo BOOLEAN con TRUE che indica ON; FALSE in caso contrario.
Nessuno.
Il driver imposta Irp-IoStatus.Status> su STATUS_SUCCESS o sullo stato di errore appropriato.
Se una sessione MediaCapture esegue lo streaming dei dati al momento in cui viene effettuata questa richiesta, il driver deve restituire un errore (STATUS_RESOURCE_IN_USE) tramite Irp-IoStatus.Status>.
Come descritto in Casi d'uso della concorrenza, il driver flash è necessario per inviare notifiche PnP per segnalare la disponibilità delle risorse. A tale scopo, è possibile chiamare IoReportTargetDeviceChange (o IoReportTargetDeviceChangeAsynchronous) con i GUID seguenti a seconda dello scenario:
La risorsa flash è stata rimossa perché viene avviata una sessione di acquisizione (o un'altra applicazione flashlight):
Attributo Impostazione Identifier GUID_LAMP_RESOURCES_LOST GUID classe {F770E98C-4403-48C9-B1D2-4EEC302E41F} La risorsa flash è ora disponibile:
Attributo Impostazione Identifier GUID_LAMP_RESOURCES_AVAILABLE GUID classe {185FE7CE-2616-481B-9094-20BB893ACD81}