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

Статья
08/07/2023

Внимание!

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

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

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

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

Синтаксис

NDIS_STATUS NdisMAllocateSharedMemoryAsyncEx(
  [in] NDIS_HANDLE MiniportDmaHandle,
  [in] ULONG       Length,
  [in] BOOLEAN     Cached,
  [in] PVOID       Context
);

Параметры

[in] MiniportDmaHandle

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

[in] Length

Количество байтов, которые необходимо выделить.

[in] Cached

Этот параметр игнорируется (кэшированная память всегда используется в системах x86 и x64).

[in] Context

Указатель на определяемый драйвером контекст, передаваемый в функцию MiniportSharedMemoryAllocateComplete при ее вызове .

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

NdisMAllocateSharedMemoryAsyncEx может возвращать одно из следующих значений:

Код возврата	Описание
NDIS_STATUS_PENDING	NDIS вызовет функцию MiniportSharedMemoryAllocateComplete и предоставит сведения, описывающие выделенную общую память. Если попытка выделить общую память завершается неудачей, NDIS вызывает MiniportSharedMemoryAllocateComplete и передает указатели NULL .
NDIS_STATUS_FAILURE	В настоящее время не удалось выделить запрошенную память. Если NdisMAllocateSharedMemoryAsyncEx возвращает это состояние, последующий вызов с теми же параметрами может быть выполнен успешно в зависимости от того, стали ли доступны системные ресурсы.

Код возврата

Описание

NDIS_STATUS_PENDING

NDIS вызовет функцию MiniportSharedMemoryAllocateComplete и предоставит сведения, описывающие выделенную общую память. Если попытка выделить общую память завершается неудачей, NDIS вызывает MiniportSharedMemoryAllocateComplete и передает указатели NULL .

NDIS_STATUS_FAILURE

В настоящее время не удалось выделить запрошенную память. Если NdisMAllocateSharedMemoryAsyncEx возвращает это состояние, последующий вызов с теми же параметрами может быть выполнен успешно в зависимости от того, стали ли доступны системные ресурсы.

Примечание Драйвер мини-порта должен уже вызывать NdisMRegisterScatterGatherDma или NdisMRegisterDmaChannel , чтобы инициализировать канал DMA точечной обработки или сбора перед вызовом NdisMAllocateSharedMemoryAsyncEx.

Драйверы сетевых адаптеров master DMA вызывают NdisMAllocateSharedMemoryAsyncEx для динамического выделения общей памяти. Такие драйверы также выделяют общее пространство памяти во время инициализации. Эти драйверы используют динамически выделенную общую память для операций передачи, когда высокий сетевой трафик предъявляет чрезмерные требования к существующему общему пространству памяти.

Такой драйвер мини-порта обычно поддерживает одну или несколько переменных состояния для отслеживания количества буферов общей памяти, доступных для входящих передач. Когда количество доступных буферов достигает низкого уровня, определяемого драйвером, драйвер мини-порта вызывает NdisMAllocateSharedMemoryAsyncEx , чтобы выделить больше буферного пространства в общей памяти. Когда количество доступных буферов достигает высокого уровня, определяемого драйвером, драйвер мини-порта вызывает NdisMFreeSharedMemory один или несколько раз, чтобы освободить предыдущие динамические выделения.

Как правило, такой драйвер мини-порта сохраняет блок общей памяти, который его функция MiniportInitializeEx , выделенная с помощью NdisMAllocateSharedMemory , до удаления сетевой карты. При удалении сетевой карты NDIS вызывает функцию MiniportHaltEx драйвера мини-порта . Этого выделения достаточно для обработки среднего спроса на передачу через сетевой адаптер.

Драйвер мини-порта должен установить ограничение на объем общей памяти, который он может выделить. Это ограничение зависит от конкретного драйвера и должно быть достаточно высоким, чтобы драйвер не иссякнул из буферов. Не следует использовать слишком большое ограничение, так как это может привести к расточительности потребления общей памяти, что может снизить производительность системы.

Любой драйвер мини-порта, вызывающий NdisMAllocateSharedMemoryAsyncEx или NdisMAllocateSharedMemory , должен освободить все невыполненные выделения с одним или несколькими вызовами NdisMFreeSharedMemory при удалении сетевой карты.

Требования

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