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

Статья
03/14/2023

Подпрограмма MapTransferEx настраивает регистры карты для сопоставления физических адресов в точечных и собирающихся списках с логическими адресами, необходимыми для передачи DMA.

Синтаксис

PMAP_TRANSFER_EX PmapTransferEx;

NTSTATUS PmapTransferEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PMDL Mdl,
  [in]            PVOID MapRegisterBase,
  [in]            ULONGLONG Offset,
  [in]            ULONG DeviceOffset,
  [in, out]       PULONG Length,
  [in]            BOOLEAN WriteToDevice,
  [out, optional] PSCATTER_GATHER_LIST ScatterGatherBuffer,
  [in]            ULONG ScatterGatherBufferLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext
)
{...}

Параметры

[in] DmaAdapter

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

[in] Mdl

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

[in] MapRegisterBase

Дескриптор регистров карты, выделенных для объекта адаптера. Вызывающий объект ранее получил этот дескриптор из подпрограммы AllocateAdapterChannelEx .

[in] Offset

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

[in] DeviceOffset

Смещение в байтах регистра данных целевого устройства или FIFO от базового адреса устройства. Этот параметр применяется к устройствам с несколькими fiFOS, к которым может обращаться системный контроллер DMA. Этот параметр используется только для системных передач DMA. Для передачи master по шине задайте для этого параметра нулевое значение.

[in, out] Length

Указатель на переменную, содержащую длину (в байтах) буфера данных ввода-вывода, используемого для передачи DMA. При входе эта переменная содержит длину, запрошенную вызывающим драйвером. Перед возвратом подпрограмма записывает фактическую длину сопоставленного буфера в эту переменную. Значение *Length при возврате из MapTransferEx указывает, сколько байтов было сопоставлено. Если количество регистров карты и размер буфера точечной и сборной достаточно для сопоставления всей длины, запрошенной вызывающим объектом, входные и выходные значения *Length идентичны. Если многомерные списки в цепочке MDL описывают в общей сложности N байт памяти, допустимые значения *Length находятся в диапазоне от 0 до N–Offset.

[in] WriteToDevice

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

[out, optional] ScatterGatherBuffer

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

[in] ScatterGatherBufferLength

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

[in, optional] DmaCompletionRoutine

Указатель на предоставленную вызывающим оператором подпрограмму DmaCompletionRoutine , вызываемую после завершения передачи DMA. Эта подпрограмма вызывается, если целевое устройство использует системный контроллер DMA, который создает прерывание завершения DMA. Подпрограмма DmaCompletionRoutine вызывается на DISPATCH_LEVEL после завершения передачи DMA. Для системного адаптера DMA этот параметр является необязательным и может иметь значение NULL. Для адаптера master шины задайте для этого параметра значение NULL.

[in, optional] CompletionContext

Определенный драйвером контекст для подпрограммы DmaCompletionRoutine . Этот контекст предоставляется в качестве параметра CompletionContext для подпрограммы DmaCompletionRoutine . Если параметр DmaCompletionRoutine имеет значение NULL, задайте для параметра CompletionContext значение NULL.

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

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

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

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

Для передачи, использующего системный контроллер DMA, вызывающий объект может, как вариант, предоставить подпрограмму обратного вызова DmaCompletionRoutine , которая вызывается по завершении передачи. Операционная система планирует этот обратный вызов в ответ на прерывание завершения DMA от системного контроллера DMA.

Число регистров карты, которые может быть настроено MapTransferEx , не может превышать максимум, полученный драйвером из IoGetDmaAdapter.

Параметры Mdl, Offset и Length описывают буфер данных ввода-вывода для запрошенной передачи DMA. Количество выделенных регистров карты может быть недостаточным для сопоставления всей памяти в этом буфере, или буфер точечной и сборной, на который указывает ScatterGatherBuffer , может быть недостаточно большим для описания всего буфера. MapTransferEx записывает выходное значение в *Length , чтобы сообщить драйверу, какой объем буферной памяти для запрошенной передачи DMA был сопоставлен подпрограммой. Подпрограмма записывает точечный или собираемый список в буфер, на который указывает ScatterGatherBuffer. В этом списке описываются фрагменты буфера, которые были успешно сопоставлены подпрограммой.

Если вызов MapTransferEx выполнен успешно, MapTransferEx записывает выходное значение *Length перед возвратом. Если вызывающий объект указывает DmaCompletionRoutine, обновленное выходное значение *Length всегда записывается перед запуском DmaCompletionRoutine . Дополнительные сведения см. в разделе Несколько вызовов MapTransferEx.

Параметр Offset указывает начальное смещение в цепочке MDL, описывающее память в буфере данных ввода-вывода. Например, предположим, что цепочка MDL содержит два mdl, MDL₁ и MDL, и что MDL₁ описывает N₁ байтов памяти, а MDL следующим образом — N₁ байтов. Если Offset = N, где N₁ < N < N₁ + N₁ , буфер не содержит памяти, описанной MDL₁, и начинается со смещения N – N₁ байтов в памяти, описанной MDL₁.

Если при передаче используется системный контроллер DMA, вызывающий объект может задать ScatterGatherBuffer = NULL, в этом случае MapTransferEx использует выделенный по умолчанию буфер по умолчанию для хранения списка точечной и сборной. Буфер по умолчанию гарантированно будет достаточно большим, чтобы содержать список точечной и собираемой по крайней мере одного элемента. Если буфер по умолчанию используется для точечной передачи большого количества элементов, может потребоваться завершить передачу нескольких вызовов MapTransferEx . Если оборудование контроллера DMA поддерживает передачу точечной и сборной данных, использование буфера по умолчанию может снизить производительность.

Если параметр ScatterGatherBuffer не равен NULL, а Параметр ScatterGatherBufferSize задает слишком маленький размер, чтобы содержать список точечной и сборной по крайней мере один элемент, MapTransferEx завершается сбоем и возвращает STATUS_INVALID_PARAMETER.

MapTransferEx — это расширенная версия подпрограммы MapTransfer . Расширенная версия имеет следующие преимущества:

MapTransferEx может обрабатывать все фрагменты буфера в цепочке MDL в одном вызове, но MapTransfer может обрабатывать только один физически смежный фрагмент буфера для каждого вызова.
MapTransferEx может создать весь точечный или собирающий список в одном вызове, но MapTransfer может создавать только один элемент точечной или сборной списка для каждого вызова.
MapTransferEx может сопоставить все фрагменты буфера в точечных и собираемых списках в одном вызове, но MapTransfer может сопоставить только один физически смежный фрагмент буфера для каждого вызова.
MapTransferEx требует только начального смещения для всего списка точечной и сборной, а MapTransfer — начальный виртуальный адрес для каждого фрагмента физически непрерывного буфера.
Вызов MapTransferEx может сопоставить буфер, который распространяется на один или несколько объектов MDL, но вызов MapTransfer может сопоставить только один физически смежный фрагмент буфера в памяти, описываемый MDL.
Для системной передачи DMA MapTransferEx позволяет вызывающей стороне предоставить процедуру обратного вызова DmaCompletionRoutine для получения уведомления после завершения передачи, но MapTransfer не предоставляет способ уведомить вызывающую сторону о завершении передачи DMA.

За каждым успешным вызовом MapTransferEx должен следовать соответствующий вызов подпрограммы FlushAdapterBuffersEx . Вызов FlushAdapterBuffersEx , следующий за вызовом MapTransferEx , должен произойти до следующего вызова MapTransferEx . Вызов FlushAdapterBuffersEx является обязательным, даже если вызов подпрограммы CancelMappedTransfer успешно отменяет сопоставленную передачу, запрошенную предыдущим вызовом MapTransferEx .

Дополнительные сведения см. в разделе Использование процедуры MapTransferEx.

Требования

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