Função SerCx2SystemDmaReceiveCreate (sercx.h)

Artigo
08/07/2023

O método SerCx2SystemDmaReceiveCreate cria um objeto SerCx2 system-DMA-receive, que a versão 2 da extensão de 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 de 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 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 system-DMA-receive recém-criado. O SerCx2 e o driver do controlador serial usam esse identificador em chamadas subsequentes para fazer referência a esse objeto.

Retornar valor

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	Um objeto system-DMA-receive já existe de uma chamada serCx2SystemDmaReceiveCreate anterior; ou um objeto de recebimento personalizado já existe 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 pio-receive.
STATUS_INFO_LENGTH_MISMATCH	O valorTamanhoda-> Configuração não é igual a sizeof(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.

Comentários

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 de 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
Exclusive

Se necessário, o driver do controlador serial pode definir qualquer um desses membros como valores diferentes de zero após o retorno da função de inicialização. No entanto, para 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, 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, SerCx2 definirá o comprimento mínimo da transação como um byte.
Se Exclusivo for zero (FALSE), o modo exclusivo será desabilitado.

Se o driver de chamada definir Exclusivo como TRUE, os membros MinimumTransferUnitOverride, DmaAlignment e 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 as funções EvtSerCx2SystemDmaReceiveEnableNewDataNotification e EvtSerCx2SystemDmaReceiveCancelNewDataNotification .

Como opção, um driver de controlador serial pode usar o parâmetro Attributes para criar um contexto para o objeto system-DMA-receive e fornecer ponteiros para as funções EvtCleanupCallback e 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 nos membros ParentObject, ExecutionLevel e SynchronizationScope dessa estrutura.

Para obter mais informações sobre como criar objetos system-DMA-receive, consulte SERCX2SYSTEMDMARECEIVE. Para obter mais informações sobre transações de recebimento de DMA do sistema, consulte Transações sercx2 system-DMA-receive.