IOCTL_SCSI_PASS_THROUGH_DIRECT_EX IOCTL (ntddscsi.h)

Artikel
02/07/2025

Die IOCTL_SCSI_PASS_THROUGH_DIRECT_EX Steuerelementcodeanforderung ist die erweiterte Version der IOCTL_SCSI_PASS_THROUGH_DIRECT Anforderung. Diese Anforderung bietet Unterstützung für bidirektionale Datenübertragungen und ermöglicht einen Befehlsdatenblock (CDB) > 16 Bytes.

Ermöglicht einer Anwendung, fast jeden SCSI-Befehl an ein Zielgerät mit den folgenden Einschränkungen zu senden:

Multitarget-Befehle, z. B. KOPIEREN, sind nicht zulässig.
Wenn ein Klassentreiber für den Zieltyp des Geräts vorhanden ist, muss die Anforderung an diesen Klassentreiber gesendet werden. Daher kann eine Anwendung diese Anforderung direkt an den Systemporttreiber für eine ziellogische Einheit senden, wenn kein Klassentreiber für den Typ des mit dieser LU verbundenen Geräts vorhanden ist.
Diese Anforderung muss erfolgen, wenn das Eingabe-CDB möglicherweise den zugrunde liegenden Miniporttreiber für den direkten Zugriff auf den Arbeitsspeicher benötigt.

Die aufrufende Anwendung erstellt den SCSI-Befehlsdeskriptorblock, der eine Anforderung für Anforderungsoptimierungsdaten enthalten kann, wenn eine CHECK CONDITION auftritt. Wenn das CDB einen Datenübertragungsvorgang anfordert, muss der Aufrufer einen Adaptergerät-Ausgerichteten Puffer einrichten, von dem bzw. in den der Miniporttreiber Daten direkt übertragen kann. Diese Anforderung wird in der Regel zum Übertragen größerer Datenmengen (>16K) verwendet.

Anwendungen können diese Anforderung über eine IRP_MJ_DEVICE_CONTROL Anforderung senden.

Speicherklassentreiber legen die Neben-IRP-Nummer auf IRP_MN_SCSI_CLASS fest, um anzugeben, dass die Anforderung von einem Speicherklassentreiber verarbeitet wurde.

Hinweis Der SCSI-Porttreiber und die SCSI-Miniporttreibermodelle können in Zukunft geändert oder nicht mehr verfügbar sein. Stattdessen empfehlen wir die Verwendung des Storport-Treibers und Storport Miniport Treibermodelle.

Hauptcode

IRP_MJ_DEVICE_CONTROL

Eingabepuffer

Parameters.DeviceIoControl.InputBufferLength gibt die Größe des Puffers bei Irp->AssociatedIrp.SystemBuffer-an, die mindestens (Sense-Datengröße + Größe(SCSI_PASS_THROUGH_DIRECT_EX)) sein muss. Die Größe der SCSI_PASS_THROUGH_DIRECT_EX-Struktur ist fest.

Diese Struktur enthält einen SCSI CDB, der vom Aufrufer initialisiert werden muss, mit Ausnahme des Pfads, der Ziel-ID und der LUN, die vom Porttreiber ausgefüllt werden. Bei einem Datenausgangsbefehl müssen sich die zu übertragenden Daten in einem Adaptergerät befinden. Der DataInBuffer- Member von SCSI_PASS_THROUGH_DIRECT_EX ist ein Zeiger auf diesen Adaptergerätpuffer. Der Aufrufer muss zusätzlichen Speicher nach der SCSI_PASS_THROUGH_DIRECT_EX Struktur zuweisen, wenn der Aufrufer nach Anforderungsoptimierungsdaten fragt.

Eingabepufferlänge

Ausgabepuffer

Der Porttreiber gibt alle Anforderungsoptimierungsdaten und die SCSI_PASS_THROUGH_DIRECT_EX Struktur an den Puffer bei Irp->AssociatedIrp.SystemBufferzurück.

Länge des Ausgabepuffers

SenseInfoLength und DataOutTransferLength werden aktualisiert, um die Menge der übertragenen Daten anzugeben. Der Porttreiber gibt alle vom Gerät übertragenen Daten an den bereitgestellten zwischengespeicherten Puffer an DataOutBuffer-zurück.

Statusblock

Das Feld Information wird auf die Anzahl der im Ausgabepuffer zurückgegebenen Bytes bei Irp->AssociatedIrp.SystemBufferfestgelegt. Das feld Status wird auf STATUS_SUCCESSoder möglicherweise auf STATUS_BUFFER_TOO_SMALL oder STATUS_INVALID_PARAMETER festgelegt, wenn die Eingabe Length Wert in SCSI_PASS_THROUGH_DIRECT_EX nicht ordnungsgemäß festgelegt ist oder der in DataInBuffer angegebene Puffer nicht ordnungsgemäß ausgerichtet ist.

Bemerkungen

Bei Datenübertragungsvorgängen ist ein Puffer mit der Ausrichtung des Adaptergeräts erforderlich. Anwendungen können das Geräteausrichtungsformat abrufen, indem sie eine IOCTL_STORAGE_QUERY_PROPERTY Steuerelementcodeanforderung mit einem Abfragetyp von PropertyStandardQuery und Eigenschafts-ID von StorageAdapterPropertyausgibt. Das Ausrichtungsformat befindet sich im AlignmentMask Element der zurückgegebenen STORAGE_ADAPTER_DESCRIPTOR Struktur. Treiber können auch den Wert im AlignmentMask Member des DeviceObject-des Adapters verwenden.

In der folgenden Beispielfunktion wird ein Puffer als Geräteauslöser für die Datenübertragung vorbereitet.


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;
}

Um eine IOCTL_SCSI_PASS_THROUGH_DIRECT_EX Anforderung ausstellen zu können, muss das zugrunde liegende Speichergerät erweiterte SRBs unterstützen. Dies bedeutet, dass der unterstützte SRB-Typ SRB_TYPE_STORAGE_REQUEST_BLOCKist. Eine Anwendung kann die SRB-Unterstützung mit der IOCTL_STORAGE_QUERY_PROPERTY-Anforderung mit einem Abfragetyp von PropertyStandardQuery- und einem Eigenschaftstyp von StorageDevicePropertyabfragen. Das in der STORAGE_ADAPTER_DESCRIPTIOR Struktur zurückgegebene SrbType-Element gibt entweder SRB_TYPE_SCSI_REQUEST_BLOCK oder SRB_TYPE_STORAGE_REQUEST_BLOCKan.

Anforderungen

Anforderung	Wert
Header-	ntddscsi.h (include Ntddscsi.h)

Siehe auch

IOCTL_SCSI_PASS_THROUGH_EX

IOCTL_STORAGE_QUERY_PROPERTY

SCSI_PASS_THROUGH_DIRECT_EX

Freigeben über