Функция NdisMAllocateSharedMemory (ndis.h)
Внимание!
Для процессоров ARM и ARM64 настоятельно рекомендуется, чтобы записи драйверов NDIS использовали WDF DMA или WDM DMA вместо NDIS Scatter/Gather DMA.
Дополнительные сведения о WDF DMA см. в разделе Обработка операций DMA в драйверах KMDF.
Дополнительные сведения о WDM DMA см. в дочерних разделах, связанных с DMA статьи Управление входными и выходными данными для драйверов.
NdisMAllocateSharedMemory выделяет и сопоставляет диапазон памяти узла, чтобы диапазон памяти одновременно был доступен как из системы узла, так и из сетевой карты DMA.
Синтаксис
void NdisMAllocateSharedMemory(
[in] NDIS_HANDLE MiniportAdapterHandle,
[in] ULONG Length,
[in] BOOLEAN Cached,
[out] PVOID *VirtualAddress,
[out] PNDIS_PHYSICAL_ADDRESS PhysicalAddress
);
Параметры
[in] MiniportAdapterHandle
Указывает входные данные дескриптора для MiniportInitializeEx.
[in] Length
Указывает число байтов для распределения.
[in] Cached
Этот параметр игнорируется (кэшированная память всегда используется в системах x86 и x64).
[out] VirtualAddress
Указатель на переменную, предоставленную вызывающей стороны, в которой эта функция возвращает базовый виртуальный адрес выделения для использования драйвером мини-порта. Если NdisMAllocateSharedMemory не может удовлетворить вызывающий объект, он возвращает значение NULL , чтобы указать, что память не выделена.
[out] PhysicalAddress
Указатель на переменную, предоставленную вызывающей стороны, в которой эта функция возвращает физический адрес, подходящий для использования сетевой картой, соответствующий возвращенной в VirtualAddress, или возвращает значение NULL.
Возвращаемое значение
None
Remarks
NdisMAllocateSharedMemory предоставляет как сопоставленный диапазон виртуальных адресов, используемый драйвером для доступа к блоку общей памяти, так и диапазон NDIS_PHYSICAL_ADDRESS типа, используемый сетевой картой. Значение, возвращаемое в PhysicalAddress , может быть сопоставлено системой вдвойне. Это значит, что "физический" диапазон адресов, описываемый значением PhysicalAddress и Length , может быть диапазоном сопоставленных логических адресов, которые не соответствуют физическим адресам узла для выделения на всех возможных платформах.
NdisMAllocateSharedMemory можно вызывать только из MiniportInitializeEx. Размер выделения для запроса зависит от того, как модуль записи драйвера, зная возможности и функции сетевой карты, решает найти компромисс между следующей дилеммой производительности и размера:
-
В периоды большого сетевого трафика драйвер мини-порта не может поддерживать высокую пропускную способность ввода-вывода, если ему не хватает общей памяти для доступных устройству буферов данных.
Например, драйвер мини-порта может указывать, что буферы приема в общей памяти быстрее, чем такие буферы возвращаются из связанных драйверов протокола, когда поток приемов поступает в сетевой адаптер. Если все его общее пространство памяти используется неоплаченными буферами получения, драйверу мини-порта может потребоваться отключить прерывания приема на сетевом адаптере, пока он не получит некоторое пространство общей памяти, доступное для буферов получения.
- С другой стороны, вызов NdisMAllocateSharedMemory с параметром Length , выбранным для прогнозирования некоторого максимального спроса на передачу, делает изображение драйвера больше, а его использование ресурсов довольно неэкономично, за исключением редких периодов очень высокого спроса на операции ввода-вывода. Кроме того, NdisMAllocateSharedMemory может не предоставить драйверу такой большой блок, если недостаточно системной памяти, что может привести к сбою инициализации драйвера.
NdisMAllocateSharedMemory и NdisMAllocateSharedMemoryAsyncEx — это единственные функции NdisXxx , которые можно вызвать для выделения памяти узла, совместно используемой драйвером, использующим виртуальные адреса, и сетевой картой, которая использует соответствующие логические адреса.
Драйвер мини-порта должен выравнивать буферы, выделяемые из общей кэшированной памяти, в целой части границы строки кэша узла, чтобы предотвратить разрыв строки кэша во время DMA. Разрыв линии кэша может вызвать проблемы с целостностью данных в драйвере или снизить производительность ввода-вывода драйвера (и системы) из-за необходимости чрезмерной очистки кэша данных для поддержания целостности данных. MiniportInitializeEx может вызывать NdisMGetDmaAlignment , чтобы определить границу выравнивания в текущей платформе для буферов, доступных устройству, которые драйвер настроит в выделенном диапазоне общей памяти.
Драйвер мини-порта должен установить ограничение на объем общей памяти, который он может выделить. Это ограничение зависит от конкретного драйвера и должно быть достаточно высоким, чтобы драйвер не иссякнул из буферов. Не устанавливайте слишком большое ограничение, так как это может привести к расточительности общей памяти, что может снизить производительность системы.
MiniportInitializeEx также может вызвать NdisSystemProcessorCount перед вызовом NdisMAllocateSharedMemory , если модуль записи драйверов решит выделить больший блок общей памяти на многопроцессорных компьютерах, исходя из предположения, что любой компьютер SMP, скорее всего, будет сетевым сервером с более высокими требованиями к сетевой машине, чем для рабочей станции.
Если вызов NdisMAllocateSharedMemory завершается сбоем, MiniportInitializeEx может снова вызвать запрос на меньшее выделение. Однако если MiniportInitializeEx не может выделить достаточный объем общей памяти для сетевого адаптера, он должен освободить все уже выделенные ресурсы и завершиться сбоем инициализации.
Если драйвер мини-порта впоследствии указывает, что получает с NdisMIndicateReceiveNetBufferLists, он должен выделить некоторое количество дескрипторов буфера из буферного пула, которые сопоставляют буферы получения сетевой карты в блоке общей памяти.
Если выделенная память кэшируется и, следовательно, требуется очистка при передаче, драйвер мини-порта должен вызвать NdisAllocateMdl , чтобы выделить дескриптор типа NDIS_BUFFER для диапазона общей памяти. Драйвер мини-порта должен вызвать KeFlushIoBuffers с этим дескриптором буфера, чтобы выполнить такую очистку.
Если драйвер мини-порта вызывает NdisMAllocateSharedMemoryAsyncEx или NdisMAllocateSharedMemory должен освободить все невыполненные выделения с одним или несколькими вызовами NdisMFreeSharedMemory при удалении сетевого адаптера, то есть при вызове функции MiniportHaltEx .
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Поддерживается в NDIS 6.0 и более поздних версиях. |
| Целевая платформа | Универсальное |
| Верхняя часть | ndis.h (включая Ndis.h) |
| Библиотека | Ndis.lib |
| IRQL | PASSIVE_LEVEL |