Função SerCx2SystemDmaReceiveCreate (sercx.h)

Artigo
10/30/2024

O método SerCx2SystemDmaReceiveCreate cria um objeto serCx2 system-DMA-receive, que a versão 2 da extensão da estrutura serial (SerCx2) usa para executar transações de recebimento de DMA do sistema.

Sintaxe

NTSTATUS SerCx2SystemDmaReceiveCreate(
  [in]           WDFDEVICE                         Device,
  [in]           PSERCX2_SYSTEM_DMA_RECEIVE_CONFIG SystemDmaReceiveConfig,
  [in, optional] PWDF_OBJECT_ATTRIBUTES            Attributes,
  [out]          SERCX2SYSTEMDMARECEIVE            *SystemDmaReceive
);

Parâmetros

[in] Device

Um identificador WDFDEVICE para o objeto de dispositivo da estrutura que representa o controlador serial. O driver do controlador serial criou esse objeto em sua função de retorno de chamada EvtDriverDeviceAdd. Para obter mais informações, consulte SerCx2InitializeDevice.

[in] SystemDmaReceiveConfig

Um ponteiro para uma estrutura SERCX2_SYSTEM_DMA_RECEIVE_CONFIG. Antes de chamar esse método, o chamador deve chamar a função SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT ou SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION para inicializar a estrutura. Essa estrutura contém ponteiros para um conjunto de rotinas de retorno de chamada de evento que são implementadas pelo driver do controlador serial. O SerCx2 chama essas funções para executar transações de recebimento de DMA do sistema.

[in, optional] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que descreve os atributos a serem atribuídos ao novo objeto system-DMA-receive. Antes de chamar esse método, o chamador deve chamar a função WDF_OBJECT_ATTRIBUTES_INIT para inicializar a estrutura. Esse parâmetro é opcional e pode ser especificado como WDF_NO_OBJECT_ATTRIBUTES se o driver do controlador serial não precisar atribuir atributos ao objeto. Para obter mais informações, consulte Comentários.

[out] SystemDmaReceive

Um ponteiro para um local no qual esse método grava um identificador de SERCX2SYSTEMDMARECEIVE no objeto de recebimento system-DMA recém-criado. O SerCx2 e o driver do controlador serial usam esse identificador em chamadas subsequentes para fazer referência a esse objeto.

Valor de retorno

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

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	Já existe um objeto system-DMA-receive de uma chamada SerCx2SystemDmaReceiveCreate anterior; ou já existe um objeto de recebimento personalizado de uma chamada anterior para o método SerCx2CustomReceiveCreate; ou existe um objeto de transmissão personalizada de uma chamada anterior para o método SerCx2CustomTransmitCreate; ou SerCx2PioReceiveCreate ainda não foi chamado para criar um objeto de recebimento de PIO.
STATUS_INFO_LENGTH_MISMATCH	O valor tamanho dode configuração de não é igual ao tamanho de(SERCX2_SYSTEM_DMA_RECEIVE_CONFIG).
STATUS_INVALID_PARAMETER	Um valor de parâmetro não é válido.
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes estão disponíveis para executar a operação solicitada.

Observações

Esse método é chamado pelo driver do controlador serial para criar um objeto system-DMA-receive. O SerCx2 usa esse objeto para executar transações de recebimento de DMA do sistema, que são transações de E/S que usam o controlador DMA do sistema para ler os dados recebidos pelo controlador serial.

Normalmente, um driver de controlador serial chama SerCx2SystemDmaReceiveCreate de sua função de retorno de chamada EvtDevicePrepareHardware. Essa função recebe uma lista de recursos de hardware, que podem incluir canais de DMA do sistema.

Um driver de controlador serial deve chamar com êxito os métodos SerCx2InitializeDevice e SerCx2PioReceiveCreate antes de chamar SerCx2SystemDmaReceiveCreate.

Antes de chamar SerCx2SystemDmaReceiveCreate, o driver do controlador serial deve chamar a função SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT ou SERCX2_SYSTEM_DMA_RECEIVE_CONFIG_INIT_NEW_DATA_NOTIFICATION para inicializar a estrutura de SERCX2_SYSTEM_DMA_RECEIVE_CONFIG apontada por SystemDmaReceiveConfig. Essas funções definem os seguintes membros da estrutura como zero:

MaximumScatterGatherFragments
MinimumTransferUnitOverride
DmaAlignment
MinimumTransactionLength
Exclusivo

Se necessário, o driver do controlador serial pode definir qualquer um desses membros como valores não zero após o retorno da função de inicialização. No entanto, por conveniência, SerCx2SystemDmaReceiveCreate usará os seguintes valores padrão se esses membros forem zero:

Se MaximumScatterGatherFragments for zero, SerCx2 definirá o número máximo de elementos em uma lista de dispersão/coleta como ((ULONG)-1).
Se MinimumTransferUnitOverride for zero, o SerCx2 definirá a unidade de transferência mínima como seu valor padrão, que é especificado na estrutura DMA_ADAPTER para o controlador DMA do sistema. Para obter mais informações sobre essa estrutura, consulte WdfDmaEnablerWdmGetDmaAdapter.
Se DmaAlignment for zero, SerCx2 definirá o valor de alinhamento como a unidade de transferência mínima. Se MinimumTransferUnitOverride for zero, a unidade de transferência mínima padrão será usada.
Se MinimumTransactionLength for zero, o SerCx2 definirá o comprimento mínimo da transação como um byte.
Se Exclusiva for zero (FALSE), o modo exclusivo será desabilitado.

Se o driver de chamada definir Exclusivo para TRUE, os membros MinimumTransferUnitOverride, DmaAlignmente MinimumTransactionLength deverão ser zero. Para obter mais informações, consulte SERCX2_SYSTEM_DMA_RECEIVE_CONFIG.

Se a combinação especificada de funções de retorno de chamada implementadas não for válida, SerCx2SystemDmaReceiveCreate falhará e retornará STATUS_INVALID_PARAMETER. O driver deve implementar o ou nenhum dos EvtSerCx2SystemDmaReceiveEnableNewDataNotification e funções EvtSerCx2SystemDmaReceiveCancelNewDataNotification.

Como opção, um driver de controlador serial pode usar o parâmetro Attributes para criar um contexto para o objeto de recebimento de DMA do sistema e fornecer ponteiros para EvtCleanupCallback e funções EvtDestroyCallback que são chamadas para preparar o objeto para exclusão. Para obter mais informações, consulte WDF_OBJECT_ATTRIBUTES.

Se o parâmetro Attributes apontar para uma estrutura WDF_OBJECT_ATTRIBUTES, o chamador não deverá substituir os valores que a função de inicialização WDF_OBJECT_ATTRIBUTES_INIT grava no ParentObject, ExecutionLevele SynchronizationScope membros dessa estrutura.

Para obter mais informações sobre como criar objetos de recebimento de DMA do sistema, consulte SERCX2SYSTEMDMARECEIVE. Para obter mais informações sobre transações de recebimento de DMA do sistema, consulte de Transações deDMA-Receive do Sistema SerCx2.