IO_STACK_LOCATION - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
// wdm.h

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;
View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Edit description on GitHub

Windows Driver Kit DDI reference (ns-wdm-_io_stack_location)

Description

The IO_STACK_LOCATION structure defines an I/O stack location, which is an entry in the I/O stack that is associated with each IRP. Each I/O stack location in an IRP has some common members and some request-type-specific members.

Members

MajorFunction

The IRP major function code indicating the type of I/O operation to be performed.

MinorFunction

A subfunction code for MajorFunction. The PnP manager, the power manager, file system drivers, and SCSI class drivers set this member for some requests.

Flags

Request-type-specific values used almost exclusively by file system drivers. Removable-media device drivers check whether this member is set with SL_OVERRIDE_VERIFY_VOLUME for read requests to determine whether to continue the read operation even if the device object's Flags is set with DO_VERIFY_VOLUME. Intermediate drivers layered over a removable-media device driver must copy this member into the I/O stack location of the next-lower driver in all incoming IRP_MJ_READ requests.

For documentation of other SL_* flags for IRP_MJ_CREATE, see IRP_MJ_CREATE (IFS).

Possible flag values include:

Flag Value Description
SL_KEY_SPECIFIED 0x01 Indicates that the IO_STACK_LOCATION.Parameters.Read(OrWrite).Key contains which copy of a given sector should be read when redundancy is enabled. Today this flag is use only with IRP_MJ_READ operations.
SL_OVERRIDE_VERIFY_VOLUME 0x02 This flag is used to determine whether to continue the read operation even if the device object's Flags is set with DO_VERIFY_VOLUME.
SL_WRITE_THROUGH 0x04 This flag informs the storage driver to set appropriate flags so that the disk bypasses the write cache in order to force the disk to write through to its persistent storage media. This flag is device-specific; not all disk drives support bypassing disk-cache.
SL_FT_SEQUENTIAL_WRITE 0x08 Reserved for system use.
SL_FORCE_DIRECT_WRITE 0x10 This flag lets kernel-mode drivers write to volume areas that they normally cannot write to because of blocking direct write in the file system and storage driver stack. Direct write blocking helps improve security. This flag is checked both at the file system layer and storage stack layer. For more information about direct write blocking, see Blocking Direct Write Operations to Volumes and Disks.
SL_REALTIME_STREAM 0x20 This flag hints that the IO is for real-time streaming requests to a CD-ROM class driver. This hints the driver to perform READ/WRITE operations at a guaranteed speed for real-time streaming. This flag is valid only with optical media.
SL_PERSISTENT_MEMORY_FIXED_MAPPING 0x20 The persistent memory mapping of the bytes in the write request cannot change while handling this write request. This flag is valid only with a persistent memory device and IRP_MJ_WRITE.

For persistent memory devices, one of the reasons for remapping (modifying the physical address of a given LBA) on persistent memory devices is to provide efficient sector level atomicity. If the flag is not set, remapping is allowed especially if it results in the driver providing sector atomicity. File systems (or the requester) prefer that a persistent memory device driver provides sector atomicity. If the flag is set, a persistent memory driver shall not remap the physical addresses corresponding to the LBAs. If that means sector atomicity can't be provided, so be it. However, the driver is more than welcome to provide sector atomicity as long as there is no remapping.

Control

Drivers can check this member to determine whether it is set with SL_PENDING_RETURNED and under what conditions the CompletionRoutine is called. Drivers have read-only access to this member. Drivers call IoSetCompletionRoutine or IoSetCompletionRoutineEx to specify these conditions.

Parameters

A union that depends on the major and minor IRP function code values contained in MajorFunction and MinorFunction. The following table shows which IRPs use the individual members of the Parameters union.

Member name IRPs that use this member
Create IRP_MJ_CREATE
Read IRP_MJ_READ
Write IRP_MJ_WRITE
QueryFile IRP_MJ_QUERY_INFORMATION
SetFile IRP_MJ_SET_INFORMATION
QueryVolume IRP_MJ_QUERY_VOLUME_INFORMATION
DeviceIoControl IRP_MJ_DEVICE_CONTROL and 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 and 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 and IRP_MN_QUERY_POWER
StartDevice IRP_MN_START_DEVICE
WMI WMI minor IRPs
Others Driver-specific IRPs

For more information, see IRP Major Function Codes.

Parameters.Create

System service parameters for NtCreateFile.

Parameters.Create.SecurityContext

Parameters.Create.Options

Parameters.Create.FileAttributes

Parameters.Create.ShareAccess

Parameters.Create.EaLength

Parameters.CreatePipe

System service parameters fo NtCreateNamedPipeFile.

Parameters.CreatePipe.SecurityContext

Parameters.CreatePipe.Options

Parameters.CreatePipe.Reserved

Parameters.CreatePipe.ShareAccess

Parameters.CreatePipe.Parameters

Parameters.CreateMailslot

System service parameters for NtCreateMailslotFile.

Parameters.CreateMailslot.SecurityContext

Parameters.CreateMailslot.Options

Parameters.CreateMailslot.Reserved

Parameters.CreateMailslot.ShareAccess

Parameters.CreateMailslot.Parameters

Parameters.Read

System service parameters for NtReadFile.

Parameters.Read.Length

Parameters.Read.Key

Parameters.Read.Flags

Parameters.Read.ByteOffset

Parameters.Write

System service parameters for NtWriteFile.

Parameters.Write.Length

Parameters.Write.Key

Parameters.Write.Flags

Parameters.Write.ByteOffset

Parameters.QueryDirectory

System service parameters for NtQueryDirectoryFile.

Parameters.QueryDirectory.Length

Parameters.QueryDirectory.FileName

Parameters.QueryDirectory.FileInformationClass

Parameters.QueryDirectory.FileIndex

Parameters.NotifyDirectory

System service parameters for NtNotifyChangeDirectoryFile.

Parameters.NotifyDirectory.Length

Parameters.NotifyDirectory.CompletionFilter

Parameters.NotifyDirectoryEx

System service parameters for NtNotifyChangeDirectoryFileEx.

Parameters.NotifyDirectoryEx.Length

Parameters.NotifyDirectoryEx.CompletionFilter

Parameters.NotifyDirectoryEx.DirectoryNotifyInformationClass

Parameters.QueryFile

System service parameters for NtQueryInformationFile.

Parameters.QueryFile.Length

Parameters.QueryFile.FileInformationClass

Parameters.SetFile

System service parameters for NtSetInformationFile.

Parameters.SetFile.Length

Parameters.SetFile.FileInformationClass

Parameters.SetFile.FileObject

Parameters.SetFile.ReplaceIfExists

Parameters.SetFile.AdvanceOnly

Parameters.SetFile.ClusterCount

Parameters.SetFile.DeleteHandle

Parameters.QueryEa

System service parameters for NtQueryEaFile.

Parameters.QueryEa.Length

Parameters.QueryEa.EaList

Parameters.QueryEa.EaListLength

Parameters.QueryEa.EaIndex

Parameters.SetEa

System service parameters for NtSetEaFile.

Parameters.SetEa.Length

Parameters.QueryVolume

System service parameters for NtQueryVolumeInformationFile.

Parameters.QueryVolume.Length

Parameters.QueryVolume.FsInformationClass

Parameters.SetVolume

System service parameters for NtSetVolumeInformationFile.

Parameters.SetVolume.Length

Parameters.SetVolume.FsInformationClass

Parameters.FileSystemControl

System service parameters for NtFsControlFile.

Parameters.FileSystemControl.OutputBufferLength

Parameters.FileSystemControl.InputBufferLength

Parameters.FileSystemControl.FsControlCode

Parameters.FileSystemControl.Type3InputBuffer

Parameters.LockControl

System service parameters for LockFile/NtUnlockFile.

Parameters.LockControl.Length

Parameters.LockControl.Key

Parameters.LockControl.ByteOffset

Parameters.DeviceIoControl

System service parameters for NtDeviceIoControlFile.

Parameters.DeviceIoControl.OutputBufferLength

Parameters.DeviceIoControl.InputBufferLength

Parameters.DeviceIoControl.IoControlCode

Parameters.DeviceIoControl.Type3InputBuffer

Parameters.QuerySecurity

System service parameters for NtQuerySecurityObject.

Parameters.QuerySecurity.SecurityInformation

Parameters.QuerySecurity.Length

Parameters.SetSecurity

System service parameters for NtSetSecurityObject.

Parameters.SetSecurity.SecurityInformation

Parameters.SetSecurity.SecurityDescriptor

Parameters.MountVolume

System service parameters for MountVolume.

Parameters.MountVolume.Vpb

Parameters.MountVolume.DeviceObject

Parameters.MountVolume.OutputBufferLength

Parameters.VerifyVolume

System service parameters for VerifyVolume.

Parameters.VerifyVolume.Vpb

Parameters.VerifyVolume.DeviceObject

Parameters.Scsi

Parameters for Scsi with internal device control.

Parameters.Scsi.Srb

Parameters.QueryQuota

System service parameters for NtQueryQuotaInformationFile.

Parameters.QueryQuota.Length

Parameters.QueryQuota.StartSid

Parameters.QueryQuota.SidList

Parameters.QueryQuota.SidListLength

Parameters.SetQuota

System service parameters for NtSetQuotaInformationFile.

Parameters.SetQuota.Length

Parameters.QueryDeviceRelations

Parameters for IRP_MN_QUERY_DEVICE_RELATIONS.

Parameters.QueryDeviceRelations.Type

Parameters.QueryInterface

Parameters for IRP_MN_QUERY_INTERFACE.

Parameters.QueryInterface.InterfaceType

Parameters.QueryInterface.Size

Parameters.QueryInterface.Version

Parameters.QueryInterface.Interface

Parameters.QueryInterface.InterfaceSpecificData

Parameters.DeviceCapabilities

Parameters for IRP_MN_QUERY_CAPABILITIES.

Parameters.DeviceCapabilities.Capabilities

Parameters.FilterResourceRequirements

Parameters for IRP_MN_FILTER_RESOURCE_REQUIREMENTS.

Parameters.FilterResourceRequirements.IoResourceRequirementList

Parameters.ReadWriteConfig

Parameters for IRP_MN_READ_CONFIG and IRP_MN_WRITE_CONFIG.

Parameters.ReadWriteConfig.WhichSpace

Parameters.ReadWriteConfig.Buffer

Parameters.ReadWriteConfig.Offset

Parameters.ReadWriteConfig.Length

Parameters.SetLock

Parameters for IRP_MN_SET_LOCK.

Parameters.SetLock.Lock

Parameters.QueryId

Parameters for IRP_MN_QUERY_ID.

Parameters.QueryId.IdType

Parameters.QueryDeviceText

Parameters for IRP_MN_QUERY_DEVICE_TEXT.

Parameters.QueryDeviceText.DeviceTextType

Parameters.QueryDeviceText.LocaleId

Parameters.UsageNotification

Parameters for IRP_MN_DEVICE_USAGE_NOTIFICATION.

Parameters.UsageNotification.InPath

Parameters.UsageNotification.Reserved[3]

Parameters.UsageNotification.Type

Parameters.WaitWake

Parameters for IRP_MN_WAIT_WAKE.

Parameters.WaitWake.PowerState

Parameters.PowerSequence

Parameter for IRP_MN_POWER_SEQUENCE.

Parameters.PowerSequence.PowerSequence

Parameters.Power.SystemPowerStateContext

Parameters.Power

Parameters for IRP_MN_SET_POWER and IRP_MN_QUERY_POWER.

Parameters.Power.SystemContext

Parameters.Power.Type

Parameters.Power.State

Parameters.Power.ShutdownType

Parameters.StartDevice

Parameters for StartDevice.

Parameters.StartDevice.AllocatedResources

Parameters.StartDevice.AllocatedResourcesTranslated

Parameters.WMI

Parameters for WMI IRPs.

Parameters.WMI.ProviderId

Parameters.WMI.DataPath

Parameters.WMI.BufferSize

Parameters.WMI.Buffer

Parameters.Others

Parameters for other driver-specific operations.

Parameters.Others.Argument1

Parameters.Others.Argument2

Parameters.Others.Argument3

Parameters.Others.Argument4

DeviceObject

A pointer to the driver-created DEVICE_OBJECT structure representing the target physical, logical, or virtual device for which this driver is to handle the IRP.

FileObject

A pointer to a FILE_OBJECT structure that represents the file object, if any, that is associated with DeviceObject pointer.

CompletionRoutine

The completion routine that is invoked depending on the flags in the Control field of this structure.

Context

Driver-defined context that is used to store the address of the context parameter that is passed to the CompletionRoutine.

Remarks

For each IRP, there is one IO_STACK_LOCATION structure for each driver in a driver stack. Each IRP's set of I/O stack locations is appended to the IRP, following the IRP structure.

Every higher-level driver is responsible for setting up the I/O stack location for the next-lower driver in each IRP. A driver must call IoGetCurrentIrpStackLocation to get a pointer to its own stack location for each IRP. Higher-level drivers can call IoGetNextIrpStackLocation to get a pointer to the next-lower driver's stack location.

The higher-level driver must set up the stack location contents before calling IoCallDriver to pass an IRP to the lower-level driver. If the driver will pass the input IRP on to the next lower-level driver, the dispatch routine should call IoSkipCurrentIrpStackLocation or IoCopyCurrentIrpStackLocationToNext to set up the I/O stack location of the next-lower driver.

A higher-level driver's call to IoCallDriver sets the DeviceObject member to the next-lower-level driver's target device object, in the I/O stack location of the lower driver. The I/O manager passes each higher-level driver's IoCompletion routine a pointer to its own device object when the IoCompletion routine is called on completion of the IRP.

If a higher-level driver allocates IRPs to make requests of its own, its IoCompletion routine is passed a NULL DeviceObject pointer if that driver neither allocates a stack location for itself nor sets up the DeviceObject pointer in its own stack location of the newly allocated IRP.

In some cases, a higher-level driver layered over a mass-storage device driver is responsible for splitting up large transfer requests for the underlying device driver. In particular, SCSI class drivers must check the Parameters.Read.Length and Parameters.Write.Length, determine whether the size of the requested transfer exceeds the underlying HBA's transfer capabilities, and, if so, split the Length of the original request into a sequence of partial transfers to satisfy the original IRP.

See also

IO_STATUS_BLOCK

IRP

IoCallDriver

IoCopyCurrentIrpStackLocationToNext

IoGetCurrentIrpStackLocation

IoGetNextIrpStackLocation

IoSetCompletionRoutine

IoSetNextIrpStackLocation

IoSkipCurrentIrpStackLocation

View the official Windows Driver Kit DDI reference

Edit description on GitHub