FltAllocatePoolAlignedWithTag function (fltkernel.h)
FltAllocatePoolAlignedWithTag allocates a device-aligned buffer for use in a noncached I/O operation.
Syntax
PVOID FLTAPI FltAllocatePoolAlignedWithTag(
[in] PFLT_INSTANCE Instance,
[in] POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag
);
Parameters
[in] Instance
Opaque instance pointer for a caller-owned minifilter driver instance that is attached to the volume. This parameter is required and cannot be NULL.
[in] PoolType
Type of pool to allocate. One of the following:
NonPagedPool
PagedPool
NonPagedPoolCacheAligned
PagedPoolCacheAligned
See POOL_TYPE for a description of the available pool memory types.
[in] NumberOfBytes
Number of bytes to allocate. This parameter is required and can be zero.
[in] Tag
Specifies the pool tag for the allocated memory. Drivers normally specify the pool tag as a string of one to four 7-bit ASCII characters, delimited by single quotation marks (for example, 'abcd'). This parameter is required and cannot be zero.
Return value
If not enough free pool is available to satisfy the request, FltAllocatePoolAlignedWithTag returns a NULL pointer. Otherwise, FltAllocatePoolAlignedWithTag returns a pointer to the newly allocated buffer.
Remarks
FltAllocatePoolAlignedWithTag allocates a buffer that is aligned in accordance with the underlying device for the given volume. Such device-aligned buffers are required for noncached I/O. (They can also be used for cached I/O.) Thus when calling routines that perform noncached I/O, such as FltReadFile and FltWriteFile, minifilter drivers should call FltAllocatePoolAlignedWithTag instead of ExAllocatePoolWithTag.
If the caller specifies a value of zero for the NumberOfBytes parameter, FltAllocatePoolAlignedWithTag allocates the smallest amount of memory that meets the alignment requirement.
The system associates the pool tag specified by the Tag parameter with the allocated buffer. Programming tools, such as the Windows Debugger (WinDbg), can display the pool tag associated with each allocated buffer. The value of the pool tag is normally displayed in reversed order. For example, if a caller passes 'Fred' as the value of the Tag parameter, this value would appear as 'derF' if pool is dumped or when tracking pool usage in the debugger.
For more information about memory management, see Memory Management.
When the buffer that FltAllocatePoolAlignedWithTag allocates is no longer needed, the caller is responsible for freeing it by calling FltFreePoolAlignedWithTag.
Callers of FltAllocatePoolAlignedWithTag can be running at IRQL DISPATCH_LEVEL only if a NonPagedXxxPoolType is specified. Otherwise, callers must be running at IRQL <= APC_LEVEL.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | fltkernel.h (include Fltkernel.h) |
| Library | FltMgr.lib |
| IRQL | <= APC_LEVEL (see Remarks section) |