структура IO_STACK_LOCATION (wdm.h)

Статья
09/20/2023

Структура IO_STACK_LOCATION определяет расположение стека ввода-вывода , которое является записью в стеке ввода-вывода, связанном с каждым IRP. Каждое расположение стека ввода-вывода в IRP содержит некоторые общие элементы и некоторые члены типа запроса.

Синтаксис

typedef struct _IO_STACK_LOCATION {
  UCHAR                  MajorFunction;
  UCHAR                  MinorFunction;
  UCHAR                  Flags;
  UCHAR                  Control;
  union {
    struct {
      PIO_SECURITY_CONTEXT     SecurityContext;
      ULONG                    Options;
      USHORT POINTER_ALIGNMENT FileAttributes;
      USHORT                   ShareAccess;
      ULONG POINTER_ALIGNMENT  EaLength;
    } Create;
    struct {
      PIO_SECURITY_CONTEXT          SecurityContext;
      ULONG                         Options;
      USHORT POINTER_ALIGNMENT      Reserved;
      USHORT                        ShareAccess;
      PNAMED_PIPE_CREATE_PARAMETERS Parameters;
    } CreatePipe;
    struct {
      PIO_SECURITY_CONTEXT        SecurityContext;
      ULONG                       Options;
      USHORT POINTER_ALIGNMENT    Reserved;
      USHORT                      ShareAccess;
      PMAILSLOT_CREATE_PARAMETERS Parameters;
    } CreateMailslot;
    struct {
      ULONG                   Length;
      ULONG POINTER_ALIGNMENT Key;
      ULONG                   Flags;
      LARGE_INTEGER           ByteOffset;
    } Read;
    struct {
      ULONG                   Length;
      ULONG POINTER_ALIGNMENT Key;
      ULONG                   Flags;
      LARGE_INTEGER           ByteOffset;
    } Write;
    struct {
      ULONG                   Length;
      PUNICODE_STRING         FileName;
      FILE_INFORMATION_CLASS  FileInformationClass;
      ULONG POINTER_ALIGNMENT FileIndex;
    } QueryDirectory;
    struct {
      ULONG                   Length;
      ULONG POINTER_ALIGNMENT CompletionFilter;
    } NotifyDirectory;
    struct {
      ULONG                                                Length;
      ULONG POINTER_ALIGNMENT                              CompletionFilter;
      DIRECTORY_NOTIFY_INFORMATION_CLASS POINTER_ALIGNMENT DirectoryNotifyInformationClass;
    } NotifyDirectoryEx;
    struct {
      ULONG                                    Length;
      FILE_INFORMATION_CLASS POINTER_ALIGNMENT FileInformationClass;
    } QueryFile;
    struct {
      ULONG                                    Length;
      FILE_INFORMATION_CLASS POINTER_ALIGNMENT FileInformationClass;
      PFILE_OBJECT                             FileObject;
      union {
        struct {
          BOOLEAN ReplaceIfExists;
          BOOLEAN AdvanceOnly;
        };
        ULONG  ClusterCount;
        HANDLE DeleteHandle;
      };
    } SetFile;
    struct {
      ULONG                   Length;
      PVOID                   EaList;
      ULONG                   EaListLength;
      ULONG POINTER_ALIGNMENT EaIndex;
    } QueryEa;
    struct {
      ULONG Length;
    } SetEa;
    struct {
      ULONG                                  Length;
      FS_INFORMATION_CLASS POINTER_ALIGNMENT FsInformationClass;
    } QueryVolume;
    struct {
      ULONG                                  Length;
      FS_INFORMATION_CLASS POINTER_ALIGNMENT FsInformationClass;
    } SetVolume;
    struct {
      ULONG                   OutputBufferLength;
      ULONG POINTER_ALIGNMENT InputBufferLength;
      ULONG POINTER_ALIGNMENT FsControlCode;
      PVOID                   Type3InputBuffer;
    } FileSystemControl;
    struct {
      PLARGE_INTEGER          Length;
      ULONG POINTER_ALIGNMENT Key;
      LARGE_INTEGER           ByteOffset;
    } LockControl;
    struct {
      ULONG                   OutputBufferLength;
      ULONG POINTER_ALIGNMENT InputBufferLength;
      ULONG POINTER_ALIGNMENT IoControlCode;
      PVOID                   Type3InputBuffer;
    } DeviceIoControl;
    struct {
      SECURITY_INFORMATION    SecurityInformation;
      ULONG POINTER_ALIGNMENT Length;
    } QuerySecurity;
    struct {
      SECURITY_INFORMATION SecurityInformation;
      PSECURITY_DESCRIPTOR SecurityDescriptor;
    } SetSecurity;
    struct {
      PVPB           Vpb;
      PDEVICE_OBJECT DeviceObject;
      ULONG          OutputBufferLength;
    } MountVolume;
    struct {
      PVPB           Vpb;
      PDEVICE_OBJECT DeviceObject;
    } VerifyVolume;
    struct {
      struct _SCSI_REQUEST_BLOCK *Srb;
    } Scsi;
    struct {
      ULONG                       Length;
      PSID                        StartSid;
      PFILE_GET_QUOTA_INFORMATION SidList;
      ULONG                       SidListLength;
    } QueryQuota;
    struct {
      ULONG Length;
    } SetQuota;
    struct {
      DEVICE_RELATION_TYPE Type;
    } QueryDeviceRelations;
    struct {
      const GUID *InterfaceType;
      USHORT     Size;
      USHORT     Version;
      PINTERFACE Interface;
      PVOID      InterfaceSpecificData;
    } QueryInterface;
    struct {
      PDEVICE_CAPABILITIES Capabilities;
    } DeviceCapabilities;
    struct {
      PIO_RESOURCE_REQUIREMENTS_LIST IoResourceRequirementList;
    } FilterResourceRequirements;
    struct {
      ULONG                   WhichSpace;
      PVOID                   Buffer;
      ULONG                   Offset;
      ULONG POINTER_ALIGNMENT Length;
    } ReadWriteConfig;
    struct {
      BOOLEAN Lock;
    } SetLock;
    struct {
      BUS_QUERY_ID_TYPE IdType;
    } QueryId;
    struct {
      DEVICE_TEXT_TYPE       DeviceTextType;
      LCID POINTER_ALIGNMENT LocaleId;
    } QueryDeviceText;
    struct {
      BOOLEAN                                          InPath;
      BOOLEAN                                          Reserved[3];
      DEVICE_USAGE_NOTIFICATION_TYPE POINTER_ALIGNMENT Type;
    } UsageNotification;
    struct {
      SYSTEM_POWER_STATE PowerState;
    } WaitWake;
    struct {
      PPOWER_SEQUENCE PowerSequence;
    } PowerSequence;
#if ...
    struct {
      union {
        ULONG                      SystemContext;
        SYSTEM_POWER_STATE_CONTEXT SystemPowerStateContext;
      };
      POWER_STATE_TYPE POINTER_ALIGNMENT Type;
      POWER_STATE POINTER_ALIGNMENT      State;
      POWER_ACTION POINTER_ALIGNMENT     ShutdownType;
    } Power;
#else
    struct {
      ULONG                              SystemContext;
      POWER_STATE_TYPE POINTER_ALIGNMENT Type;
      POWER_STATE POINTER_ALIGNMENT      State;
      POWER_ACTION POINTER_ALIGNMENT     ShutdownType;
    } Power;
#endif
    struct {
      PCM_RESOURCE_LIST AllocatedResources;
      PCM_RESOURCE_LIST AllocatedResourcesTranslated;
    } StartDevice;
    struct {
      ULONG_PTR ProviderId;
      PVOID     DataPath;
      ULONG     BufferSize;
      PVOID     Buffer;
    } WMI;
    struct {
      PVOID Argument1;
      PVOID Argument2;
      PVOID Argument3;
      PVOID Argument4;
    } Others;
  } Parameters;
  PDEVICE_OBJECT         DeviceObject;
  PFILE_OBJECT           FileObject;
  PIO_COMPLETION_ROUTINE CompletionRoutine;
  PVOID                  Context;
} IO_STACK_LOCATION, *PIO_STACK_LOCATION;

Члены

MajorFunction

Код основной функции IRP , указывающий тип выполняемой операции ввода-вывода.

MinorFunction

Код подфункции для MajorFunction. Диспетчер PnP, диспетчер питания, драйверы файловой системы и драйверы классов SCSI задают этот элемент для некоторых запросов.

Flags

Значения типа запроса, используемые почти исключительно драйверами файловой системы. Драйверы устройств с съемным носителем проверяют, задан ли этот элемент SL_OVERRIDE_VERIFY_VOLUME для запросов на чтение, чтобы определить, следует ли продолжать операцию чтения, даже если флагов объекта устройства заданы DO_VERIFY_VOLUME. Промежуточные драйверы, наложенные на драйвер устройства с съемным носителем, должны скопировать этот элемент в расположение стека ввода-вывода следующего драйвера во всех входящих запросах IRP_MJ_READ.

Документация по другим флагам для IRP_MJ_CREATE см. вIRP_MJ_CREATE (IFS).

Возможные значения флага:

Флаг	Ценность	Описание
SL_KEY_SPECIFIED	`0x01`	Указывает, что `IO_STACK_LOCATION.Parameters.Read(OrWrite).Key` содержит копию данного сектора, которую следует считывать при включении избыточности. Сегодня этот флаг используется только с операциями IRP_MJ_READ.
SL_OVERRIDE_VERIFY_VOLUME	`0x02`	Этот флаг используется для определения того, следует ли продолжать операцию чтения, даже если флагов объекта устройства заданы DO_VERIFY_VOLUME.
SL_WRITE_THROUGH	`0x04`	Этот флаг сообщает драйверу хранилища установить соответствующие флаги, чтобы диск переместит кэш записи, чтобы заставить диск записывать данные на постоянный носитель хранилища. Этот флаг предназначен для устройства; не все диски поддерживают обход кэша дисков.
SL_FT_SEQUENTIAL_WRITE	`0x08`	Зарезервировано для использования системы.
SL_FORCE_DIRECT_WRITE	`0x10`	Этот флаг позволяет драйверам режима ядра записывать данные в области томов, в которые они обычно не могут записываться из-за блокировки прямой записи в файловой системе и стеке драйверов хранилища. Прямая блокировка записи помогает повысить безопасность. Этот флаг проверяется как на уровне файловой системы, так и на уровне стека хранилища. Дополнительные сведения о прямой блокировке записи см. в разделе Блокировка прямых операций записи в томах и дисках.
SL_REALTIME_STREAM	`0x20`	Этот флаг указывает, что ввод-вывод предназначен для потоковой передачи запросов в режиме реального времени на драйвер класса CD-ROM. Это указывает драйверу выполнять операции READ/WRITE с гарантированной скоростью потоковой передачи в режиме реального времени. этот флаг действителен только с оптическим носителем.
SL_PERSISTENT_MEMORY_FIXED_MAPPING	`0x20`	Сопоставление сохраняемой памяти байтов в запросе записи не может измениться при обработке этого запроса на запись. Этот флаг действителен только с устройством постоянной памяти и IRP_MJ_WRITE.

Для устройств постоянной памяти одна из причин повторного сопоставления (изменение физического адреса заданного LBA) на устройствах постоянной памяти заключается в том, чтобы обеспечить эффективную атомарность уровня сектора. Если флаг не задан, повторное перемысливание допускается, особенно если он приводит к тому, что драйвер обеспечивает атомарность сектора. Файловые системы (или запрашивающий) предпочитают, чтобы драйвер устройства постоянной памяти предоставлял атомарность сектора. Если флаг задан, драйвер постоянной памяти не должен переназначить физические адреса, соответствующие LBAs. Если это означает, что атомарность сектора не может быть предоставлена, так быть. Тем не менее, драйвер более чем приветствуется обеспечить атомарность сектора до тех пор, пока нет перемездки.

Control

Драйверы могут проверить этот элемент, чтобы определить, задано ли оно SL_PENDING_RETURNED и в каких условиях вызывается CompletionRoutine. Драйверы имеют доступ только для чтения к этому члену. Драйверы вызывают IoSetCompletionRoutine или IoSetCompletionRoutineEx, чтобы указать эти условия.

Parameters

Объединение, которое зависит от основных и незначительных значений кода функции IRP, содержащихся в MajorFunction и MinorFunction. В следующей таблице показано, какие ИРВ используют отдельные члены объединения параметров .

Имя участника	IRPs, которые используют этот элемент
создание	IRP_MJ_CREATE
чтения	IRP_MJ_READ
записи	IRP_MJ_WRITE
QueryFile	IRP_MJ_QUERY_INFORMATION
SetFile	IRP_MJ_SET_INFORMATION
QueryVolume	IRP_MJ_QUERY_VOLUME_INFORMATION
DeviceIoControl	IRP_MJ_DEVICE_CONTROL и IRP_MJ_INTERNAL_DEVICE_CONTROL
MountVolume	IRP_MN_MOUNT_VOLUME
VerifyVolume	IRP_MN_VERIFY_VOLUME
Scsi	IRP_MJ_INTERNAL_DEVICE_CONTROL (SCSI)
QueryDeviceRelations	IRP_MN_QUERY_DEVICE_RELATIONS
QueryInterface	IRP_MN_QUERY_INTERFACE
DeviceCapabilities	IRP_MN_QUERY_CAPABILITIES
FilterResourceRequirements	IRP_MN_FILTER_RESOURCE_REQUIREMENTS
ReadWriteConfig	IRP_MN_READ_CONFIG и IRP_MN_WRITE_CONFIG
SetLock	IRP_MN_SET_LOCK
QueryId	IRP_MN_QUERY_ID
QueryDeviceText	IRP_MN_QUERY_DEVICE_TEXT
UsageNotification	IRP_MN_DEVICE_USAGE_NOTIFICATION
WaitWake	IRP_MN_WAIT_WAKE
PowerSequence	IRP_MN_POWER_SEQUENCE
Power	IRP_MN_SET_POWER и IRP_MN_QUERY_POWER
StartDevice	IRP_MN_START_DEVICE
WMI	дополнительных WMI
другие	Ip-адреса irps для конкретного драйвера

Дополнительные сведения см. в основных кодов функций IRP.

Parameters.Create

Параметры системной службы для NtCreateFile.

Parameters.Create.SecurityContext

Parameters.Create.Options

Parameters.Create.FileAttributes

Parameters.Create.ShareAccess

Parameters.Create.EaLength

Parameters.CreatePipe

Параметры системной службы NtCreateNamedPipeFile.

Parameters.CreatePipe.SecurityContext

Parameters.CreatePipe.Options

Parameters.CreatePipe.Reserved

Parameters.CreatePipe.ShareAccess

Parameters.CreatePipe.Parameters

Parameters.CreateMailslot

Параметры системной службы для NtCreateMailslotFile.

Parameters.CreateMailslot.SecurityContext

Parameters.CreateMailslot.Options

Parameters.CreateMailslot.Reserved

Parameters.CreateMailslot.ShareAccess

Parameters.CreateMailslot.Parameters

Parameters.Read

Параметры системной службы для NtReadFile.

Parameters.Read.Length

Parameters.Read.Key

Parameters.Read.Flags

Parameters.Read.ByteOffset

Parameters.Write

Параметры системной службы для NtWriteFile.

Parameters.Write.Length

Parameters.Write.Key

Parameters.Write.Flags

Parameters.Write.ByteOffset

Parameters.QueryDirectory

Параметры системной службы для NtQueryDirectoryFile.

Parameters.QueryDirectory.Length

Parameters.QueryDirectory.FileName

Parameters.QueryDirectory.FileInformationClass

Parameters.QueryDirectory.FileIndex

Parameters.NotifyDirectory

Параметры системной службы для NtNotifyChangeDirectoryFile.

Parameters.NotifyDirectory.Length

Parameters.NotifyDirectory.CompletionFilter

Parameters.NotifyDirectoryEx

Параметры системной службы для NtNotifyChangeDirectoryFileEx.

Parameters.NotifyDirectoryEx.Length

Parameters.NotifyDirectoryEx.CompletionFilter

Parameters.NotifyDirectoryEx.DirectoryNotifyInformationClass

Parameters.QueryFile

Параметры системной службы для NtQueryInformationFile.

Parameters.QueryFile.Length

Parameters.QueryFile.FileInformationClass

Parameters.SetFile

Параметры системной службы для NtSetInformationFile.

Parameters.SetFile.Length

Parameters.SetFile.FileInformationClass

Parameters.SetFile.FileObject

Parameters.SetFile.ReplaceIfExists

Parameters.SetFile.AdvanceOnly

Parameters.SetFile.ClusterCount

Parameters.SetFile.DeleteHandle

Parameters.QueryEa

Параметры системной службы для NtQueryEaFile.

Parameters.QueryEa.Length

Parameters.QueryEa.EaList

Parameters.QueryEa.EaListLength

Parameters.QueryEa.EaIndex

Parameters.SetEa

Параметры системной службы для NtSetEaFile.

Parameters.SetEa.Length

Parameters.QueryVolume

Параметры системной службы для NtQueryVolumeInformationFile.

Parameters.QueryVolume.Length

Parameters.QueryVolume.FsInformationClass

Parameters.SetVolume

Параметры системной службы для NtSetVolumeInformationFile.

Parameters.SetVolume.Length

Parameters.SetVolume.FsInformationClass

Parameters.FileSystemControl

Параметры системной службы для NtFsControlFile.

Parameters.FileSystemControl.OutputBufferLength

Parameters.FileSystemControl.InputBufferLength

Parameters.FileSystemControl.FsControlCode

Parameters.FileSystemControl.Type3InputBuffer

Parameters.LockControl

Параметры системной службы для LockFile/NtUnlockFile.

Parameters.LockControl.Length

Parameters.LockControl.Key

Parameters.LockControl.ByteOffset

Parameters.DeviceIoControl

Параметры системной службы для NtDeviceIoControlFile.

Parameters.DeviceIoControl.OutputBufferLength

Parameters.DeviceIoControl.InputBufferLength

Parameters.DeviceIoControl.IoControlCode

Parameters.DeviceIoControl.Type3InputBuffer

Parameters.QuerySecurity

Параметры системной службы для NtQuerySecurityObject.

Parameters.QuerySecurity.SecurityInformation

Parameters.QuerySecurity.Length

Parameters.SetSecurity

Параметры системной службы для NtSetSecurityObject.

Parameters.SetSecurity.SecurityInformation

Parameters.SetSecurity.SecurityDescriptor

Parameters.MountVolume

Параметры системной службы для MountVolume.

Parameters.MountVolume.Vpb

Parameters.MountVolume.DeviceObject

Parameters.MountVolume.OutputBufferLength

Parameters.VerifyVolume

Параметры системной службы для VerifyVolume.

Parameters.VerifyVolume.Vpb

Parameters.VerifyVolume.DeviceObject

Parameters.Scsi

Параметры для SCSI с внутренним элементом управления устройствами.

Parameters.Scsi.Srb

Parameters.QueryQuota

Параметры системной службы для NtQueryQuotaInformationFile.

Parameters.QueryQuota.Length

Parameters.QueryQuota.StartSid

Parameters.QueryQuota.SidList

Parameters.QueryQuota.SidListLength

Parameters.SetQuota

Параметры системной службы для NtSetQuotaInformationFile.

Parameters.SetQuota.Length

Parameters.QueryDeviceRelations

Параметры для IRP_MN_QUERY_DEVICE_RELATIONS.

Parameters.QueryDeviceRelations.Type

Parameters.QueryInterface

Параметры для IRP_MN_QUERY_INTERFACE.

Parameters.QueryInterface.InterfaceType

Parameters.QueryInterface.Size

Parameters.QueryInterface.Version

Parameters.QueryInterface.Interface

Parameters.QueryInterface.InterfaceSpecificData

Parameters.DeviceCapabilities

Параметры для IRP_MN_QUERY_CAPABILITIES.

Parameters.DeviceCapabilities.Capabilities

Parameters.FilterResourceRequirements

Параметры для IRP_MN_FILTER_RESOURCE_REQUIREMENTS.

Parameters.FilterResourceRequirements.IoResourceRequirementList

Parameters.ReadWriteConfig

Параметры для IRP_MN_READ_CONFIG и IRP_MN_WRITE_CONFIG.

Parameters.ReadWriteConfig.WhichSpace

Parameters.ReadWriteConfig.Buffer

Parameters.ReadWriteConfig.Offset

Parameters.ReadWriteConfig.Length

Parameters.SetLock

Параметры для IRP_MN_SET_LOCK.

Parameters.SetLock.Lock

Parameters.QueryId

Параметры для IRP_MN_QUERY_ID.

Parameters.QueryId.IdType

Parameters.QueryDeviceText

Параметры для IRP_MN_QUERY_DEVICE_TEXT.

Parameters.QueryDeviceText.DeviceTextType

Parameters.QueryDeviceText.LocaleId

Parameters.UsageNotification

Параметры для IRP_MN_DEVICE_USAGE_NOTIFICATION.

Parameters.UsageNotification.InPath

Parameters.UsageNotification.Reserved[3]

Parameters.UsageNotification.Type

Parameters.WaitWake

Параметры для IRP_MN_WAIT_WAKE.

Parameters.WaitWake.PowerState

Parameters.PowerSequence

Параметр для IRP_MN_POWER_SEQUENCE.

Parameters.PowerSequence.PowerSequence

Parameters.Power

Параметры для IRP_MN_SET_POWER и IRP_MN_QUERY_POWER.

Parameters.Power.SystemContext

Parameters.Power.SystemPowerStateContext

Parameters.Power.Type

Parameters.Power.State

Parameters.Power.ShutdownType

Parameters.StartDevice

Параметры для StartDevice.

Parameters.StartDevice.AllocatedResources

Parameters.StartDevice.AllocatedResourcesTranslated

Parameters.WMI

Параметры для WMI IRP.

Parameters.WMI.ProviderId

Parameters.WMI.DataPath

Parameters.WMI.BufferSize

Parameters.WMI.Buffer

Parameters.Others

Параметры для других операций, относящихся к драйверу.

Parameters.Others.Argument1

Parameters.Others.Argument2

Parameters.Others.Argument3

Parameters.Others.Argument4

DeviceObject

Указатель на созданную драйвером DEVICE_OBJECT структуру, представляющую целевое физическое, логическое или виртуальное устройство, для которого этот драйвер должен обрабатывать IRP.

FileObject

Указатель на структуру FILE_OBJECT, представляющую объект файла( если таковой есть), связанный с указателем DeviceObject.

CompletionRoutine

Подпрограмма завершения, вызываемая в зависимости от флагов в поле элемента управления этой структуры.

Context

Определяемый драйвером контекст, используемый для хранения адреса параметра контекста, передаваемого в CompletionRoutine.

Замечания

Для каждого IRP существует одна структура IO_STACK_LOCATION для каждого драйвера в стеке драйверов. Каждый набор расположений стека операций ввода-вывода добавляется в IRP после структуры IRP.

Каждый драйвер более высокого уровня отвечает за настройку расположения стека ввода-вывода для следующего ниже драйвера в каждом IRP. Драйвер должен вызвать IoGetCurrentIrpStackLocation, чтобы получить указатель на собственное расположение стека для каждого IRP. Драйверы более высокого уровня могут вызывать IoGetNextIrpStackLocation, чтобы получить указатель на расположение стека следующего ниже драйвера.

Драйвер более высокого уровня должен настроить содержимое расположения стека перед вызовом IoCallDriver, чтобы передать IRP драйверу нижнего уровня. Если драйвер передает входной IRP на следующий драйвер нижнего уровня, подпрограмма отправки должна вызвать IoSkipCurrentIrpStackLocation или IoCopyCurrentIrpStackLocationToNext, чтобы настроить расположение стека ввода-вывода следующего драйвера.

Вызов драйвера более высокого уровня для IoCallDriver задает элемент DeviceObject для целевого объекта устройства драйвера следующего нижнего уровня в расположении стека ввода-вывода нижнего драйвера. Диспетчер ввода-вывода передает каждому драйверу более высокого уровня IoCompletion подпрограмму указателя на собственный объект устройства, когда подпрограмма IoCompletion вызывается при завершении IRP.

Если драйвер более высокого уровня выделяет irPs для выполнения запросов самостоятельно, его подпрограмма IoCompletion передается NULLDeviceObject указателем, если этот драйвер не выделяет расположение стека для себя, а также задает указатель DeviceObject в собственном расположении стека выделенного IRP.

В некоторых случаях драйвер более высокого уровня, наложенный на драйвер устройства массового хранения, отвечает за разделение больших запросов передачи для базового драйвера устройства. В частности, драйверы классов SCSI должны проверять Parameters.Read.Length и Parameters.Write.Length, определить, превышает ли размер запрошенной передачи базовые возможности передачи HBA и, если да, разделите длину исходного запроса на последовательность частичных передач для удовлетворения исходного IRP.