NdisAllocateMemoryWithTag function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
NdisAllocateMemoryWithTag allocates resident (nonpaged) system-space memory.
Syntax
NDIS_STATUS NdisAllocateMemoryWithTag(
_Out_ PVOID *VirtualAddress,
_In_ UINT Length,
_In_ ULONG Tag
);
Parameters
VirtualAddress [out]
Pointer to a caller-supplied variable in which this function returns the base virtual address of the allocated memory or NULL if sufficient nonpaged memory is currently unavailable.Length [in]
Specifies the size in bytes to be allocated.Tag [in]
Is a string, delimited by single quote marks, with up to four characters, usually specified in reversed order. The NDIS-supplied default tag for this call is 'maDN', but the caller can override this default by supplying an explicit value.
Return value
NdisAllocateMemoryWithTag can return either of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | The caller can use the allocated memory range starting at the value returned at VirtualAddress. |
| NDIS_STATUS_FAILURE | An attempt to allocate the requested memory failed. This return does not necessarily mean that a subsequent call will fail. |
Remarks
A call to NdisAllocateMemoryWithTag is equivalent to calling NdisAllocateMemory, except that NdisAllocateMemoryWithTag allows the caller to supply a tag that appears in any crash dump of the system that occurs subsequently.
During driver development on a checked build of the system, this function also can be useful for crash debugging. Calling this routine, rather than NdisAllocateMemory, inserts the caller-supplied tag into a crash dump of pool memory.
The Tag passed to this function is more readable if its characters are reversed when NdisAllocateMemoryWithTag is called. For example, if a caller passes 'Fred' as a Tag, it would appear as 'derF' if pool is dumped or when tracking pool usage in the debugger. The NDIS-supplied default tag appears as 'NDam' (indicating NDISallocatememory) when pool is dumped.
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. NdisAllocateMemoryWithTagPriority. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL. |
See also