Função NdisMAllocateNetBufferSGList (ndis.h)

Os drivers de miniporto master de barramento chamam a função NdisMAllocateNetBufferSGList para obter uma lista de dispersão/coleta para os dados de rede associados a uma estrutura de NET_BUFFER.

Sintaxe

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

Parâmetros

[in] NdisMiniportDmaHandle

Um identificador para uma área de contexto que o NDIS usa para gerenciar um recurso de DMA. O chamador obteve esse identificador chamando o Função NdisMRegisterScatterGatherDma .

[in] NetBuffer

Um ponteiro para uma estrutura NET_BUFFER. NdisMAllocateNetBufferSGList aloca uma lista de dispersão/coleta para os dados de rede associados a essa estrutura NET_BUFFER. A lista de dispersão/coleta é gerada a partir dos dados que começam no início do MDL especificado no membro CurrentMdl da estrutura de NET_BUFFER_DATA associada.

[in] Context

Um ponteiro para uma área de contexto que o chamador criou. HAL passa esse ponteiro para MiniportProcessSGList depois que HAL cria a lista de dispersão/coleta. O chamador pode usar essa área de contexto para suas próprias finalidades.

[in] Flags

Sinalizadores NDIS que podem ser combinados com uma operação OR. Para limpar todos os sinalizadores, defina esse membro como zero. Essa função dá suporte ao sinalizador NDIS_SG_LIST_WRITE_TO_DEVICE que; se definido, indica que a direção da transferência de DMA é do NET_BUFFER para o dispositivo. Se NDIS_SG_LIST_WRITE_TO_DEVICE estiver claro, a transferência será do dispositivo. Os drivers de miniport devem definir esse sinalizador no caminho de envio quando a operação de DMA transferir dados de um NET_BUFFER para o dispositivo. Os drivers de miniport que executam operações de DMA do dispositivo para uma NET_BUFFER pré-alocada, por exemplo, NICs compatíveis com descarregamento de chaminé durante as operações de recebimento, devem limpar esse sinalizador.

[in, optional] ScatterGatherListBuffer

Se não for NULL, ScatterGatherListBuffer especificará um ponteiro para o armazenamento que o chamador aloca para manter a lista de dispersão/coleta. Se NULL, o NDIS alocará armazenamento para a lista de dispersão/coleta.

[in] ScatterGatherListBufferSize

Se o parâmetro ScatterGatherListBuffer não for NULL, ScatterGatherListBufferSize especificará o tamanho do buffer que contém a lista de dispersão/coleta. Se esse tamanho for muito pequeno, o NDIS alocará armazenamento para a lista de dispersão/coleta. Se o parâmetro ScatterGatherListBuffer for NULL, esse parâmetro não será usado.

Retornar valor

NdisMAllocateNetBufferSGList retorna um dos seguintes:

Comentários

Um driver de miniporte master de barramento NDIS chama NdisMAllocateNetBufferSGList de seu Função MiniportSendNetBufferLists . O driver de miniporto chama NdisMAllocateNetBufferSGList uma vez para cada estrutura NET_BUFFER para a qual deve obter uma lista de dispersão/coleta.

Quando um driver de miniporto chama NdisMAllocateNetBufferSGList, o NDIS chama HAL para criar a lista de dispersão/coleta. Depois que o HAL compila a lista de dispersão/coleta, ele chama a função MiniportProcessSGList que o driver de miniporto registrou chamando NdisMRegisterScatterGatherDma.

HAL pode chamar MiniportProcessSGList antes ou depois que o NDIS retornar de NdisMAllocateNetBufferSGList. Os drivers de miniporte não devem tentar acessar a lista de dispersão/coleta até que HAL chame MiniportProcessSGList.

Para melhorar o desempenho do sistema, os drivers de miniport devem pré-alocar buffers para uso no parâmetro ScatterGatherListBuffer de NdisMAllocateNetBufferSGList. O NDIS fornece o tamanho recomendado para os buffers no membro ScatterGatherListSize do parâmetro DmaDescription quando o driver de miniporto chama NdisMRegisterScatterGatherDma. Os drivers de miniport especificam o tamanho do buffer no parâmetro ScatterGatherListBufferSize quando chamam NdisMAllocateNetBufferSGList.

O NDIS pode alocar um buffer mesmo se o driver de miniporto especificar um buffer no parâmetro ScatterGatherListBuffer . Isso pode acontecer se o buffer especificado for muito pequeno para manter a lista de dispersão/coleta. Portanto, os gravadores de driver não devem assumir que o buffer especificado no parâmetro ScatterGatherListBuffer contém a lista de dispersão/coleta. HAL passa o ponteiro de lista de dispersão/coleta correto para a função MiniportProcessSGList do driver de miniport.

Para melhorar o desempenho do sistema, a lista de dispersão/coleta é gerada a partir dos dados de rede começando no início do MDL especificado no membro CurrentMdl da estrutura de NET_BUFFER_DATA associada. O início dos dados de rede na lista SG é deslocado do início da lista SG pelo valor especificado no membro CurrentMdlOffset da estrutura de NET_BUFFER_DATA associada.

Os drivers de miniport devem chamar a função NdisMFreeNetBufferSGList para liberar uma lista de dispersão/coleta.

Requisitos

Confira também

MiniportProcessSGList

MiniportSendNetBufferLists

DMA de dispersão/coleta de NDIS

NET_BUFFER

NET_BUFFER_DATA

NdisMFreeNetBufferSGList