Função SerCx2CustomTransmitCreate (sercx.h)

Artigo
10/30/2024

O método SerCx2CustomTransmitCreate cria um objeto de transmissão personalizada, que a versão 2 da extensão da estrutura serial (SerCx2) usa para gravar dados de transmissão no controlador serial por meio de um mecanismo de transferência de dados personalizado.

Sintaxe

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

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] CustomTransmitConfig

Um ponteiro para uma estrutura SERCX2_CUSTOM_TRANSMIT_CONFIG. Antes de chamar esse método, o chamador deve chamar a função SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 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 transmissão personalizada.

[in] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que descreve os atributos a serem atribuídos ao novo objeto de transmissão personalizada. 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] CustomTransmit

Um ponteiro para um local no qual esse método grava um identificador de SERCX2CUSTOMTRANSMIT no objeto de transmissão personalizada 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 de transmissão personalizada de uma chamada SerCx2CustomTransmitCreate anterior; ou existe um objeto system-DMA-transmit de uma chamada SerCx2SystemDmaTransmitCreate anterior; ou existe um objeto system-DMA-transmit de uma chamada serCx2SystemDmaTransmitCreate anterior; ou SerCx2PioTransmitCreate ainda não foi chamado para criar um objeto de transmissão PIO.
STATUS_INVALID_PARAMETER	Um valor de parâmetro não é válido.
STATUS_INFO_LENGTH_MISMATCH	O valor tamanho dode configuração de não é igual ao tamanho de(SERCX2_CUSTOM_TRANSMIT_CONFIG).
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes estão disponíveis para criar o objeto de transmissão personalizada.

Observações

Esse método é chamado pelo driver do controlador serial para criar um objeto de transmissão personalizada. O SerCx2 usa esse objeto para executar transações de transmissão personalizada, que são transações que usam um mecanismo de transferência de dados personalizado para gravar dados de transmissão no controlador serial.

Um driver de controlador serial deve chamar com êxito os métodos SerCx2InitializeDevice e SerCx2PioTransmitCre ate antes de chamar SerCx2CustomTransmitCreate.

Antes de chamar SerCx2CustomTransmitCreate, o driver do controlador serial deve chamar a função SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT para inicializar a estrutura de SERCX2_CUSTOM_TRANSMIT_CONFIG apontada por CustomTransmitConfig. Essa função define os seguintes membros da estrutura como zero:

de Alinhamento
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit
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, SerCx2CustomTransmitCreate usará os seguintes valores padrão se esses membros forem zero:

Se Alinhamento for zero, o SerCx2 definirá o valor de alinhamento de dados como um, o que significa que o buffer de gravação pode iniciar em um limite de bytes arbitrário na memória.
Se MinimumTransactionLength for zero, o SerCx2 definirá o comprimento mínimo da transação como um byte.
Se MaximumTransactionLength for zero, SerCx2 definirá o comprimento máximo da transação como ((ULONG)-1).
Se MinimumTransferUnit for zero, o SerCx2 definirá a unidade de transferência mínima como um byte.
Se Exclusiva for zero (FALSE), o modo exclusivo será desabilitado.

Se o driver de chamada definir Exclusivo para TRUE, os membros MinimumTransferUnit, Alignmente MinimumTransactionLength devem ser zero. Para obter mais informações, consulte SERCX2_CUSTOM_TRANSMIT_CONFIG.

Como opção, um driver de controlador serial pode usar o parâmetro Attributes para criar um contexto para o objeto de transmissão personalizada e fornecer ponteiros para EvtCleanupCallback e EvtDestroyCallback funções 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 transmissão personalizada, consulte SERCX2CUSTOMTRANSMIT. Para obter mais informações sobre transações de transmissão personalizada, consulte transações de Custom-Transmit SerCx2.