Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

CalculateScatterGatherList routine

The CalculateScatterGatherList routine calculates the size, in bytes, of scatter/gather list necessary to hold a given buffer.

Syntax


NTSTATUS CalculateScatterGatherList(
  _In_      PDMA_ADAPTER DmaAdapter,
  _In_opt_  PMDL         Mdl,
  _In_      PVOID        CurrentVa,
  _In_      ULONG        Length,
  _Out_     PULONG       ScatterGatherListSize,
  _Out_opt_ PULONG       NumberOfMapRegisters
);

Parameters

DmaAdapter [in]

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

Mdl [in, optional]

Either NULL or a pointer to the MDL that contains the buffer.

CurrentVa [in]

Pointer to the virtual address of the beginning of the buffer.

Length [in]

Specifies the length of the buffer, in bytes.

ScatterGatherListSize [out]

Pointer to the variable the routine uses to return the size of the scatter/gather list, in bytes.

NumberOfMapRegisters [out, optional]

Either NULL or pointer to the variable the routine uses to return the number of map registers needed for DMA operations on the buffer.

Return value

CalculateScatterGatherList returns one of the following status codes.

Return codeDescription
STATUS_SUCCESS

The values returned in ScatterGatherListSize and NumberOfMapRegisters are valid.

STATUS_INSUFFICIENT_RESOURCES

The number of map registers required exceeds the number of map registers available.

STATUS_BUFFER_TOO_SMALL

The specified Length is too big to fit within the buffer.

 

Remarks

CalculateScatterGatherList is not a system routine that can be called directly by name. This routine can be called only by pointer from the address returned in a DMA_OPERATIONS structure. Drivers obtain the address of this routine by calling IoGetDmaAdapter with the Version member of the DeviceDescription parameter set to DEVICE_DESCRIPTION_VERSION2. If IoGetDmaAdapter returns NULL, the routine is not available on your platform.

If the caller passes NULL for the Mdl parameter, the routine calculates the maximum possible size needed to hold a scatter/gather list for the specified buffer. If the caller specifies the MDL that contains the buffer in the Mdl parameter, the routine computes the actual size needed to hold the scatter/gather list.

A driver uses CalculateScatterGatherList to allocate a scatter/gather list buffer to pass to BuildScatterGatherList.

Requirements

Target platform

Desktop

Version

Available in Windows XP and later versions of Windows.

Header

Ntddk.h (include Ntddk.h)

IRQL

Any level

See also

DEVICE_DESCRIPTION
DMA_ADAPTER
DMA_OPERATIONS
SCATTER_GATHER_LIST
BuildScatterGatherList
IoGetDmaAdapter

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft