Функция NdisMRegisterScatterGatherDma (ndis.h)

Статья
08/07/2023

Внимание!

Для процессоров ARM и ARM64 настоятельно рекомендуется, чтобы записи драйверов NDIS использовали WDF DMA или WDM DMA вместо NDIS Scatter/Gather DMA.

Дополнительные сведения о WDF DMA см. в разделе Обработка операций DMA в драйверах KMDF.

Дополнительные сведения о WDM DMA см. в дочерних разделах, связанных с DMA статьи Управление входными и выходными данными для драйверов.

Драйверы master минипорта автобуса вызывают функцию NdisMRegisterScatterGatherDma из MiniportInitializeEx для инициализации канала DMA точечной и сборной.

Синтаксис

NDIS_STATUS NdisMRegisterScatterGatherDma(
  [in]      NDIS_HANDLE              MiniportAdapterHandle,
  [in, out] PNDIS_SG_DMA_DESCRIPTION DmaDescription,
  [out]     PNDIS_HANDLE             NdisMiniportDmaHandle
);

Параметры

[in] MiniportAdapterHandle

Дескриптор мини-порта, переданный NDIS в MiniportInitializeEx.

[in, out] DmaDescription

Указатель на структуру NDIS_SG_DMA_DESCRIPTION. Эта структура описывает свойства точечной и сборной DMA драйвера мини-порта. Структура определяется следующим образом:

typedef struct _NDIS_SG_DMA_DESCRIPTION {
  NDIS_OBJECT_HEADER  Header;
  ULONG  Flags;
  ULONG  MaximumPhysicalMapping;
  MINIPORT_PROCESS_SG_LIST_HANDLER  ProcessSGListHandler;
  MINIPORT_ALLOCATE_SHARED_MEM_COMPLETE_HANDLER  SharedMemAllocateCompleteHandler;
  ULONG  ScatterGatherListSize;
} NDIS_SG_DMA_DESCRIPTION, *PNDIS_SG_DMA_DESCRIPTION;

Эта структура включает следующие элементы:

Структура NDIS_OBJECT_HEADER для структуры NDIS_SG_DMA_DESCRIPTION. Задайте для элемента Type структуры, указанной в заголовке , значение NDIS_OBJECT_TYPE_SG_DMA_DESCRIPTION, для элемента Revision — NDIS_SG_DMA_DESCRIPTION_REVISION_1, а для элемента Size — значение NDIS_SIZEOF_SG_DMA_DESCRIPTION_REVISION_1.

Флаги

Набор битовых флагов, определяющих характеристики точечных и собираемых данных. Присвойте этому элементу побитовое ЗНАЧЕНИЕ ИЛИ всех обязательных флагов.

Флаг NDIS_SG_DMA_64_BIT_ADDRESS указывает, что сетевой адаптер может использовать 64-разрядную адресацию для операций DMA. В противном случае сетевой адаптер использует 32-разрядную адресацию.

Установите для этого элемента значение 0, если 64-разрядная адресация не требуется.

MaximumPhysicalMapping

Максимальное число байтов, которое сетевой адаптер может передать за одну операцию DMA. NDIS предоставляет это значение уровню аппаратной абстракции (HAL) при выделении канала DMA, и HAL использует это значение для определения максимального количества регистров карты для резервирования для сетевого адаптера.

ProcessSgListHandler

Функция MiniportProcessSGList , которую NDIS вызывает, когда HAL завершает создание точечных и собирательных списков.

SharedMemAllocateCompleteHandler

TheФункция MiniportSharedMemoryAllocateComplete для драйверов miniport, которые вызывают NdisMAllocateSharedMemoryAsyncEx. Это поле является необязательным и должно иметь значение NULL , если драйвер мини-порта не вызывает NdisMAllocateSharedMemoryAsyncEx.

ScattergatherListSize

Размер (в байтах) памяти, необходимой для хранения точечных или собираемых списков. NDIS задает это значение перед возвратом из NdisMRegisterScatterGatherDma. Драйверы мини-портов должны использовать этот размер для предварительного выделения памяти для каждого точечных или собирающихся списков.

[out] NdisMiniportDmaHandle

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

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

NdisMRegisterScatterGatherDma возвращает одно из следующих элементов:

Код возврата	Описание
NDIS_STATUS_SUCCESS	NdisMRegisterScatterGatherDma успешно выделил ресурсы для master операций DMA шины.
NDIS_STATUS_RESOURCES	Сбой NdisMRegisterScatterGatherDma из-за нехватки ресурсов.
NDIS_STATUS_NOT_SUPPORTED	Сбой NdisMRegisterScatterGatherDma, так как в минипорте не указано, что он поддерживает NDIS 6.0 или более поздних версий, или из-за того, что драйвер мини-порта не указал, что его сетевой адаптер является устройством DMA master шины. Драйвер мини-порта указывает свою версию NDIS при вызове NdisMRegisterMiniportDriver. Драйвер мини-порта указывает, что он поддерживает устройства DMA master шины при вызовах. NdisMSetMiniportAttributes.
NDIS_STATUS_BAD_VERSION	Текущая версия NDIS не поддерживает версию, указанную в элементе Revision структуры заголовкаDmaDescription .

Драйвер NDIS bus-master miniport вызывает NdisMRegisterScatterGatherDma в своей функции MiniportInitializeEx для инициализации ресурсов для операций DMA точечной и сборной. Параметр DmaDescription , который драйвер мини-порта передает в NdisMRegisterScatterGatherDma , содержит сведения, которые NDIS использует для инициализации точечных и сборных ресурсов DMA. После возврата NdisMRegisterScatterGatherDma элемент ScatterGatherListSizeDmaDescription содержит размер буфера, который должен быть достаточным для хранения точечных или собираемых списков. Драйверы мини-портов должны использовать этот размер для предварительного выделения памяти для точечных или сборных списков.

Элемент ProcessSGListHandler в параметре DmaDescription определяет точку входа в драйвере мини-порта для функции MiniportProcessSGList . Когда драйвер мини-порта вызывает NdisMAllocateNetBufferSGList, NDIS вызывает HAL, чтобы предоставить точечный или сборный список драйверу мини-порта. HAL вызывает MiniportProcessSGList после того, как HAL завершит создание списка точечной и собираемой информации. NDIS может вызывать MiniportProcessSGList вне контекста вызова NdisMAllocateNetBufferSGList.

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

Вызов водителей автобусов master минипорта NdisMAllocateSharedMemoryAsyncEx для динамического выделения общей памяти для операций передачи данных. Этот вызов необходим, если высокий сетевой трафик приводит к нехватке общей памяти драйвера мини-порта, выделенного драйвером во время инициализации. Если NdisMAllocateSharedMemoryAsyncEx возвращает NDIS_STATUS_PENDING, NDIS вызываетФункция MiniportSharedMemoryAllocateComplete для завершения операции позже. Драйверы miniport указывают точку входа для функции MiniportSharedMemoryAllocateComplete в элементе SharedMemAllocateCompleteHandler параметра DmaDescription .

Драйверы мини-порта вызываютФункция NdisMDeregisterScatterGatherDma для освобождения ресурсов DMA, выделенных NdisMRegisterScatterGatherDma.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается в NDIS 6.0 и более поздних версиях.
Целевая платформа	Универсальное
Верхняя часть	ndis.h (включая Ndis.h)
Библиотека	Ndis.lib
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	Init_RegisterSG(ndis), Irql_Gather_DMA_Function(ndis)