PVOID
ExAllocatePool(
IN POOL_TYPE PoolType,
IN ULONG NumberOfBytes
);
ExAllocatePool allocates pool memory of the specified type and returns a pointer to the allocated block. This routine is used for general pool allocation of memory.
Parameters
PoolType
Specifies the type of pool memory to allocate, which can be one of the following:
NonPagedPool
NonPagedPoolMustSucceed
NonPagedPoolCacheAligned
NonPagedPoolCacheAlignedMustS
PagedPool
PagedPoolCacheAligned
NumberOfBytes
Specifies the number of bytes to allocate.
Return Value
If the PoolType is one of the XxxMustS(ucceed) values, this call succeeds if the system has any available must-succeed memory, and ExAllocatePool returns a pointer to allocated pool memory.
ExAllocatePool returns a NULL pointer if the PoolType is not one of the XxxMustS(ucceed) values and not enough free pool exists to satisfy the request.
Comments
If the NumberOfBytes requested is >= PAGE_SIZE, a page-aligned buffer is allocated. Memory requests for < PAGE_SIZE do not cross page boundaries. Memory requests for < PAGE_SIZE are not necessarily page-aligned but are aligned on an 8-byte boundary.
For the PoolType NonPagedPoolMustSucceed somewhat less than PAGE_SIZE memory is available. If such a call fails to allocate sufficient memory, ExAllocatePool causes a system crash. Consequently, a caller should request this type of memory only if that caller needs it to prevent the system from crashing or being corrupted. Very few drivers ever encounter a situation that requires them to allocate this type of memory.
A successful allocation requesting NumberOfBytes < PAGE_SIZE of nonpaged pool gives the caller exactly the number of requested bytes of memory. Any successful allocation that requests NumberOfBytes > PAGE_SIZE wastes all unused bytes on the last-allocated page.
Callers of ExAllocatePool must be running at IRQL <= DISPATCH_LEVEL. A caller at DISPATCH_LEVEL must specify a NonPagedXxx PoolType. Otherwise, the caller must be running at IRQL < DISPATCH_LEVEL.
If ExAllocatePool returns NULL, the caller should return the NTSTATUS value STATUS_INSUFFICIENT_RESOURCES or should delay processing to another point in time.
See Also