Função SerCx2SystemDmaTransmitCreate (sercx.h)
O método SerCx2SystemDmaTransmitCreate cria um objeto SerCx2 system-DMA-transmit, que a versão 2 da extensão de estrutura serial (SerCx2) usa para executar transações de transmissão de DMA do sistema.
Sintaxe
NTSTATUS SerCx2SystemDmaTransmitCreate(
[in] WDFDEVICE Device,
[in] PSERCX2_SYSTEM_DMA_TRANSMIT_CONFIG SystemDmaTransmitConfig,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] SERCX2SYSTEMDMATRANSMIT *SystemDmaTransmit
);
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] SystemDmaTransmitConfig
Um ponteiro para uma estrutura SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG . Antes de chamar esse método, o chamador deve chamar a função SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT 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 transmissão 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-transmit. 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] SystemDmaTransmit
Um ponteiro para um local no qual esse método grava um identificador SERCX2SYSTEMDMATRANSMIT no objeto system-DMA-transmit 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 |
---|---|
|
Já existe um objeto system-DMA-transmit de uma chamada SerCx2SystemDmaTransmitCreate anterior; ou existe um objeto de transmissão personalizada de uma chamada anterior para o método SerCx2CustomTransmitCreate ; ou existe um objeto de recebimento personalizado de uma chamada anterior para o método SerCx2CustomReceiveCreate ; ou SerCx2PioTransmitCreate ainda não foi chamado para criar um objeto de transmissão de PIO. |
|
O valorTamanhoda Configuração-> não é igual a sizeof(SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG). |
|
Um valor de parâmetro não é válido. |
|
Recursos insuficientes estão disponíveis para criar o objeto system-DMA-transmit. |
Comentários
O driver do controlador serial pode criar um objeto system-DMA-transmit. O SerCx2 usa esse objeto para executar transações de transmissão de DMA do sistema, que são transações que usam o controlador DMA do sistema para gravar dados no controlador serial a serem transmitidos.
Normalmente, um driver de controlador serial chama SerCx2SystemDmaTransmitCreate 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.
O driver do controlador serial deve chamar com êxito os métodos SerCx2InitializeDevice e SerCx2PioTransmitCreate antes de chamar SerCx2SystemDmaTransmitCreate.
Antes de chamar SerCx2SystemDmaTransmitCreate, o driver do controlador serial deve chamar a função SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG_INIT para inicializar a estrutura de SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG apontada por SystemDmaTransmitConfig. Essa função define os seguintes membros da estrutura como zero:
- MaximumScatterGatherFragments
- MinimumTransferUnitOverride
- DmaAlignment
- MinimumTransactionLength
- Exclusive
- 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 a combinação especificada de funções de retorno de chamada implementadas não for válida, SerCx2SystemDmaTransmitCreate falhará e retornará STATUS_INVALID_PARAMETER. O driver deve implementar todos os três ou nenhum das funções EvtSerCx2SystemDmaTransmitDrainFifo, EvtSerCx2SystemDmaTransmitCancelDrainFifo e EvtSerCx2SystemDmaTransmitPurgeFifo .
Como opção, um driver de controlador serial pode usar o parâmetro Attributes para criar um contexto para o objeto system-DMA-transmit e para 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 de transmissão de DMA do sistema, consulte SERCX2SYSTEMDMATRANSMIT. Para obter mais informações sobre transações de transmissão de DMA do sistema, consulte Transações de Transmissão de Sistema-DMA-SerCx2.
Requisitos
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Disponível a partir do Windows 8.1. |
Plataforma de Destino | Universal |
Cabeçalho | sercx.h |
IRQL | PASSIVE_LEVEL |
Confira também
EvtSerCx2SystemDmaTransmitCancelDrainFifo
EvtSerCx2SystemDmaTransmitCleanupTransaction
EvtSerCx2SystemDmaTransmitDrainFifo
EvtSerCx2SystemDmaTransmitInitializeTransaction
EvtSerCx2SystemDmaTransmitPurgeFifo
SERCX2_SYSTEM_DMA_TRANSMIT_CONFIG
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de