IOCTL_SCSI_PASS_THROUGH_DIRECT IOCTL (ntddscsi.h)

Article
08/07/2023

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.
Les opérations de transfert de données bidirectionnelles ne sont pas prises en charge.
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

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 DataBuffer de SCSI_PASS_THROUGH_DIRECT 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 , si l’appelant demande des données d’sens de requête.

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, qui doit être au moins (sens taille de la taille + desdonnéesde (SCSI_PASS_THROUGH_DIRECT)). La taille de la structure SCSI_PASS_THROUGH_DIRECT est fixe.

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 à la mémoire tampon sur Irp-AssociatedIrp.SystemBuffer>.

Longueur de la mémoire tampon de sortie

SenseInfoLength et DataTransferLength 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 DataBuffer .

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 est incorrectement définie ou si la mémoire tampon spécifiée dans DataBuffer 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;
}

Configuration requise

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

Voir aussi

IOCTL_SCSI_PASS_THROUGH

IOCTL_STORAGE_QUERY_PROPERTY

SCSI_PASS_THROUGH_DIRECT

Partager via