PCALCULATE_SCATTER_GATHER_LIST_SIZE callback function (wdm.h)

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

Syntax

PCALCULATE_SCATTER_GATHER_LIST_SIZE PcalculateScatterGatherListSize;

NTSTATUS PcalculateScatterGatherListSize(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in, optional]  PMDL Mdl,
  [in]            PVOID CurrentVa,
  [in]            ULONG Length,
  [out]           PULONG ScatterGatherListSize,
  [out, optional] PULONG pNumberOfMapRegisters
)
{...}

Parameters

[in] DmaAdapter

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

[in, optional] Mdl

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

[in] CurrentVa

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

[in] Length

Specifies the length of the buffer, in bytes.

[out] ScatterGatherListSize

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

[out, optional] pNumberOfMapRegisters

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.

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

See also

BuildScatterGatherList

DEVICE_DESCRIPTION

DMA_ADAPTER

DMA_OPERATIONS

IoGetDmaAdapter

SCATTER_GATHER_LIST