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

Статья
03/08/2023

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

Внимание!

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

Синтаксис

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [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]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

Параметры

[in] DmaAdapter

Указатель на структуру DMA_ADAPTER . Эта структура представляет собой объект адаптера, представляющий master шине драйвера DMA устройства или системного канала DMA. Вызывающий объект получил этот указатель из предыдущего вызова процедуры 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	Подпрограмма BuildScatterGatherListEx называется синхронно. Если этот флаг установлен и необходимые ресурсы DMA недоступны сразу, вызов завершается ошибкой и возвращает STATUS_INSUFFICIENT_RESOURCES.

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

[in, optional] ExecutionRoutine

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

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

[in, optional] Context

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

[in] WriteToDevice

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

[in] ScatterGatherBuffer

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

[in] ScatterGatherLength

Размер (в байтах) буфера, переданного в параметре ScatterGatherBuffer . Размер выделенного буфера должен быть достаточно большим, чтобы он содержал список точечной и сборной, а также внутренние данные, которые операционная система хранит в этом буфере. Чтобы вычислить необходимый размер буфера, вызовите подпрограмму GetDmaTransferInfo или CalculateScatterGatherList .

[in, optional] DmaCompletionRoutine

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

[in, optional] CompletionContext

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

[out, optional] ScatterGatherList

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

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

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

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

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

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

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

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

Например, драйвер может предварительно выделить один или несколько точечных буферов во время инициализации устройства. Позже вызов BuildScatterGatherListEx , использующий такой буфер, может завершиться успешно в условиях низкой доступности памяти, что может привести к сбою вызова GetScatterGatherListEx .

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

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

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

BuildScatterGatherListEx — это расширенная версия подпрограммы BuildScatterGatherList . В следующем списке перечислены функции, доступные только в расширенной версии.

Компонент	Описание
Начальная смещение	Вызывающий драйвер может указать начальное смещение для передачи точечной и сборной DMA вместо запуска передачи с первого адреса буфера в начале цепочки MDL.
Отмена запроса на выделение	Драйвер может вызвать CancelAdapterChannel , чтобы отменить ожидающий запрос на выделение, когда адаптер DMA находится в очереди для ожидания ресурсов DMA.
Синхронный обратный вызов	Драйвер может задать флаг DMA_SYNCHRONOUS_CALLBACK , чтобы запросить вызов подпрограммы AdapterListControl , предоставленной драйвером, в вызывающем потоке до возврата BuildScatterGatherListEx .

Требования

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