Partilhar via


EVT_SPB_CONTROLLER_SEQUENCE função de retorno de chamada (spbcx.h)

Uma função de retorno de chamada de evento do driver de controlador SPB EvtSpbControllerIoSequence executa uma sequência de transferências de dados entre o dispositivo de destino especificado e os buffers fornecidos com a solicitação de sequência.

Sintaxe

EVT_SPB_CONTROLLER_SEQUENCE EvtSpbControllerSequence;

void EvtSpbControllerSequence(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target,
  [in] SPBREQUEST Request,
  [in] ULONG TransferCount
)
{...}

Parâmetros

[in] Controller

Um identificador WDFDEVICE para o objeto de dispositivo da estrutura que representa o controlador SPB.

[in] Target

Um identificador SPBTARGET para o destino dessa solicitação de E/S. O destino é um dispositivo periférico ou uma porta anexada ao barramento. A extensão da estrutura SPB (SpbCx) atribuiu anteriormente esse identificador ao destino no EvtSpbTargetConnect retorno de chamada que abriu a conexão com o destino.

[in] Request

O identificador SPBREQUEST para a solicitação de E/S. O driver do controlador SPB deve concluir essa solicitação executando a operação solicitada ou retornando um status de erro. Para obter mais informações, consulte Comentários.

[in] TransferCount

O número de transferências individuais nesta sequência de transferência de E/S. Cada transferência individual é uma operação simples de leitura ou gravação.

Valor de retorno

Nenhum

Observações

O SpbCx gerencia a fila de E/S para o controlador SPB. O SpbCx chama a função de retorno de chamada do driver do controlador SPB EvtSpbControllerIoSequence quando um cliente (driver periférico) do controlador SPB envia uma solicitação IOCTL_SPB_EXECUTE_SEQUENCE para um dispositivo de destino anexado ao barramento. O valor do parâmetro Request é um identificador que encapsula essa solicitação.

Um retorno de chamada EvtSpbControllerIoSequence não retorna um valor de status. Em vez disso, o driver do controlador SPB indica o status da operação de sequência no status de conclusão da solicitação de E/S.

Um retorno de chamada EvtSpbControllerIoSequence é assíncrono. Ou seja, a função de retorno de chamada deve iniciar a operação de sequência solicitada (ou a primeira parte da sequência) e retornar sem aguardar a conclusão da operação. Posteriormente, o driver do controlador SPB continua processando a solicitação ou a conclui durante DPCs de interrupção ou DPCs de temporizador.

O driver do controlador SPB pode recuperar os valores de parâmetro da solicitação de E/S para determinar o comprimento máximo das transferências dentro da sequência. O driver pode usar esse comprimento para alocar recursos de DMA que podem ser reutilizados para cada transferência dentro da sequência.

O driver do controlador SPB pode chamar o método SpbRequestGetTransferParameters para recuperar os parâmetros de controle e o buffer de dados para cada transferência na sequência. O buffer é um objeto WDFMEMORY que, na implementação atual, encapsula um MDL encadeado. Para obter mais informações sobre MDLs encadeados, consulte Usando MDLs.

O controlador SPB deve manter o dispositivo de destino selecionado para toda a operação de sequência. Se o destino for selecionado por uma linha de seleção de dispositivo, a linha poderá ser declarada continuamente desde o início da primeira transferência na sequência até que a última transferência termine. Essa linha pode ser declarada tão cedo quanto a operação de bloqueio no início da sequência e pode permanecer declarada até a operação de desbloqueio no final da sequência.

Um atraso opcional pode ser especificado para cada transferência em uma sequência. O driver do controlador SPB é responsável por atrasar pelo menos esse número de microssegundos antes de iniciar a transferência. Se a primeira transferência na sequência tiver um atraso associado, o driver deverá primeiro transmitir o endereço ou afirmar a linha de seleção de dispositivo do dispositivo de destino e, em seguida, atrasar o tempo especificado antes de iniciar a transferência de dados. Durante esse atraso, o destino deve permanecer selecionado, mas o controlador não deve executar o relógio no barramento.

Se o dispositivo de destino sinalizar um NACK durante uma transferência em uma sequência, o controlador SPB interromperá a sequência. (Ou seja, o controlador não tenta novamente a transferência com falha e não tenta executar as transferências restantes na sequência.) Se isso ocorrer, o driver do controlador SPB deverá definir o status de conclusão da solicitação de E/S para STATUS_SUCCESS, definir o campo Informações no bloco de status de E/S para o número de bytes realmente transferidos (sem contar os dados perdidos na transferência que recebeu o NACK) e concluir a solicitação.

O driver do controlador SPB deve concluir a solicitação de E/S com um código de status de erro somente se uma das seguintes condições ocorrer:

  • O controlador SPB não pode selecionar o dispositivo de destino (por exemplo, um dispositivo de destino em um barramento I2C sinaliza um NACK quando o controlador transmite o byte de endereço).
  • O driver do controlador SPB obtém um status de erro de uma chamada para um serviço WDF ou WDM durante o processamento da operação de sequência.

Para registrar uma função de retorno de chamada EvtSpbControllerIoSequence, chame o método SpbDeviceInitialize.

Exemplos

Para definir uma função de retorno de chamada EvtSpbControllerIoSequence, primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a análise de código para drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtSpbControllerIoSequence denominada MyEvtSpbControllerIoSequence, use o tipo de função EVT_SPB_CONTROLLER_SEQUENCE, conforme mostrado neste exemplo de código:

EVT_SPB_CONTROLLER_SEQUENCE  MyEvtSpbControllerIoSequence;

Em seguida, implemente sua função de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
VOID
  MyEvtSpbControllerIoSequence(
    WDFDEVICE Controller,
    SPBTARGET Target,
    SPBREQUEST Request,
    ULONG TransferCount
    )
{ ... }

O tipo de função EVT_SPB_CONTROLLER_SEQUENCE é definido no arquivo de cabeçalho Spbcx.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função EVT_SPB_CONTROLLER_SEQUENCE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers KMDF. Para obter mais informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito Valor
de cliente com suporte mínimo Com suporte a partir do Windows 8.
da Plataforma de Destino Área de trabalho
cabeçalho spbcx.h
IRQL Chamado no <DO IRQL = DISPATCH_LEVEL.

Consulte também