Demandes d’E/S S SPB
La macro CTL_CODE fournie par le système, qui est décrite dans Définition des codes de contrôle d’E/S, est utilisée pour définir des codes de contrôle IOCTL_SPB_* dans Spb.h.
code de contrôle IOCTL_SPB_EXECUTE_SEQUENCE
Le code de contrôle d’E/S IOCTL_SPB_EXECUTE_SEQUENCE permet à un client (pilote périphérique) du pilote de contrôleur SPB d’effectuer une séquence de transferts (lectures et écritures) sous la forme d’une seule opération atomique avec une seule demande d’E/S. L’appareil désigné sur le bus est la cible pour tous les transferts dans la séquence.
En spécifiant une séquence de transferts de longueur fixe en tant qu’opération atomique unique, la demande de contrôle d’E/S IOCTL_SPB_EXECUTE_SEQUENCE permet au pilote du contrôleur d’optimiser les transferts d’E/S et d’améliorer les performances.
Le client envoie cette demande de contrôle d’E/S à l’objet file pour l’appareil cible.
Un pilote de contrôleur SPB inscrit une fonction de rappel EvtSpbControllerIoSequence pour effectuer les transferts de bus pour une séquence de transfert d’E/S. L’extension d’infrastructure SPB (SpbCx) appelle cette fonction pour passer une requête IOCTL_SPB_EXECUTE_SEQUENCE au pilote de contrôleur SPB pour traitement.
mémoire tampon d’entrée IOCTL_SPB_EXECUTE_SEQUENCE
La mémoire tampon d’entrée est une structure SPB_TRANSFER_LIST, qui contient une liste de pointeurs vers les mémoires tampons de données du client. Cette liste contient une mémoire tampon de données pour chaque transfert (lecture ou écriture) dans la séquence de transfert d’E/S.
IOCTL_SPB_EXECUTE_SEQUENCE longueur de la mémoire tampon d’entrée
Taille d’une structure SPB_TRANSFER_LIST.
IOCTL_SPB_EXECUTE_SEQUENCE status bloc
Si l’opération réussit, le pilote du contrôleur définit le membre Status sur STATUS_SUCCESS et définit le membre Information sur le nombre total d’octets transférés pendant la séquence.
Cette opération peut échouer pour diverses raisons, notamment des ressources insuffisantes, une entrée client non valide et un dysfonctionnement de l’appareil.
Si le pilote du contrôleur commence à traiter la demande d’E/S, mais qu’une erreur se produit pendant l’un des transferts dans la séquence (par exemple, l’appareil cible signale à un NACK de refuser le transfert), le pilote du contrôleur abandonne les transferts restants dans la séquence. Le pilote définit ensuite la status d’achèvement sur STATUS_SUCCESS, définit le membre Information sur le nombre d’octets qui ont été correctement transférés avant que l’erreur ne se produise et termine la demande.
code de contrôle IOCTL_SPB_FULL_DUPLEX
Le code de contrôle IOCTL_SPB_FULL_DUPLEX est utilisé par un client (pilote périphérique) pour demander une opération d’E/S en duplex complet. Les opérations d’E/S en duplex intégral sont prises en charge par des contrôleurs pour les bus tels que SPI qui peuvent lire et écrire simultanément des données. La macro CTL_CODE fournie par le système, décrite dans Définition des codes de contrôle d’E/S, est utilisée pour définir IOCTL_SPB_FULL_DUPLEX comme suit.
Le pilote en mode utilisateur ou le pilote en mode noyau d’un appareil sur le bus envoie cette demande de contrôle d’E/S à l’objet fichier de l’appareil cible.
Cet IOCTL est pris en charge uniquement par les pilotes de contrôleur SPB pour les bus, tels que SPI, qui peuvent lire et écrire des données simultanément.
Les mémoires tampons d’écriture et de lecture pour le transfert en duplex intégral sont décrites par une structure SPB_TRANSFER_LIST. Cette structure doit utiliser le format suivant :
Le tableau de structures SPB_TRANSFER_LIST_ENTRY contient exactement deux éléments. Le premier élément décrit la mémoire tampon d’écriture (Direction = SpbTransferDirectionToDevice). Le deuxième élément décrit la mémoire tampon de lecture (Direction = SpbTransferDirectionFromDevice).
Les membres DelayInUs des deux structures SPB_TRANSFER_LIST_ENTRY doivent être zéro. Les formats de mémoire tampon pour la mémoire tampon d’écriture et la mémoire tampon de lecture peuvent être les suivants :
- SpbTransferBufferFormatSimple
- SpbTransferBufferFormatList
- SpbTransferBufferFormatSimpleNonPaged
- SpbTransferBufferFormatMdl
Les deux derniers formats de la liste précédente peuvent être utilisés uniquement par les clients en mode noyau. Les formats des mémoires tampons d’écriture et de lecture ne doivent pas nécessairement être identiques. Pour plus d’informations sur ces formats de mémoire tampon, consultez SPB_TRANSFER_BUFFER_FORMAT.
Une opération réussie peut définir le membre Information sur une valeur inférieure à la somme des tailles de la mémoire tampon d’écriture et de la mémoire tampon de lecture, ce qui peut se produire si la demande est annulée, ou si l’opération ne peut pas écrire le contenu complet de la mémoire tampon d’écriture sur l’appareil, ou remplir complètement la mémoire tampon de lecture avec des données lues à partir de l’appareil.
Les tailles de mémoire tampon d’écriture et de lecture ne doivent pas nécessairement être identiques. Si la mémoire tampon d’écriture est supérieure à la mémoire tampon de lecture, l’opération continue d’écrire des données à partir de la mémoire tampon d’écriture une fois la mémoire tampon de lecture saturée. Si la mémoire tampon de lecture est plus grande que la mémoire tampon d’écriture, l’opération continue de remplir la mémoire tampon de lecture une fois la mémoire tampon d’écriture vidée.
Si un pilote de contrôleur SPB inscrit une fonction de rappel EvtSpbControllerIoOther, l’extension de l’infrastructure SPB (SpbCx) appelle cette fonction pour passer une demande de IOCTL_SPB_FULL_DUPLEX au pilote de contrôleur SPB pour traitement. SpbCx n’effectue aucune vérification des paramètres, validation de liste de transfert ou autre traitement pour une demande de IOCTL_SPB_FULL_DUPLEX.
Pour plus d’informations sur la façon dont un pilote de contrôleur SPB implémente la prise en charge de cet IOCTL, consultez Gestion des demandes IOCTL_SPB_FULL_DUPLEX.
mémoire tampon d’entrée IOCTL_SPB_FULL_DUPLEX
Pointeur vers une structure SPB_TRANSFER_LIST qui contient des pointeurs vers les mémoires tampons de données d’entrée et de sortie du client. Cette structure contient un tableau Transferts de deux éléments exactement. Le premier élément décrit la mémoire tampon qui contient les données à écrire sur l’appareil. Le deuxième élément décrit la mémoire tampon utilisée pour stocker les données lues à partir de l’appareil. Pour plus d’informations sur la façon dont un pilote de contrôleur SPB implémente une demande de contrôle d’E/S personnalisé (IOCTL) qui utilise SPB_TRANSFER_LIST structures pour décrire les mémoires tampons, consultez Utilisation de la structure SPB_TRANSFER_LIST pour les IOCTL personnalisés.
IOCTL_SPB_FULL_DUPLEX longueur de la mémoire tampon d’entrée
Taille d’une structure SPB_TRANSFER_LIST.
IOCTL_SPB_FULL_DUPLEX status bloc
Si l’opération réussit, le pilote du contrôleur définit le membre Status sur STATUS_SUCCESS et définit le membre Information sur le nombre total d’octets transférés (octets lus plus octets écrits) pendant l’opération de duplex intégral.
Cette opération peut échouer pour diverses raisons, notamment des ressources insuffisantes, une entrée client non valide et un dysfonctionnement de l’appareil.
code de contrôle IOCTL_SPB_LOCK_CONNECTION
Le code de contrôle IOCTL_SPB_LOCK_CONNECTION est utilisé par un client (pilote de périphérique) pour acquérir le verrou de connexion sur un appareil cible connecté À SPB partagé avec un autre client. Lorsqu’un client détient le verrou de connexion, ce client dispose d’un accès exclusif à l’appareil. La macro CTL_CODE fournie par le système, décrite dans Définition des codes de contrôle d’E/S, est utilisée pour définir IOCTL_SPB_LOCK_CONNECTION comme suit.
Les requêtes IOCTL_SPB_LOCK_CONNECTION et IOCTL_SPB_UNLOCK_CONNECTION acquièrent et libèrent le verrou de connexion sur un appareil cible qui est attaché à un bus de périphérique simple. La plupart des clients n’utilisent pas ces demandes de contrôle d’E/S. Ces demandes sont utilisées uniquement si deux clients partagent l’accès au même appareil cible. Pour plus d’informations, consultez Verrous de connexion SPB.
Deux clients peuvent ouvrir des connexions logiques distinctes sur le même appareil cible et utiliser le verrou de connexion lorsque l’un des clients a besoin d’un accès exclusif à l’appareil. Lorsqu’un client détient le verrou, les demandes d’E/S adressées à l’appareil à partir du deuxième client sont automatiquement différées jusqu’à ce que le premier client libère le verrou.
Un client peut simultanément conserver un verrou de connexion sur l’appareil cible et un verrou de contrôleur sur le contrôleur SPB. Les requêtes IOCTL_SPB_LOCK_CONTROLLER et IOCTL_SPB_UNLOCK_CONTROLLER acquièrent et libèrent le verrou du contrôleur. Le client doit acquérir le verrou de connexion avant d’acquérir le verrou de contrôleur, et doit libérer le verrou de contrôleur avant de libérer le verrou de connexion. Un client utilise un verrou de contrôleur pour effectuer un ensemble ordonné de transferts de bus (opérations de lecture et d’écriture) en tant qu’opération de bus atomique unique. Pour plus d’informations, consultez Séquences de transfert d’E/S.
Un verrou de connexion est automatiquement arrêté si une demande de IRP_MJ_CLEANUP est envoyée à un appareil cible alors que la connexion est verrouillée sur l’appareil. Une demande de nettoyage est envoyée à un appareil cible lorsqu’un client ferme son handle de fichier à l’appareil.
IOCTL_SPB_LOCK_CONNECTION status bloc
Si l’opération réussit, le membre Status est défini sur STATUS_SUCCESS.
Si l’opération échoue, le membre Status est défini sur une erreur appropriée status code.
Si le client détient déjà le verrou de connexion sur l’appareil cible ou le verrou du contrôleur sur le contrôleur SPB, cette opération échoue avec Status = STATUS_INVALID_DEVICE_REQUEST. Cette opération peut échouer pour d’autres raisons, notamment des ressources insuffisantes, une entrée client non valide et un dysfonctionnement de l’appareil.
code de contrôle IOCTL_SPB_LOCK_CONTROLLER
Le code de contrôle IOCTL_SPB_LOCK_CONTROLLER est utilisé par un client (pilote périphérique) pour verrouiller le contrôleur SPB. Lorsque le contrôleur est verrouillé, le client utilise exclusivement le bus pour accéder à l’appareil cible spécifié pour le verrou. La macro CTL_CODE fournie par le système, décrite dans Définition des codes de contrôle d’E/S, est utilisée pour définir IOCTL_SPB_LOCK_CONTROLLER comme suit.
Pour obtenir une utilisation exclusive du bus pour accéder à un appareil cible, un client (pilote de périphérique) envoie ce IOCTL à l’objet fichier de la cible. Une fois ce IOCTL terminé, le contrôleur est verrouillé et tous les transferts d’E/S (lecture ou écriture) sur le bus accèdent à la cible désignée. Entre les transferts, le contrôleur conserve l’appareil cible sélectionné, mais arrête l’horloge.
Le contrôleur reste verrouillé jusqu’à ce que le client envoie une demande de IOCTL_SPB_UNLOCK_CONTROLLER pour déverrouiller le contrôleur. Lorsque la séquence de transferts du client vers ou depuis l’appareil cible est terminée, le client doit déverrouiller le contrôleur afin que le contrôleur puisse traiter les demandes d’E/S d’autres cibles sur le bus.
Un verrou est automatiquement arrêté si une requête IRP_MJ_CLEANUP est envoyée à un appareil cible alors que le contrôleur est verrouillé sur la cible. Une demande de nettoyage est envoyée à une cible lorsqu’un client ferme son handle à la cible.
Les contrôleurs SPB ne sont pas requis pour prendre en charge les demandes IOCTL_SPB_LOCK_CONTROLLER et IOCTL_SPB_UNLOCK_CONTROLLER, et les pilotes de périphériques ne doivent pas supposer qu’ils sont pris en charge.
Si un pilote de contrôleur SPB inscrit une fonction de rappel EvtSpbControllerLock, l’extension d’infrastructure SPB (SpbCx) appelle cette fonction pour passer une demande de IOCTL_SPB_LOCK_CONTROLLER au pilote de contrôleur SPB pour traitement.
IOCTL_SPB_LOCK_CONTROLLER status bloc
Si l’opération réussit, le membre Status est défini sur STATUS_SUCCESS. Cet IOCTL peut retourner une erreur status pour plusieurs raisons, notamment l’échec de la configuration du contrôleur pour qu’il fonctionne en mode d’accès exclusif. Dans ce mode, le contrôleur conserve l’appareil cible sélectionné afin qu’il soit la cible exclusive pour tous les transferts d’E/S sur le bus. Le contrôleur reste dans ce mode jusqu’à ce qu’il soit déverrouillé.
code de contrôle IOCTL_SPB_UNLOCK_CONNECTION
Le code de contrôle d’E/S IOCTL_SPB_UNLOCK_CONNECTION est utilisé par un client (pilote de périphérique) pour libérer le verrou de connexion sur un appareil cible connecté à SPB partagé avec un autre client. Le client a précédemment envoyé une IOCTL_SPB_LOCK_CONNECTION demande d’accès exclusif à l’appareil.
Les requêtes IOCTL_SPB_LOCK_CONNECTION et IOCTL_SPB_UNLOCK_CONNECTION acquièrent et libèrent le verrou de connexion sur un appareil cible qui est attaché à un bus périphérique simple. La plupart des clients n’utilisent pas ces demandes de contrôle d’E/S. Ces demandes sont utilisées uniquement si deux clients partagent l’accès au même appareil cible. Pour plus d’informations, consultez Verrous de connexion SPB.
Une fois qu’un client (pilote périphérique) envoie une demande de IOCTL_SPB_LOCK_CONNECTION à un appareil cible sur le bus et que la demande s’est terminée, la connexion reste verrouillée jusqu’à ce que le client envoie une demande IOCTL_SPB_UNLOCK_CONNECTION pour déverrouiller la connexion.
Le client envoie une IOCTL_SPB_UNLOCK_CONNECTION demande de libération du verrou de connexion à l’appareil cible lorsque le client n’a plus besoin d’un accès exclusif à l’appareil. La connexion doit être déverrouillée afin que l’autre client puisse accéder à l’appareil.
IOCTL_SPB_UNLOCK_CONNECTION status bloc
Si l’opération réussit, le membre Status est défini sur STATUS_SUCCESS.
Si l’opération échoue, le membre Status est défini sur une erreur appropriée status code. Si le client ne détient pas le verrou de connexion sur l’appareil cible, ou si le client détient toujours le verrou de connexion sur le contrôleur SPB, cette opération échoue avec Status = STATUS_INVALID_DEVICE_REQUEST. Cette opération peut échouer pour d’autres raisons, notamment des ressources faibles, une entrée client non valide et un dysfonctionnement de l’appareil.
code de contrôle IOCTL_SPB_UNLOCK_CONTROLLER
Le code de contrôle d’E/S IOCTL_SPB_UNLOCK_CONTROLLER est utilisé par un client (pilote périphérique) pour déverrouiller le contrôleur SPB. Le client a précédemment verrouillé le contrôleur pour bénéficier d’une utilisation exclusive du bus pour accéder à un appareil cible sur le bus.
Une fois qu’un client (pilote périphérique) a envoyé une IOCTL_SPB_LOCK_CONTROLLER demande de contrôle d’E/S à un appareil cible sur le bus, le contrôleur reste verrouillé jusqu’à ce que le client envoie une IOCTL_SPB_UNLOCK_CONTROLLER demande de contrôle d’E/S pour déverrouiller le contrôleur. Le client envoie ces demandes de contrôle d’E/S à l’objet fichier de l’appareil cible.
Le client envoie une demande de IOCTL_SPB_UNLOCK_CONTROLLER lorsqu’il a terminé une séquence de transferts sur le bus et qu’il souhaite libérer l’appareil cible. Le contrôleur doit être déverrouillé afin de pouvoir traiter les demandes d’E/S pour d’autres cibles sur le bus.
Les contrôleurs SPB ne sont pas nécessaires pour prendre en charge les demandes IOCTL_SPB_LOCK_CONTROLLER et IOCTL_SPB_UNLOCK_CONTROLLER, et les pilotes de périphériques ne doivent pas supposer qu’ils sont pris en charge.
L’extension de l’infrastructure SPB (SpbCx) appelle la fonction de rappel EvtSpbControllerUnlock facultative d’un pilote de contrôleur SPB pour transmettre une requête IOCTL_SPB_LOCK_CONTROLLER au pilote du contrôleur SPB pour traitement.
IOCTL_SPB_UNLOCK_CONTROLLER status bloc
Si l’opération réussit, le membre Status est défini sur STATUS_SUCCESS.
Ce IOCTL ne peut échouer que s’il est envoyé par un client dont le contrôleur n’est pas verrouillé pour un accès exclusif à la cible désignée.