Utilisation des canaux USB dans les pilotes UMDF 1.x
Avertissement
UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2.
Les exemples UMDF 1 archivés sont disponibles dans la mise à jour des exemples de pilotes Windows 11, version 22H2 - Mai 2022.
Pour plus d’informations, consultez Prise en main avec UMDF.
L’infrastructure représente chaque canal d’une interface USB en tant qu’objet de canal USB de framework. Lorsqu’un pilote configure un périphérique USB, l’infrastructure crée un objet de canal USB d’infrastructure pour chaque canal dans chaque interface sélectionnée. Les méthodes d’objet de canal permettent à un pilote de :
Obtention d’informations sur le canal UMDF-USB
Après qu’un pilote UMDF a appelé la méthode IWDFUsbInterface::RetrieveUsbPipeObject pour obtenir un pointeur vers l’interface IWDFUsbTargetPipe pour un objet de canal USB, le pilote peut appeler les méthodes suivantes définies par l’objet de canal USB pour obtenir des informations sur le canal USB :
IWDFUsbTargetPipe::GetInformation
Récupère des informations sur un canal USB et son point de terminaison.
IWDFUsbTargetPipe::GetType
Retourne le type d’un canal USB.
IWDFUsbTargetPipe::IsInEndPoint
Détermine si un canal USB est connecté à un point de terminaison d’entrée.
IWDFUsbTargetPipe::IsOutEndPoint
Détermine si un canal USB est connecté à un point de terminaison de sortie.
IWDFUsbTargetPipe::RetrievePipePolicy
Récupère une stratégie de canal WinUsb.
Lecture à partir d’un canal UMDF-USB
Pour lire des données à partir d’un canal d’entrée USB, votre pilote peut utiliser l’une des techniques suivantes (ou les deux) :
Lit les données de manière synchrone.
Pour lire des données de manière synchrone à partir d’un canal d’entrée USB, un pilote UMDF appelle d’abord la méthode IWDFIoTarget::FormatRequestForRead pour générer une demande de lecture. Ensuite, le pilote appelle la méthode IWDFIoRequest::Send , en spécifiant l’indicateur WDF_REQUEST_SEND_OPTION_SYNCHRONOUS, pour envoyer la requête de manière synchrone.
Lire les données de manière asynchrone.
Pour lire des données de manière asynchrone à partir d’un canal d’entrée USB, un pilote UMDF appelle d’abord la méthode IWDFIoTarget::FormatRequestForRead pour générer une demande de lecture. Ensuite, le pilote appelle la méthode IWDFIoRequest::Send sans spécifier l’indicateur WDF_REQUEST_SEND_OPTION_SYNCHRONOUS.
Lit les données de façon synchrone et continue.
Un lecteur continu est un mécanisme fourni par l’infrastructure qui garantit qu’une demande de lecture est toujours disponible pour un canal USB. Ce mécanisme garantit que le pilote est toujours prêt à recevoir des données d’un appareil qui fournit un flux d’entrée asynchrone et non sollicité. Par exemple, un pilote pour un carte d’interface réseau peut utiliser un lecteur continu pour recevoir des données d’entrée.
Pour configurer un lecteur continu pour un canal d’entrée, la fonction de rappel IPnpCallbackHardware::OnPrepareHardware du pilote doit appeler la méthode IWDFUsbTargetPipe2::ConfigureContinuousReader . Cette méthode met en file d’attente un ensemble de demandes de lecture vers la cible d’E/S de l’appareil.
En outre, la fonction de rappel IPnpCallback::OnD0Entry du pilote doit appeler IWDFIoTargetStateManagement::Start pour démarrer le lecteur continu et la fonction de rappel IPnpCallback::OnD0Exit du pilote doit appeler IWDFIoTargetStateManagement::Stop pour arrêter le lecteur continu.
Chaque fois que les données sont disponibles à partir de l’appareil, la cible d’E/S termine une demande de lecture et l’infrastructure appelle l’une des deux fonctions de rappel : IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion si la cible d’E/S a correctement lu les données, ou IUsbTargetPipeContinuousReaderCallbackReaderFailed::OnReaderFailure si la cible d’E/S signale une erreur.
Une fois qu’un pilote a appelé IWDFUsbTargetPipe2::ConfigureContinuousReader, le pilote ne peut pas utiliser IWDFIoRequest::Send pour envoyer des demandes d’E/S au canal, sauf si la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReaderFailed::OnReaderFailure du pilote est appelée et retourne FALSE.
Les lecteurs continus sont pris en charge dans les versions UMDF 1.9 et ultérieures.
Écriture sur un canal UMDF-USB
Pour écrire des données dans un canal de sortie USB, un pilote UMDF peut d’abord appeler la méthode IWDFIoTarget::FormatRequestForWrite pour générer une demande d’écriture. Ensuite, le pilote peut appeler la méthode IWDFIoRequest::Send pour envoyer la requête de manière asynchrone.
Arrêt, vidage et réinitialisation d’un canal UMDF-USB
Un pilote UMDF peut appeler les méthodes suivantes pour arrêter, vider ou réinitialiser un canal USB :
IWDFUsbTargetPipe::Abort
Envoie de façon synchrone une demande d’arrêt de tous les transferts en attente sur un canal USB.
IWDFUsbTargetPipe::Flush
Envoie de manière synchrone une demande d’abandon des données enregistrées par WinUsb lorsque l’appareil a retourné plus de données que le client n’en a demandé.
IWDFUsbTargetPipe::Reset
Envoie de façon synchrone une demande de réinitialisation d’un canal USB.
Définition de la stratégie pour un canal UMDF-USB
Un pilote UMDF peut appeler la méthode IWDFUsbTargetPipe::SetPipePolicy pour contrôler le comportement utilisé par WinUsb pour un canal USB (par exemple, les délais d’attente, la gestion des paquets courts et d’autres comportements).
Gestion des erreurs de canal
Si la cible USB de votre pilote effectue une demande d’E/S avec une erreur status valeur, votre pilote doit effectuer les opérations suivantes :
Appelez IWDFIoTargetStateManagement::Stop avec l’indicateur WdfIoTargetCancelSentIo défini. Cet appel arrête le canal et annule toutes les demandes d’E/S supplémentaires que le pilote a envoyées à la cible USB, si la cible n’a pas terminé les requêtes.
Appelez IWDFUsbTargetPipe::Abort pour envoyer une demande d’abandon au canal.
Appelez IWDFUsbTargetPipe::Reset pour envoyer une demande de réinitialisation au canal.
Appelez IWDFIoTargetStateManagement::Start pour redémarrer le canal.
Renvoyez la demande d’E/S qui a échoué et toutes les demandes d’E/S qui ont suivi la demande ayant échoué.