PBUILD_SCATTER_GATHER_LIST_EX função de retorno de chamada (wdm.h)

A rotina BuildScatterGatherListEx aloca os recursos necessários para uma transferência de DMA, cria uma lista de dispersão/coleta e chama a rotina AdapterListControl fornecida pelo driver para iniciar a transferência de DMA.

Sintaxe

PBUILD_SCATTER_GATHER_LIST_EX PbuildScatterGatherListEx;

NTSTATUS PbuildScatterGatherListEx(
  [in]            PDMA_ADAPTER DmaAdapter,
  [in]            PDEVICE_OBJECT DeviceObject,
  [in]            PVOID DmaTransferContext,
  [in]            PMDL Mdl,
  [in]            ULONGLONG Offset,
  [in]            ULONG Length,
  [in]            ULONG Flags,
  [in, optional]  PDRIVER_LIST_CONTROL ExecutionRoutine,
  [in, optional]  PVOID Context,
  [in]            BOOLEAN WriteToDevice,
  [in]            PVOID ScatterGatherBuffer,
  [in]            ULONG ScatterGatherLength,
  [in, optional]  PDMA_COMPLETION_ROUTINE DmaCompletionRoutine,
  [in, optional]  PVOID CompletionContext,
  [out, optional] PVOID ScatterGatherList
)
{...}

Parâmetros

[in] DmaAdapter

Um ponteiro para uma estrutura DMA_ADAPTER. Essa estrutura é o objeto do adaptador que representa o dispositivo DMA mestre do barramento do driver ou o canal DMA do sistema. O chamador obteve esse ponteiro de uma chamada anterior para a rotina de IoGetDmaAdapter .

[in] DeviceObject

Um ponteiro para uma estrutura DEVICE_OBJECT. Essa estrutura é o PDO (objeto de dispositivo físico) que representa o dispositivo de destino para a operação de DMA solicitada.

[in] DmaTransferContext

Um ponteiro para um contexto de transferência de DMA inicializado. Esse contexto foi inicializado por uma chamada anterior para a rotina de InitializeDmaTransferContext . Esse contexto deve ser exclusivo em todas as solicitações de alocação do adaptador. Para cancelar uma solicitação de alocação pendente, o chamador deve fornecer o contexto de transferência de DMA para a solicitação para a rotina de CancelAdapterChannel.

[in] Mdl

Um ponteiro para uma cadeia de MDL que descreve o layout de página física para uma coleção de buffers bloqueados na memória virtual. A lista de dispersão/coleta para a transferência de DMA usará a região dessa memória especificada pelos parâmetros de Deslocamento e Comprimento. Para obter mais informações sobre cadeias de MDL, consulte Usando MDLs.

[in] Offset

O deslocamento inicial para a transferência de DMA de dispersão/coleta. Esse parâmetro é um deslocamento de bytes desde o início do buffer no primeiro MDL na cadeia de MDL. Se os MDLs na cadeia de MDL especificarem um total de N bytes de espaço em buffer, os valores válidos de Deslocamento estarão no intervalo de 0 a N–1.

[in] Length

O tamanho, em bytes, da transferência de DMA. Se a cadeia de MDL especificar um total de N bytes de espaço em buffer, os valores válidos de Length estarão no intervalo de 1 a N–Deslocamento.

[in] Flags

Os sinalizadores de alocação do canal do adaptador. Há suporte para o seguinte sinalizador:

Se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido, o parâmetro ExecutionRoutine será opcional e poderá ser NULL. Se esse sinalizador não estiver definido, ExecutionRoutine deverá ser um ponteiro de NULL nãoválido. Para obter mais informações sobre esse sinalizador, consulte a seção Comentários.

[in, optional] ExecutionRoutine

Um ponteiro para a rotina de AdapterListControl fornecida pelo driver que inicia a transferência de DMA para o driver. O gerente de E/S chama a rotina AdapterListControl depois que os recursos necessários são alocados para o objeto do adaptador. Depois que a rotina AdapterListControl retorna, o gerenciador de E/S libera automaticamente o objeto do adaptador e os recursos que foram alocados para esse objeto.

Se o sinalizador de DMA_SYNCHRONOUS_CALLBACK estiver definido, ExecutionRoutine será opcional e poderá ser NULL. Se ExecutionRoutine for NULL, o chamador poderá usar os recursos alocados pelo BuildScatterGatherListEx. Para obter mais informações, consulte a seção Comentários.

[in, optional] Context

O contexto de controle do adaptador determinado pelo driver. Esse contexto é passado para a rotina AdapterListControl como o parâmetro Context.

[in] WriteToDevice

A direção da transferência de DMA. Defina esse parâmetro para TRUE para uma operação de gravação, que transfere dados da memória para o dispositivo. Defina esse parâmetro como FALSE para uma operação de leitura, que transfere dados do dispositivo para a memória.

[in] ScatterGatherBuffer

Um ponteiro para um buffer alocado pelo chamador no qual a rotina grava a lista de dispersão/coleta para a transferência de DMA. Essa lista começa com uma estrutura de SCATTER_GATHER_LIST, que é seguida por uma matriz de SCATTER_GATHER_ELEMENT.

[in] ScatterGatherLength

O tamanho, em bytes, do buffer passado no parâmetro ScatterGatherBuffer. O tamanho do buffer alocado deve ser grande o suficiente para conter a lista de dispersão/coleta, além de dados internos que o sistema operacional armazena nesse buffer. Para calcular o tamanho do buffer necessário, chame a rotina de GetDmaTransferInfo ou CalculateScatterGatherList.

[in, optional] DmaCompletionRoutine

Não usado. Definir como NULL.

[in, optional] CompletionContext

Não usado. Definir como NULL.

[out, optional] ScatterGatherList

Um ponteiro para uma variável na qual a rotina grava um ponteiro na lista de dispersão/coleta para a transferência de DMA. Essa lista começa com uma estrutura SCATTER_GATHER_LIST, que contém um ponteiro para uma matriz de SCATTER_GATHER_ELEMENT. Esse ponteiro de saída sempre corresponde ao valor do parâmetro ScatterGatherBuffer.

Se o sinalizador de DMA_SYNCHRONOUS_CALLBACK estiver definido e o parâmetro ExecutionRoutine for NULL, ScatterGatherList deverá ser um ponteiro null válido, não. Se executionRoutine não forNULL, ScatterGatherList será opcional e poderá ser NULL se o driver de chamada não exigir a lista de dispersão/coleta. A chamada BuildScatterGatherListEx falhará se o sinalizador DMA_SYNCHRONOUS_CALLBACK estiver definido e ScatterGatherList e executionRoutine estiverem NULL ou se o sinalizador DMA_SYNCHRONOUS_CALLBACK não estiver definido e ExecutionRoutine estiver NULL .

Valor de retorno

BuildScatterGatherListEx retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno de erro possíveis incluem os seguintes códigos de status.

Observações

BuildScatterGatherListEx* não é uma rotina do sistema que pode ser chamada diretamente pelo nome. Essa rotina pode ser chamada apenas pelo ponteiro do endereço retornado em uma estrutura deDMA_OPERATIONS* . Os drivers obtêm o endereço dessa rotina chamando IoGetDmaAdapter com o Version membro do parâmetro DeviceDescription definido como DEVICE_DESCRIPTION_VERSION3. Se IoGetDmaAdapter retornar NULL, a rotina não estará disponível em sua plataforma.

Use BuildScatterGatherListEx somente para adaptadores de barramento-mestre. Não use essa rotina para um adaptador DMA do sistema.

BuildScatterGatherListEx é semelhante à rotina de GetScatterGatherListEx , exceto pelo fato de exigir que o chamador aloque o buffer para a lista de dispersão/coleta.

Por exemplo, um driver pode pré-alocar um ou mais buffers de dispersão/coleta durante a inicialização do dispositivo. Posteriormente, uma chamada BuildScatterGatherListEx que usa esse buffer pode ter êxito em condições de baixa disponibilidade de memória que podem fazer com que uma chamada GetScatterGatherListEx falhe.

Por padrão, BuildScatterGatherListEx retorna de forma assíncrona, sem aguardar a conclusão da alocação de recursos solicitada. Após esse retorno, o chamador poderá, se necessário, cancelar a solicitação de alocação pendente chamando a rotina de CancelAdapterChannel de .

Se o driver de chamada definir o sinalizador DMA_SYNCHRONOUS_CALLBACK, a rotina BuildScatterGatherListEx se comportará da seguinte maneira:

• Se os recursos solicitados não estiverem disponíveis imediatamente, BuildScatterGatherListEx não aguardar recursos, não criará uma lista de dispersão/coleta e não chamará a rotina AdapterListControl. Em vez disso, BuildScatterGatherListEx falha e retorna STATUS_INSUFFICIENT_RESOURCES.

• O driver não será necessário para fornecer uma rotina de AdapterListControl se o sinalizador de DMA_SYNCHRONOUS_CALLBACK estiver definido.

• Se o driver fornecer uma rotina AdapterListControl , o sinalizador DMA_SYNCHRONOUS_CALLBACK indicará que essa rotina deve ser chamada no contexto do thread de chamada, antes que BuildScatterGatherListEx retorne.

• Se o driver não fornecer uma rotina de AdapterListControl , o driver poderá usar os recursos alocados e a lista de dispersão/coleta após BuildScatterGatherListEx retornar. Nesse caso, o driver deve fornecer um ponteiro de NULLNULL válido enão. Além disso, após a conclusão da transferência de DMA iniciada pelo driver, o driver deve chamar a rotina FreeAdapterObject para liberar os recursos que BuildScatterGatherListEx alocados para o objeto do adaptador.

BuildScatterGatherListEx é uma versão estendida da rotina de BuildScatterGatherList . A lista a seguir resume os recursos disponíveis apenas na versão estendida:

Requisitos

Consulte também

AdapterListControl

AllocateAdapterChannelEx

CalculateScatterGatherList

DMA_OPERATIONS

DmaCompletionRoutine

FreeAdapterObject

GetScatterGatherList

GetScatterGatherListEx

mapTransferEx