IOCTL_ATA_PASS_THROUGH IOCTL (ntddscsi.h)

Article
08/07/2023

Permet à une application d’envoyer presque n’importe quelle commande ATA à un appareil cible, avec les restrictions suivantes :

S’il existe un pilote de classe pour le type d’appareil cible, l’application doit envoyer la demande au pilote de classe. Ainsi, une application peut envoyer cette requête directement au pilote de port système pour une unité logique cible (LU) uniquement s’il n’existe aucun pilote de classe pour le type d’appareil connecté à cette lu. Le pilote de port système ne case activée pas pour déterminer si un périphérique a été revendiqué par un pilote de classe avant de traiter une demande directe. Par conséquent, si une application contourne un pilote de classe qui a revendiqué un appareil et envoie une demande directe pour ce périphérique directement au pilote de port, un conflit de contrôle de l’appareil peut se produire entre le pilote de classe et l’application.
Cette requête ne peut pas être utilisée si la commande nécessite que le pilote sous-jacent accède directement à la mémoire. Si la commande de l’appelant peut nécessiter un accès direct à la mémoire, utilisez IOCTL_ATA_PASS_THROUGH_DIRECT à la place.
Les applications ne doivent pas tenter d’envoyer une demande directe de manière asynchrone. Toutes les demandes directes doivent être synchrones.
Les applications ne nécessitent pas de privilèges administratifs pour envoyer une demande directe à un appareil, mais elles doivent disposer d’un accès en lecture/écriture à l’appareil.

L’application appelante fournit le contenu du registre du fichier de tâches ATA pour la commande prévue dans la structure ATA_PASS_THROUGH_EX . Le système double la mise en mémoire tampon de tous les transferts de données. Cette requête est généralement utilisée pour transférer de petites quantités de données (moins de 16 Ko).

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d'entrée

La mémoire tampon sur Irp-AssociatedIrp.SystemBuffer> doit contenir une structure ATA_PASS_THROUGH_EX, qui inclut un ensemble de registres d’entrée de fichier de tâches qui indiquent le type de commande à exécuter et ses paramètres. L’appelant doit initialiser tous les membres de cette structure à l’exception de PathId, TargetId et Lun, que le pilote de port remplit. Pour une commande data-out, le membre DataBufferOffset de la structure doit pointer vers une mémoire tampon alignée sur le cache contenant les données à écrire.

Longueur de la mémoire tampon d’entrée

Parameters.DeviceIoControl.InputBufferLength indique la taille en octets de la mémoire tampon sur Irp->AssociatedIrp.SystemBuffer. Si la commande ATA incorporée est une opération d’écriture, la taille de la mémoire tampon d’entrée doit être la somme de sizeof(ATA_PASS_THROUGH_EX) et la valeur dans le membre DataTransferLength de ATA_PASS_THROUGH_EX. L’exemple de pseudocode suivant montre comment calculer la taille de la mémoire tampon :

ULONG buffsize; // size of the buffer
ATA_PASS_THROUGH_EX hdr;
hdr.DataTransferLength = size in bytes of the data transfer
buffsize = sizeof (ATA_PASS_THROUGH_EX) + hdr.DataTransferLength

Si la commande ATA incorporée est une opération de lecture ou une opération de contrôle d’appareil qui n’implique pas de transfert de données, InputBufferLength doit être égal à sizeof (ATA_PASS_THROUGH_EX).

Dans les deux cas, si InputBufferLength est inférieur à sizeof (ATA_PASS_THROUGH_EX), le pilote de port échoue à la requête d’E/S et retourne une erreur.

Mémoire tampon de sortie

Le pilote de port met en forme les données de retour à l’aide d’une structure ATA_PASS_THROUGH_EX et stocke les données dans la mémoire tampon sur Irp-AssociatedIrp.SystemBuffer>.

Le pilote de port remplit le membre CurrentTaskFile avec les valeurs présentes dans les registres de sortie de l’appareil à l’achèvement de la commande ATA incorporée. Si la commande était un transfert de données, le pilote de port stocke les données transférées dans une mémoire tampon alignée sur le cache qui se trouve à un décalage des octets DataBufferOffset par rapport au début de la structure. L’application est responsable de l’interprétation du contenu des registres de sortie pour déterminer les erreurs, le cas échéant, qui ont été retournées par l’appareil.

Longueur de la mémoire tampon de sortie

Le pilote de port met à jour le membre DataTransferLength de ATA_PASS_THROUGH_EX pour indiquer la quantité de données effectivement transférées à partir de l’appareil. Si la commande ATA incorporée est une opération d’écriture ou une opération de contrôle d’appareil qui ne transfère pas de données, OutputBufferLength est égal à sizeof(ATA_PASS_THROUGH_EX). Si la commande ATA incorporée est une opération de lecture, OutputBufferLength est égal à sizeof(ATA_PASS_THROUGH_EX) + DataTransferLength.

Bloc d’état

Le membre Information est défini sur le nombre d’octets retournés dans la mémoire tampon de sortie sur Irp-AssociatedIrp.SystemBuffer>. Le membre Status est défini sur STATUS_SUCCESS ou éventuellement sur STATUS_BUFFER_TOO_SMALL ou STATUS_INVALID_PARAMETER si la valeur d’entrée Status dans ATA_PASS_THROUGH_EX est incorrectement définie.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows Server 2003.
En-tête	ntddscsi.h (inclure Ntddscsi.h)

Voir aussi

ATA_PASS_THROUGH_EX

IOCTL_ATA_PASS_THROUGH_DIRECT

Partager via