IO_STACK_LOCATION structure (wdm.h)
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.
Syntax
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;
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
Parameters for IRP_MN_SET_POWER and IRP_MN_QUERY_POWER.
Parameters.Power.SystemContext
Parameters.Power.SystemPowerStateContext
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.
Requirements
Requirement | Value |
---|---|
Header | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |