Export (0) Print
Expand All

AllocateCommonBuffer routine

The AllocateCommonBuffer routine allocates memory and maps it so that it is simultaneously accessible from both the processor and a device for DMA operations.

Syntax


PVOID AllocateCommonBuffer(
  _In_   PDMA_ADAPTER DmaAdapter,
  _In_   ULONG Length,
  _Out_  PPHYSICAL_ADDRESS LogicalAddress,
  _In_   BOOLEAN CacheEnabled
);

Parameters

DmaAdapter [in]

Pointer to the DMA_ADAPTER structure returned by IoGetDmaAdapter that represents the bus-master adapter or DMA controller.

Length [in]

Specifies the number of bytes of memory to allocate.

LogicalAddress [out]

Pointer to a variable that receives the logical address the device can use to access the allocated buffer. Use this address rather than calling MmGetPhysicalAddress because the system can take into account any platform-specific memory restrictions.

CacheEnabled [in]

Specifies whether the allocated memory can be cached. This parameter is ignored on computers with x86-based, x64-based, and Itanium-based processors, because the operating system assumes that DMA is always coherent with the caches of these processors. For these processors, the operating system always allocates common buffers that are cache-enabled, and a driver can use common buffers only if DMA operations for the device are coherent with the contents of the processor caches.

Return value

AllocateCommonBuffer returns the base virtual address of the allocated range. If the buffer cannot be allocated, it returns NULL.

Remarks

AllocateCommonBuffer is not a system routine that can be called directly by name. This routine is callable only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter.

AllocateCommonBuffer supports DMA in which the device and the processor continuously communicate through system memory, as in a control structure for a bus-master DMA device.

AllocateCommonBuffer also supports subordinate devices whose drivers use a system DMA controller's autoinitialize mode.

AllocateCommonBuffer does the following:

  • Allocates memory that can be reached from both the processor and the device. This memory appears contiguous to the device.

  • Allocates map registers to map the buffer, if required by the system.

  • Sets up a translation for the device, including loading map registers if necessary.

To use resident system memory economically, drivers should allocate as few of these buffers per device as possible. AllocateCommonBuffer allocates at least a page of memory, regardless of the requested Length. After a successful allocation requesting fewer than PAGE_SIZE bytes, the caller can access only the requested Length. After a successful allocation requesting more than an integral multiple of PAGE_SIZE bytes, any remaining bytes on the last allocated page are inaccessible to the caller.

If a driver needs several pages of common buffer space, but the pages need not be contiguous, the driver should make several one-page requests to AllocateCommonBuffer instead of one large request. This approach conserves contiguous memory.

Drivers typically call AllocateCommonBuffer as part of device start-up, during their response to a PnP IRP_MN_START_DEVICE request. After startup, it is possible that only one-page requests will succeed, if any.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

PASSIVE_LEVEL

DDI compliance rules

IrqlDispatch

See also

DMA_ADAPTER
FreeCommonBuffer
IoGetDmaAdapter
DMA_OPERATIONS

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft