StorPortBuildScatterGatherList function (storport.h)

Article
10/21/2021

The StorPortBuildScatterGatherList routine creates a scatter/gather list for the specified data buffer.

Syntax

ULONG StorPortBuildScatterGatherList(
  [in]      PVOID                        HwDeviceExtension,
  [in]      PVOID                        Mdl,
  [in]      PVOID                        CurrentVa,
  [in]      ULONG                        Length,
  [in]      PPOST_SCATTER_GATHER_EXECUTE ExecutionRoutine,
  [in]      PVOID                        Context,
  [in]      BOOLEAN                      WriteToDevice,
  [in, out] PVOID                        ScatterGatherBuffer,
  [in]      ULONG                        ScatterGatherBufferLength
);

Parameters

[in] HwDeviceExtension

A pointer to the hardware device extension for the host bus adapter (HBA).

[in] Mdl

A pointer to a memory descriptor list (MDL) that describes the memory pages associated with the data buffer.

[in] CurrentVa

The virtual address of the data buffer.

[in] Length

The length, in bytes, of the data buffer.

[in] ExecutionRoutine

A pointer to a miniport driver-supplied ExecutionRoutine. The Storport driver calls this routine after creating the scatter/gather list. The miniport driver should perform all operations that make use of the scatter/gather list inside the execution routine, not in the code that follows the call to the StorPortBuildScatterGatherList routine.

An ExecutionRoutine is declared as follows:

VOID
ExecutionRoutine (
    IN PVOID  *DeviceObject,
    IN PVOID  *Irp,
    IN PSTOR_SCATTER_GATHER_LIST  ScatterGather,
    IN PVOID  Context
    );

DeviceObject

Miniport drivers should ignore this parameter.

Irp

Miniport drivers should ignore this parameter.

ScatterGather

A pointer to a STOR_SCATTER_GATHER_LIST structure that contains the scatter/gather list for the specified data buffer.

Context

The context value specified in the StorPortBuildScatterGatherList function's Context parameter.

The Storport driver calls a miniport driver's ExecutionRoutine at IRQL = DISPATCH_LEVEL.

[in] Context

A context value that the port driver passes to the execution routine specified in the ExecutionRoutine parameter. The execution routine uses this value to uniquely identify the request.

[in] WriteToDevice

A value that indicates the direction of the DMA transfer. A value of TRUE indicates a transfer that is from the data buffer to the device, and a value of FALSE indicates a transfer that is from the device to the data buffer.

[in, out] ScatterGatherBuffer

A pointer to a miniport-supplied buffer that receives the scatter/gather list. A miniport driver can allocate memory for this buffer by calling the StorPortAllocatePool routine.

[in] ScatterGatherBufferLength

The size, in bytes, of the buffer pointed to by the ScatterGatherBuffer parameter.

Return value

StorPortBuildScatterGatherList returns one of the following values:

Return code	Description
STOR_STATUS_NOT_IMPLEMENTED	This function is not implemented on the active operating system.
STOR_STATUS_SUCCESS	Indicates that the routine created the scatter/gather list successfully. Important See 'Remarks'.
STOR_STATUS_INVALID_PARAMETER	The HwDeviceExtension passed was NULL.
STOR_STATUS_INVALID_IRQL	The call was made at an invalid IRQL.
STOR_STATUS_INSUFFICIENT_RESOURCES	The system has insufficient map registers available for the transfer.
STOR_STATUS_BUFFER_TOO_SMALL	The Length parameter is too big to fit within the buffer.

Remarks

The miniport driver calls StorPortPutScatterGatherList to release the resources that StorPortBuildScatterGatherList allocated while constructing the scatter/gather list.

The miniport driver must call StorPortPutScatterGatherList before freeing or reusing the memory it allocated for the scatter/gather list.

Note If StorPortBuildScatterGatherList returns STOR_STATUS_SUCCESS, then the callback in ExecutionRoutine was successfully queued to execute after the scatter/gather list is created. The miniport must not assume that ExecutionRoutine was called or that the scatter/gather list is ready when StorPortBuildScatterGatherList returns. If necessary, the miniport can synchronize the execution of code following StorPortBuildScatterGatherList with the callback in ExecutionRoutine to ensure that the scatter/gather list is available.

Requirements

Requirement	Value
Target Platform	Universal
Header	storport.h (include Storport.h)
IRQL	DISPATCH_LEVEL

Share via