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

  • Artigo

Uma função de retorno de chamada de evento EvtSpbControllerIoSequence do driver SPB 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 de 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 retorno de chamada EvtSpbTargetConnect 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 erro status. 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.

Retornar valor

Nenhum

Comentários

O SpbCx gerencia a fila de E/S para o controlador SPB. O SpbCx chama a função de retorno de chamada EvtSpbControllerIoSequence do driver do controlador SPB quando um cliente (driver periférico) do controlador SPB envia uma solicitação de 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 status. Em vez disso, o driver do controlador SPB indica o status da operação de sequência na status de conclusão para a 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, em seguida, 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 AMD 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 declarar a linha device-select 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 status de E/S como 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 erro status código somente se ocorrer uma das seguintes condições:

  • 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 recebe um erro status 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 a encontrar erros e é um requisito para escrever drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtSpbControllerIoSequence chamada 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 a 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 para drivers KMDF. Para obter mais informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Com suporte a partir do Windows 8.
Plataforma de Destino Área de Trabalho
Cabeçalho spbcx.h
IRQL Chamado em IRQL <= DISPATCH_LEVEL.

Confira também