функция обратного вызова PBUILD_SCATTER_GATHER_LIST (wdm.h)

Статья
03/08/2023

Подпрограмма BuildScatterGatherList подготавливает систему к операции DMA, используя предоставленный драйвером буфер для создания списка точечной и сборной данных.

Синтаксис

PBUILD_SCATTER_GATHER_LIST PbuildScatterGatherList;

NTSTATUS PbuildScatterGatherList(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PMDL Mdl,
  [in] PVOID CurrentVa,
  [in] ULONG Length,
  [in] PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in] PVOID Context,
  [in] BOOLEAN WriteToDevice,
  [in] PVOID ScatterGatherBuffer,
  [in] ULONG ScatterGatherLength
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER, возвращаемую IoGetDmaAdapter, которая представляет адаптер master шины или контроллер DMA.

[in] DeviceObject

Указатель на объект устройства, представляющий целевое устройство для операции DMA.

[in] Mdl

Указатель на MDL, описывающий буфер, заданный элементом MdlAddress текущего IRP.

[in] CurrentVa

Указатель на текущий виртуальный адрес в MDL для буфера, который необходимо сопоставить с операцией передачи DMA.

[in] Length

Указывает длину сопоставляемого буфера (в байтах).

[in] ExecutionRoutine

Указатель на подпрограмму AdapterListControl, предоставляемую драйвером, которая вызывается по адресу IRQL = DISPATCH_LEVEL при наличии системного контроллера DMA или адаптера master шины.

[in] Context

Указатель на определенный драйвером контекст, передаваемый в ExecutionRoutine при его вызове.

[in] WriteToDevice

Указывает направление передачи DMA: TRUE для передачи из буфера на устройство и FALSE в противном случае.

[in] ScatterGatherBuffer

Указатель на буфер, предоставленный вызывающим объектом, который подпрограмма заполняет SCATTER_GATHER_LIST структурой.

[in] ScatterGatherLength

Указывает размер (в байтах) буфера, передаваемого в параметре ScatterGatherBuffer .

Возвращаемое значение

BuildScatterGatherList возвращает одно из следующих значений:

Код возврата	Описание
STATUS_SUCCESS	Операция успешно завершена.
STATUS_INSUFFICIENT_RESOURCES	В системе недостаточно регистров карт, доступных для передачи.
STATUS_BUFFER_TOO_SMALL	Указанная длина слишком велика, чтобы поместиться в буфер.

BuildScatterGatherList не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в DMA_OPERATIONS структуре. Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter с элементом Version параметра DeviceDescription , для DEVICE_DESCRIPTION_VERSION2. Если IoGetDmaAdapter возвращает значение NULL, подпрограмма недоступна на вашей платформе.

BuildScatterGatherList выполняет ту же операцию, что и GetScatterGatherList, за исключением того, что он использует буфер, указанный в параметре ScatterGatherBuffer , для хранения создаваемого им списка точечной и сборной. В отличие от этого, GetScatterGatherList динамически выделяет буфер для хранения точечной или собираемой списка. Если для выделения буфера недостаточно памяти, getScatterGatherList может завершиться ошибкой STATUS_INSUFFICIENT_RESOURCES. Драйверы, которые должны избегать этого сценария, могут предварительно выделить буфер для хранения точечных и собирающихся списков и использовать вместо него BuildScatterGatherList .

Драйвер может использовать подпрограмму CalculateScatterGatherList , чтобы определить размер буфера, выделяемого для хранения точечных и собираемых списков.

Драйвер должен сохранить указатель на список точечной и сборной в ScatterGatherBuffer для использования при вызове PutScatterGatherList. Драйвер должен вызвать PutScatterGatherList (который очищает список), прежде чем он сможет получить доступ к данным в списке.

Требования

Требование	Значение
Минимальная версия клиента	Доступно в Windows XP и более поздних версиях Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h)
IRQL	DISPATCH_LEVEL
Правила соответствия DDI	IrqlDispatch(wdm)