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

Статья
08/07/2023

Внимание!

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

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

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

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

Синтаксис

NDIS_STATUS NdisMAllocateNetBufferSGList(
  [in]           NDIS_HANDLE NdisMiniportDmaHandle,
  [in]           PNET_BUFFER NetBuffer,
  [in]           PVOID       Context,
  [in]           ULONG       Flags,
  [in, optional] PVOID       ScatterGatherListBuffer,
  [in]           ULONG       ScatterGatherListBufferSize
);

Параметры

[in] NdisMiniportDmaHandle

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

[in] NetBuffer

Указатель на структуру NET_BUFFER. NdisMAllocateNetBufferSGList выделяет список точечной и сборной для сетевых данных, связанных с этой NET_BUFFER структурой. Список точечной и сборной создается на основе данных, начиная с начала MDL, указанного в элементе CurrentMdl связанной NET_BUFFER_DATA структуры.

[in] Context

Указатель на область контекста, созданную вызывающим объектом. HAL передает этот указатель в MiniportProcessSGList после того, как HAL создаст список точечной и сборной. Вызывающий объект может использовать эту область контекста в своих целях.

[in] Flags

Флаги NDIS, которые можно объединить с операцией OR. Чтобы очистить все флаги, установите для этого элемента нулевое значение. Эта функция поддерживает флаг NDIS_SG_LIST_WRITE_TO_DEVICE, который; Если задано значение , указывает направление передачи DMA из NET_BUFFER на устройство. Если NDIS_SG_LIST_WRITE_TO_DEVICE не задано, передача выполняется с устройства. Драйверы мини-порта должны устанавливать этот флаг в пути отправки, когда операция DMA передает данные из NET_BUFFER на устройство. Драйверы минипорта, выполняющие операции DMA с устройства на предварительно выделенное NET_BUFFER, например сетевые адаптеры с поддержкой разгрузки дымохода во время операций получения, должны снять этот флаг.

[in, optional] ScatterGatherListBuffer

Если значение не равно NULL, То ScatterGatherListBuffer указывает указатель на хранилище, которое вызывающий объект выделяет для хранения точечных или сборных списков. Если значение РАВНО NULL, NDIS выделяет хранилище для списка точечной и сборной.

[in] ScatterGatherListBufferSize

Если параметр ScatterGatherListBuffer не равен NULL, То ScatterGatherListBufferSize указывает размер буфера, содержащего список точечной и сборной. Если этот размер слишком мал, NDIS выделяет хранилище для списка точечной и сборной. Если параметр ScatterGatherListBuffer имеет значение NULL, этот параметр не используется.

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

NdisMAllocateNetBufferSGList возвращает одно из следующих результатов:

Код возврата	Описание
NDIS_STATUS_SUCCESS	NdisMAllocateNetBufferSGList успешно создал список точечной и сборной для указанной структуры NET_BUFFER.
NDIS_STATUS_RESOURCES	Сбой NdisMAllocateNetBufferSGList из-за нехватки ресурсов.

Водитель автобуса master NDIS вызывает NdisMAllocateNetBufferSGList из своего Функция MiniportSendNetBufferLists . Драйвер мини-порта вызывает NdisMAllocateNetBufferSGList один раз для каждой структуры NET_BUFFER , для которой он должен получить список точечной и сборной.

Когда драйвер мини-порта вызывает NdisMAllocateNetBufferSGList, NDIS вызывает HAL для создания списка точечной и сборной. После того как HAL создаст список точечной и сборной, он вызывает функцию MiniportProcessSGList , зарегистрированную драйвером минипорта, вызвав NdisMRegisterScatterGatherDma.

HAL может вызывать MiniportProcessSGList до или после возврата NDIS из NdisMAllocateNetBufferSGList. Драйверы минипорта не должны пытаться получить доступ к списку точечной и сборной, пока hal не вызовет MiniportProcessSGList.

Чтобы повысить производительность системы, драйверы мини-портов должны предварительно выделить буферы для использования в параметре ScatterGatherListBufferобъекта NdisMAllocateNetBufferSGList. NDIS предоставляет рекомендуемый размер буферов в элементе ScatterGatherListSize параметра DmaDescription , когда драйвер мини-порта вызывает NdisMRegisterScatterGatherDma. Драйверы минипорта указывают размер буфера в параметре ScatterGatherListBufferSize при вызове NdisMAllocateNetBufferSGList.

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

Чтобы повысить производительность системы, список точечной и сборной создается из сетевых данных, начиная с начала MDL, указанного в элементе CurrentMdl связанной NET_BUFFER_DATA структуры. Начало сетевых данных в списке SG смещается от начала списка SG на значение, указанное в элементе CurrentMdlOffset связанной NET_BUFFER_DATA структуры.

Драйверы минипорта должны вызывать функцию NdisMFreeNetBufferSGList , чтобы освободить список точечной и сборной.

Требования

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