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

Статья
08/08/2023

Подпрограмма GetScatterGatherList подготавливает систему к операции точечной и сборной DMA от имени целевого объекта устройства с помощью системного контроллера DMA или адаптера master шины.

Синтаксис

PGET_SCATTER_GATHER_LIST PgetScatterGatherList;

NTSTATUS PgetScatterGatherList(
  [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] DmaAdapter

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

[in] DeviceObject

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

[in] Mdl

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

[in] CurrentVa

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

[in] Length

Указывает длину в байтах для сопоставления.

[in] ExecutionRoutine

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

[in] Context

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

[in] WriteToDevice

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

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

Эта подпрограмма может возвращать одно из следующих значений NTSTATUS.

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

Подпрограмма GetScatterGatherList динамически выделяет буфер для хранения списка точечной и сборной. Возможные значения NTSTATUS в случае сбоя выделения буфера см. в возвращаемом значении.

GetScatterGatherList не является системной подпрограммой, которую можно вызывать напрямую по имени. Эта подпрограмма может вызываться только указателем из адреса, возвращаемого в DMA_OPERATIONS структуре. Драйверы получают адрес этой подпрограммы, вызывая IoGetDmaAdapter.

Как только соответствующий канал DMA и все необходимые регистры карты будут доступны, GetScatterGatherList создает список точечной и сборочной информации, инициализирует регистры карты, а затем вызывает подпрограмму AdapterListControl , предоставляемую драйвером, для выполнения операции ввода-вывода.

GetScatterGatherList объединяет действия подпрограмм AllocateAdapterChannel и MapTransfer для драйверов, выполняющих точечную и сборную DMA. GetScatterGatherList определяет, сколько регистров карты требуется для передачи, выделяет регистры карты, сопоставляет буферы для DMA и заполняет список точечной и сборной. Затем он вызывает предоставленную подпрограмму AdapterListControl , передав указатель на список точечной и сборной в ScatterGather. Драйвер должен сохранить этот указатель для использования при вызове PutScatterGatherList. Обратите внимание, что GetScatterGatherList не имеет ограничений очередей, применяемых к AllocateAdapterChannel.

В подпрограмме AdapterListControl драйвер должен выполнять операции ввода-вывода. По возвращении из подпрограммы, предоставленной драйвером, GetScatterGatherList сохраняет регистры карты, но освобождает структуру адаптера DMA. Драйвер должен вызвать PutScatterGatherList (который очищает буферы), прежде чем он сможет получить доступ к данным в буфере.

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

Требования

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