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

Подпрограмма buildScatterGatherListEx выделяет ресурсы, необходимые для передачи DMA, создает список точечной и сборной и вызывает подпрограмму, предоставляемую драйвером, AdapterListControl для запуска передачи 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, параметр 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, если вызов выполнен успешно. Возможные значения возвращаемых ошибок включают следующие коды состояния.

Замечания

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. В следующем списке перечислены функции, доступные только в расширенной версии:

Требования

См. также

AdapterListControl

AllocateAdapterChannelEx

CalculateScatterGatherList

DMA_OPERATIONS

DmaCompletionRoutine

FreeAdapterObject

GetScatterGatherList

GetScatterGatherListEx

MapTransferEx