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

Статья
07/16/2024

Подпрограмма 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. Эта структура — это объект адаптера, представляющий основное устройство DMA драйвера или канал DMA системы. Вызывающий объект получил этот указатель из предыдущего вызова подпрограммы IoGetDmaAdapter.

[in] DeviceObject

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

[in] DmaTransferContext

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

[in] Mdl

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

[in] Offset

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

[in] Length

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

[in] Flags

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

Флаг	Значение
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. Если ExecutionRoutineNULL, вызывающий объект может использовать ресурсы, выделенные BuildScatterGatherListEx. Дополнительные сведения см. в разделе "Примечания".

[in, optional] Context

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

[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 и ExecutionRoutineNULLили если флаг DMA_SYNCHRONOUS_CALLBACK не задан, а ExecutionRoutine равно NULL.

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

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

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

Замечания

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

Используйте BuildScatterGatherListEx только для адаптеров главного шины. Не используйте эту подпрограмму для адаптера 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. В этом случае драйвер должен указать допустимый указатель, отличный отNULLScatterGatherList указателя. Кроме того, после завершения передачи DMA, инициированной драйвером, драйвер должен вызвать подпрограмму FreeAdapterObject, чтобы освободить ресурсы, которые BuildScatterGatherListEx, выделенные для объекта адаптера.

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

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно начиная с Windows 8.
целевая платформа	Настольный
заголовка	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	DISPATCH_LEVEL