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

Статья
03/08/2023

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

Внимание!

Не вызывайте эту подпрограмму для системного устройства DMA.

Синтаксис

PGET_SCATTER_GATHER_LIST_EX PgetScatterGatherListEx;

NTSTATUS PgetScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PSCATTER_GATHER_LIST *ScatterGatherList
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER . Эта структура является объектом адаптера, который представляет устройство DMA master шины водителя. Вызывающий объект получил этот указатель из предыдущего вызова процедуры IoGetDmaAdapter .

[in] DeviceObject

Указатель на структуру DEVICE_OBJECT . Эта структура представляет собой объект физического устройства (PDO), представляющий целевое устройство для запрошенной операции DMA.

[in] DmaTransferContext

Указатель на инициализированный контекст передачи DMA. Этот контекст был инициализирован предыдущим вызовом подпрограммы InitializeDmaTransferContext . Этот контекст должен быть уникальным для всех запросов на выделение адаптера. Чтобы отменить ожидающий запрос на выделение, вызывающий объект должен предоставить контекст передачи DMA для запроса в подпрограмму CancelAdapterChannel .

[in] Mdl

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

[in] Offset

Начальное смещение для передачи DMA точечной и сборной данных. Этот параметр представляет собой смещение в байтах от начала буфера в первом MDL-файле в цепочке MDL. Если многомерные библиотеки в цепочке MDL указывают в общей сложности N байт буферного пространства, допустимые значения Offset находятся в диапазоне от 0 до N–1.

[in] Length

Длина передачи DMA (в байтах). Если в цепочке MDL указано в общей сложности N байтов буферного пространства, допустимые значения Length находятся в диапазоне от 1 до N–Offset.

[in] Flags

Флаги выделения канала адаптера. Поддерживается следующий флаг:

Flag	Значение
DMA_SYNCHRONOUS_CALLBACK	Подпрограмма GetScatterGatherListEx называется синхронно. Если этот флаг установлен и необходимые ресурсы DMA недоступны сразу, вызов завершается ошибкой и возвращает STATUS_INSUFFICIENT_RESOURCES.

Если установлен флаг DMA_SYNCHRONOUS_CALLBACK , параметр ExecutionRoutine является необязательным и может иметь значение NULL. Если этот флаг не задан, ExecutionRoutine должен быть допустимым указателем, не имеющим значения NULL . Дополнительные сведения об этом флаге см. в разделе Примечания.

[in, optional] ExecutionRoutine

Указатель на предоставленную драйвером подпрограмму AdapterListControl , которая инициирует передачу DMA для драйвера. Диспетчер ввода-вывода вызывает подпрограмму AdapterListControl после выделения необходимых ресурсов для объекта адаптера. После возврата подпрограммы AdapterListControl диспетчер ввода-вывода автоматически освобождает объект адаптера и ресурсы, выделенные для этого объекта.

Если установлен флаг DMA_SYNCHRONOUS_CALLBACK , параметр ExecutionRoutine является необязательным и может иметь значение NULL. Если этот параметр имеет значение NULL, вызывающий объект может использовать ресурсы, выделенные GetScatterGatherListEx , для выполнения передачи DMA после возврата GetScatterGatherListEx . Дополнительные сведения см. в разделе «Примечания».

[in, optional] Context

Определяемые драйвером контексты управления адаптером. Этот контекст передается подпрограмме AdapterListControl в качестве параметра Context .

[in] WriteToDevice

Направление передачи DMA. Присвойте этому параметру значение TRUE для операции записи, которая передает данные из памяти на устройство. Присвойте этому параметру значение FALSE для операции чтения, которая передает данные с устройства в память.

[in, optional] DmaCompletionRoutine

Не используется. Задайте значение NULL.

[in, optional] CompletionContext

Не используется. Задайте значение NULL.

[out, optional] ScatterGatherList

Указатель на переменную, в которую подпрограмма записывает указатель на выделенный список точечной или сборной. Этот параметр указывает на SCATTER_GATHER_LIST структуру. Подпрограмма выделяет эту структуру и массив SCATTER_GATHER_ELEMENT , на который она указывает.

Параметр ScatterGatherList является необязательным и может иметь значение NULL, если параметр ExecutionRoutine не равен NULL.

Если флаг DMA_SYNCHRONOUS_CALLBACK установлен и параметр ExecutionRoutine имеет значение NULL, то ScatterGatherList должен быть допустимым указателем, не равным NULL . Если свойство ExecutionRoutine не равно NULL, То ScatterGatherList является необязательным и может иметь значение NULL , если вызывающий драйвер не требует список точечной и сборной. Вызов GetScatterGatherListEx завершается ошибкой, если установлен флаг DMA_SYNCHRONOUS_CALLBACK , а ScatterGatherList и ExecutionRoutine имеют значение NULL или если флаг DMA_SYNCHRONOUS_CALLBACK не задан, а ExecutionRoutine имеет значение NULL.

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

GetScatterGatherListEx возвращает STATUS_SUCCESS, если вызов выполнен успешно. Возможные возвращаемые значения ошибок включают следующие коды состояния:

Код возврата	Описание
STATUS_INVALID_PARAMETERS	Подпрограмма завершилась сбоем из-за недопустимых значений параметров, переданных вызывающим.
STATUS_INSUFFICIENT_RESOURCES	Подпрограмме не удалось выделить ресурсы, необходимые для передачи DMA.

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

Используйте GetScatterGatherListEx только для адаптеров master шины. Не используйте эту подпрограмму для системного адаптера DMA.

Драйвер устройства master шины может использовать GetScatterGatherListEx для объединения операций, выполняемых подпрограммами AllocateAdapterChannelEx и MapTransferEx, в один вызов. GetScatterGatherListEx выполняет следующие операции:

Выделяет ресурсы, необходимые для передачи DMA.
Создает список точечной и сборной на основе значений параметров Mdl, Offset и Length .
Вызывает предоставленную драйвером подпрограмму AdapterListControl и предоставляет ей список точечной и сборной в качестве параметра.

Выделенные ресурсы автоматически освобождаются после возврата подпрограммы AdapterListControl . Если метод GetScatterGatherListEx вызывается синхронно (то есть, если установлен флаг DMA_SYNCHRONOUS_CALLBACK ), подпрограмму AdapterListControl можно опустить. В этом случае вызывающий объект использует выделенные ресурсы для инициации передачи DMA после возврата GetScatterGatherListEx . Вызывающий объект должен явно освободить эти ресурсы.

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

Если вызывающий драйвер устанавливает флаг DMA_SYNCHRONOUS_CALLBACK , подпрограмма GetScatterGatherListEx ведет себя следующим образом:

Если запрошенные ресурсы недоступны сразу, GetScatterGatherListEx не ожидает ресурсов, не создает список точечной и сборной и не вызывает подпрограмму AdapterListControl . Вместо этого GetScatterGatherListEx завершается сбоем и возвращает STATUS_INSUFFICIENT_RESOURCES.
Драйвер не требуется предоставлять подпрограмму AdapterListControl , если установлен флаг DMA_SYNCHRONOUS_CALLBACK .
Если драйвер предоставляет подпрограмму AdapterListControl , флаг DMA_SYNCHRONOUS_CALLBACK указывает, что эта подпрограмма должна вызываться в контексте вызывающего потока до возврата GetScatterGatherListEx .
Если драйвер не предоставляет подпрограмму AdapterListControl , драйвер может использовать выделенные ресурсы и список точечной и сборной после возврата GetScatterGatherListEx . В этом случае драйвер должен предоставить допустимый указатель ScatterGatherList , отличный от NULL. Кроме того, после того как драйвер инициирует передачу DMA, драйвер должен вызвать подпрограмму FreeAdapterObject , чтобы освободить ресурсы, выделенные для объекта адаптера GetScatterGatherListEx .

GetScatterGatherListEx — это расширенная версия подпрограммы GetScatterGatherList . Следующие функции доступны только в расширенной версии:

Метод GetScatterGatherListEx аналогичен процедуре BuildScatterGatherListEx , за исключением того, что GetScatterGatherListEx автоматически выделяет буфер для списка точечной и сборной.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows 8.
Целевая платформа	Персональный компьютер
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
IRQL	<= DISPATCH_LEVEL