NdisAllocateMemoryWithTag

NdisAllocateMemoryWithTag allocates resident (nonpaged) system-space memory.

NDIS_STATUS
  NdisAllocateMemoryWithTag(
    OUT PVOID  *VirtualAddress,
    IN UINT  Length,
    IN ULONG  Tag
    );

Parameters

VirtualAddress

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

Specifies the size in bytes to be allocated.

Tag

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:

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.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

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 NDIS allocate memory) when pool is dumped.

Callers of NdisAllocateMemoryWithTag can be running at IRQL <= DISPATCH_LEVEL.

See Also

MiniportInitialize, NdisAllocateMemory, NdisFreeMemory, NdisMAllocateSharedMemory, NdisMSetAttributes, NdisMSetAttributesEx