PVOID EngAllocUserMem(
|
ULONG cj, | |
|
ULONG tag | |
|
); |
EngAllocUserMem allocates a block of memory from the address space of the current process, and inserts a caller-supplied tag before the allocation.
EngAllocUserMem returns a pointer to the allocated memory if there is enough user-mode memory to satisfy the request; otherwise, it returns a null pointer.
A Windows NT process has 4 GB of virtual address space. The upper 2 GB is system memory that is accessible only to kernel-mode threads; this space is identical across all processes. The lower 2 GB is user memory that is accessible to both user-mode and kernel-mode threads; this space is unique to its process. The memory allocated by EngAllocUserMem is allocated from the unique 2 GB of user memory, and is thus accessible only when the graphics driver is called in the context of the thread in which the memory was allocated. Graphics drivers always execute in the context of the caller; that is, graphics drivers cannot switch process contexts.
EngAllocUserMem is particularly useful to a printer driver with large bitmaps that will only be used by the current process. Rather than allocating from the system pool, this driver can instead allocate space from the current process’s address space. Drivers need to exercise care with memory allocated by EngAllocUserMem, as it is possible for the application to step on this memory. EngAllocUserMem should only be used to allocate relatively large chunks of memory, as each allocation takes at least 64K of virtual address space. Sensitive data structures should never be allocated using this function. Also, user memory allocated by this function cannot be passed to EngWritePrinter by the printer driver.
The tag string should be specified in byte reversed order. The first letter must be ‘D’; the other three should be indicative of the driver name. For example, the tag string ‘ 3sD’ appears as ‘Ds3 ‘ if pool is dumped. The tag appears in any crash dump of the system that occurs.