IOCTL_SCSI_PASS_THROUGH_DIRECT_EX IOCTL (ntddscsi.h)

Article
06/08/2024

La demande de code de contrôle IOCTL_SCSI_PASS_THROUGH_DIRECT_EX est la version étendue de la demande IOCTL_SCSI_PASS_THROUGH_DIRECT . Cette demande prend en charge les transferts de données bidirectionnels et autorise un bloc de données de commande (CDB) > de 16 octets.

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

Les commandes multi-cibles, telles que COPY, ne sont pas autorisées.
S’il existe un pilote de classe pour le type d’appareil cible, la demande doit être envoyée à ce pilote de classe. Par conséquent, une application peut envoyer cette requête directement au pilote de port système pour une unité logique cible uniquement s’il n’existe aucun pilote de classe pour le type d’appareil connecté à cette lu.
Cette demande doit être effectuée si la base de données CDB d’entrée peut nécessiter que le pilote miniport sous-jacent accède directement à la mémoire.

L’application appelante crée le bloc de descripteur de commande SCSI, qui peut inclure une demande de données d’sens de requête si une condition CHECK se produit. Si la CDB demande une opération de transfert de données, l’appelant doit configurer une mémoire tampon alignée sur le périphérique de l’adaptateur à partir de laquelle ou dans laquelle le pilote miniport peut transférer des données directement. Cette requête est généralement utilisée pour transférer de plus grandes quantités de données (>16 Ko).

Les applications peuvent envoyer cette demande au moyen d’une demande de IRP_MJ_DEVICE_CONTROL .

Les pilotes de classe de stockage définissent le numéro IRP secondaire sur IRP_MN_SCSI_CLASS pour indiquer que la demande a été traitée par un pilote de classe de stockage.

Note Les modèles de pilote de port SCSI et de pilote miniport SCSI peuvent être modifiés ou indisponibles à l’avenir. Au lieu de cela, nous vous recommandons d’utiliser les modèles de pilote Storport et de pilote miniport Storport .

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d'entrée

Parameters.DeviceIoControl.InputBufferLength indique la taille, en octets, de la mémoire tampon sur Irp->AssociatedIrp.SystemBuffer, qui doit être au moins (sens taille + des données(SCSI_PASS_THROUGH_DIRECT_EX)). La taille de la structure SCSI_PASS_THROUGH_DIRECT_EX est fixe.

Cette structure inclut une base de données CDB SCSI, qui doit être initialisée par l’appelant, à l’exception du chemin d’accès, de l’ID cible et du numéro d’unité logique, qui sont renseignés par le pilote de port. Pour une commande data-out, les données à transférer doivent se trouver dans une mémoire tampon alignée sur le périphérique de l’adaptateur. Le membre DataInBuffer de SCSI_PASS_THROUGH_DIRECT_EX est un pointeur vers cette mémoire tampon alignée sur le périphérique de l’adaptateur. L’appelant doit allouer du stockage supplémentaire, en suivant la structure SCSI_PASS_THROUGH_DIRECT_EX , si l’appelant demande des données d’sens de requête.

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

Mémoire tampon de sortie

Le pilote de port retourne toutes les données d’sens de requête et la structure SCSI_PASS_THROUGH_DIRECT_EX à la mémoire tampon sur Irp-AssociatedIrp.SystemBuffer>.

Longueur de la mémoire tampon de sortie

SenseInfoLength et DataOutTransferLength sont mis à jour pour indiquer la quantité de données transférées. Le pilote de port retourne toutes les données transférées de l’appareil vers la mémoire tampon alignée sur le cache fournie sur DataOutBuffer.

Bloc d’état

Le champ Informations est défini sur le nombre d’octets retournés dans la mémoire tampon de sortie sur Irp-AssociatedIrp.SystemBuffer>. Le champ État est défini sur STATUS_SUCCESS, ou éventuellement sur STATUS_BUFFER_TOO_SMALL ou STATUS_INVALID_PARAMETER si la valeur longueur d’entrée dans SCSI_PASS_THROUGH_DIRECT_EX est incorrectement définie ou si la mémoire tampon spécifiée dans DataInBuffer n’est pas correctement alignée sur l’appareil.

Remarques

Pour les opérations de transfert de données, une mémoire tampon avec alignement correspondant au périphérique de l’adaptateur est requise. Les applications peuvent récupérer le masque d’alignement de l’appareil en émettant une demande de code de contrôle IOCTL_STORAGE_QUERY_PROPERTY avec un type de requête PropertyStandardQuery et l’ID de propriété StorageAdapterProperty. Le masque d’alignement se trouve dans le membre AlignmentMask de la structure STORAGE_ADAPTER_DESCRIPTOR retournée. Les pilotes peuvent également utiliser la valeur dans le membre AlignmentMask du DeviceObject de l’adaptateur.

Dans l’exemple de fonction suivant, une mémoire tampon est préparée en tant que mémoire tampon de transfert de données alignée sur l’appareil.


PVOID AllocateAlignedBuffer(ULONG size, ULONG AlignmentMask, PVOID *pUnAlignedBuffer)
{
    PVOID AlignedBuffer;
    ULONG_PTR FullWordMask = (ULONG_PTR)AlignmentMask;

    if (AlignmentMask == 0)
    {
        AlignedBuffer = malloc(size);
        // return the original buffer to free later
        *pUnAlignedBuffer = AlignedBuffer;
    }
    else
    {
        // expand the size for the alignment window
        size += AlignmentMask;
        AlignedBuffer = malloc(size);
        // return the original buffer to free later
        *pUnAlignedBuffer = AlignedBuffer;
        // adjust buffer pointer for the desired alignment
        AlignedBuffer = (PVOID)(((ULONG_PTR)AlignedBuffer + FullWordMask) & ~FullWordMask);
    }

    return AlignedBuffer;
}

Pour émettre une demande de IOCTL_SCSI_PASS_THROUGH_DIRECT_EX , le périphérique de stockage sous-jacent doit prendre en charge les SSR étendus. Cela signifie que le type SRB pris en charge est SRB_TYPE_STORAGE_REQUEST_BLOCK. Une application peut interroger la prise en charge de SRB avec la requête IOCTL_STORAGE_QUERY_PROPERTY avec un type de requête PropertyStandardQuery et un type de propriété StorageDeviceProperty. Le membre SrbType retourné dans la structure STORAGE_ADAPTER_DESCRIPTIOR indique SRB_TYPE_SCSI_REQUEST_BLOCK ou SRB_TYPE_STORAGE_REQUEST_BLOCK.

Configuration requise

Condition requise	Valeur
En-tête	ntddscsi.h (inclure Ntddscsi.h)

Voir aussi

IOCTL_SCSI_PASS_THROUGH_EX

IOCTL_STORAGE_QUERY_PROPERTY

SCSI_PASS_THROUGH_DIRECT_EX

Partager via