Solicitações de E/S do SPB

A macro CTL_CODE fornecida pelo sistema, descrita em Definindo códigos de controle de E/S, é usada para definir códigos de controle IOCTL_SPB_* no Spb.h.

IOCTL_SPB_EXECUTE_SEQUENCE código de controle

O código de controle de E/S IOCTL_SPB_EXECUTE_SEQUENCE permite que um cliente (driver periférico) do driver do controlador SPB execute uma sequência de transferências (leituras e gravações) como uma única operação atômica com uma solicitação de E/S. O dispositivo designado no barramento é o destino para todas as transferências na sequência.

Ao especificar uma sequência de transferências de comprimento fixo como uma única operação atômica, a solicitação de controle de E/S IOCTL_SPB_EXECUTE_SEQUENCE permite que o driver do controlador otimize as transferências de E/S e melhore o desempenho.

O cliente envia essa solicitação de controle de E/S para o objeto de arquivo para o dispositivo de destino.

Um driver de controlador SPB registra uma função de retorno de chamada EvtSpbControllerIoSequence para executar as transferências de barramento para uma sequência de transferência de E/S. A extensão de estrutura SPB (SpbCx) chama essa função para passar uma solicitação IOCTL_SPB_EXECUTE_SEQUENCE para o driver do controlador SPB para processamento.

IOCTL_SPB_EXECUTE_SEQUENCE buffer de entrada

O buffer de entrada é uma estrutura SPB_TRANSFER_LIST, que contém uma lista de ponteiros para os buffers de dados do cliente. Esta lista contém um buffer de dados para cada transferência (leitura ou gravação) na sequência de transferência de E/S.

IOCTL_SPB_EXECUTE_SEQUENCE comprimento do buffer de entrada

O tamanho de uma estrutura SPB_TRANSFER_LIST.

bloco IOCTL_SPB_EXECUTE_SEQUENCE status

Se a operação for bem-sucedida, o driver do controlador definirá o membro Status como STATUS_SUCCESS e definirá o membro Information como o número total de bytes transferidos durante a sequência.

Essa operação pode falhar por vários motivos, que podem incluir poucos recursos, entrada de cliente inválida e mau funcionamento do dispositivo.

Se o driver do controlador começar a processar a solicitação de E/S, mas ocorrer um erro durante uma das transferências na sequência (por exemplo, o dispositivo de destino sinalizará uma NACK para recusar a transferência), o driver do controlador anulará as transferências restantes na sequência. Em seguida, o driver define a status de conclusão como STATUS_SUCCESS, define o membro Information como o número de bytes que foram transferidos com êxito antes do erro ocorrer e conclui a solicitação.

IOCTL_SPB_FULL_DUPLEX código de controle

O código de controle IOCTL_SPB_FULL_DUPLEX é usado por um cliente (driver periférico) para solicitar uma operação de E/S de duplex completo. As operações de E/S de duplex completo têm suporte de controladores para barramentos como SPI que podem ler e gravar dados simultaneamente. A macro CTL_CODE fornecida pelo sistema, descrita em Definindo códigos de controle de E/S, é usada para definir IOCTL_SPB_FULL_DUPLEX da seguinte maneira.

O driver do modo de usuário ou o driver do modo kernel para um dispositivo no barramento envia essa solicitação de controle de E/S para o objeto de arquivo para o dispositivo de destino.

Esse IOCTL tem suporte apenas por drivers de controlador SPB para ônibus, como SPI, que podem ler e gravar dados simultaneamente.

Os buffers de gravação e leitura para a transferência de duplex completo são descritos por uma estrutura SPB_TRANSFER_LIST. Essa estrutura deve usar o seguinte formato:

• A matriz de estruturas de SPB_TRANSFER_LIST_ENTRY contém exatamente dois elementos. O primeiro elemento descreve o buffer de gravação (Direction = SpbTransferDirectionToDevice). O segundo elemento descreve o buffer de leitura (Direction = SpbTransferDirectionFromDevice).

• Os membros DelayInUs das duas estruturas SPB_TRANSFER_LIST_ENTRY devem ser zero. Os formatos de buffer para o buffer de gravação e o buffer de leitura podem ser qualquer um dos seguintes:

  • SpbTransferBufferFormatSimple
  • SpbTransferBufferFormatList
  • SpbTransferBufferFormatSimpleNonPaged
  • SpbTransferBufferFormatMdl

  Os dois últimos formatos na lista anterior só podem ser usados por clientes do modo kernel. Os formatos dos buffers de gravação e leitura não precisam ser os mesmos. Para obter mais informações sobre esses formatos de buffer, consulte SPB_TRANSFER_BUFFER_FORMAT.

Uma operação bem-sucedida pode definir o membro Informações como um valor menor que a soma dos tamanhos do buffer de gravação e do buffer de leitura, que pode ocorrer se a solicitação for cancelada ou se a operação não puder gravar o conteúdo completo do buffer de gravação no dispositivo ou preencher completamente o buffer de leitura com dados lidos do dispositivo.

Os tamanhos de buffer de gravação e leitura não são necessários para serem os mesmos. Se o buffer de gravação for maior que o buffer de leitura, a operação continuará gravando dados do buffer de gravação depois que o buffer de leitura estiver cheio. Se o buffer de leitura for maior que o buffer de gravação, a operação continuará a preencher o buffer de leitura depois que o buffer de gravação for esvaziado.

Se um driver de controlador SPB registrar uma função de retorno de chamada EvtSpbControllerIoOther, a extensão de estrutura do SPB (SpbCx) chamará essa função para passar uma solicitação IOCTL_SPB_FULL_DUPLEX para o driver do controlador SPB para processamento. O SpbCx não executa nenhuma verificação de parâmetro, validação de lista de transferência ou outro processamento para uma solicitação de IOCTL_SPB_FULL_DUPLEX.

Para obter mais informações sobre como um driver de controlador SPB implementa o suporte para esse IOCTL, consulte Tratamento de solicitações de IOCTL_SPB_FULL_DUPLEX.

IOCTL_SPB_FULL_DUPLEX buffer de entrada

Um ponteiro para uma estrutura SPB_TRANSFER_LIST que contém ponteiros para os buffers de dados de entrada e saída do cliente. Essa estrutura contém uma matriz Transfers de exatamente dois elementos. O primeiro elemento descreve o buffer que contém os dados a serem gravados no dispositivo. O segundo elemento descreve o buffer usado para manter os dados lidos do dispositivo. Para obter mais informações sobre como um driver de controlador SPB implementa uma solicitação de controle de E/S personalizado (IOCTL) que usa estruturas SPB_TRANSFER_LIST para descrever buffers, consulte Usando a estrutura de SPB_TRANSFER_LIST para IOCTLs personalizados.

IOCTL_SPB_FULL_DUPLEX comprimento do buffer de entrada

O tamanho de uma estrutura SPB_TRANSFER_LIST.

bloco IOCTL_SPB_FULL_DUPLEX status

Se a operação for bem-sucedida, o driver do controlador definirá o membro Status como STATUS_SUCCESS e definirá o membro Information como o número total de bytes transferidos (bytes lidos mais bytes gravados) durante a operação full-duplex.

Essa operação pode falhar por vários motivos, que podem incluir poucos recursos, entrada de cliente inválida e mau funcionamento do dispositivo.

IOCTL_SPB_LOCK_CONNECTION código de controle

O código de controle IOCTL_SPB_LOCK_CONNECTION é usado por um cliente (driver periférico) para adquirir o bloqueio de conexão em um dispositivo de destino conectado a SPB compartilhado com outro cliente. Enquanto um cliente mantém o bloqueio de conexão, esse cliente tem acesso exclusivo ao dispositivo. A macro CTL_CODE fornecida pelo sistema, descrita em Definindo códigos de controle de E/S, é usada para definir IOCTL_SPB_LOCK_CONNECTION da seguinte maneira.

As solicitações de IOCTL_SPB_LOCK_CONNECTION e IOCTL_SPB_UNLOCK_CONNECTION adquirem e liberam o bloqueio de conexão em um dispositivo de destino anexado a um barramento periférico simples. A maioria dos clientes não usa essas solicitações de controle de E/S. Essas solicitações serão usadas somente se dois clientes compartilharem acesso ao mesmo dispositivo de destino. Para obter mais informações, consulte Bloqueios de conexão do SPB.

Dois clientes podem abrir conexões lógicas separadas para o mesmo dispositivo de destino e usar o bloqueio de conexão quando um dos clientes exigir acesso exclusivo ao dispositivo. Quando um cliente mantém o bloqueio, as solicitações de E/S para o dispositivo do segundo cliente são adiadas automaticamente até que o primeiro cliente libere o bloqueio.

Um cliente pode manter simultaneamente um bloqueio de conexão no dispositivo de destino e um bloqueio do controlador no controlador SPB. As solicitações de IOCTL_SPB_LOCK_CONTROLLER e IOCTL_SPB_UNLOCK_CONTROLLER adquirem e liberam o bloqueio do controlador. O cliente deve adquirir o bloqueio de conexão antes de adquirir o bloqueio do controlador e deve liberar o bloqueio do controlador antes de liberar o bloqueio de conexão. Um cliente usa um bloqueio do controlador para executar um conjunto ordenado de transferências de barramento (operações de leitura e gravação) como uma única operação de barramento atômico. Para obter mais informações, consulte Sequências de transferência de E/S.

Um bloqueio de conexão será encerrado automaticamente se uma solicitação IRP_MJ_CLEANUP for enviada para um dispositivo de destino enquanto a conexão estiver bloqueada no dispositivo. Uma solicitação de limpeza é enviada para um dispositivo de destino quando um cliente fecha seu identificador de arquivo para o dispositivo.

bloco IOCTL_SPB_LOCK_CONNECTION status

Se a operação for bem-sucedida, o membro Status será definido como STATUS_SUCCESS.

Se a operação falhar, o membro Status será definido como um erro apropriado status código.

Se o cliente já tiver o bloqueio de conexão no dispositivo de destino ou o bloqueio do controlador no controlador SPB, essa operação falhará com Status = STATUS_INVALID_DEVICE_REQUEST. Essa operação pode falhar por outros motivos, que podem incluir poucos recursos, entrada de cliente inválida e mau funcionamento do dispositivo.

IOCTL_SPB_LOCK_CONTROLLER código de controle

O código de controle IOCTL_SPB_LOCK_CONTROLLER é usado por um cliente (driver periférico) para bloquear o controlador SPB. Enquanto o controlador está bloqueado, o cliente tem uso exclusivo do barramento para acessar o dispositivo de destino especificado para o bloqueio. A macro CTL_CODE fornecida pelo sistema, descrita em Definindo códigos de controle de E/S, é usada para definir IOCTL_SPB_LOCK_CONTROLLER da seguinte maneira.

Para obter o uso exclusivo do barramento para acessar um dispositivo de destino, um cliente (driver periférico) envia esse IOCTL para o objeto de arquivo para o destino. Depois que esse IOCTL for concluído, o controlador será bloqueado e todas as transferências de E/S (leitura ou gravação) no barramento acessarão o destino designado. Entre transferências, o controlador mantém o dispositivo de destino selecionado, mas interrompe o relógio.

O controlador permanece bloqueado até que o cliente envie uma solicitação IOCTL_SPB_UNLOCK_CONTROLLER para desbloquear o controlador. Quando a sequência de transferências do cliente de ou para o dispositivo de destino for concluída, o cliente deverá desbloquear o controlador para que o controlador possa processar solicitações de E/S para outros destinos no barramento.

Um bloqueio será encerrado automaticamente se uma solicitação IRP_MJ_CLEANUP for enviada para um dispositivo de destino enquanto o controlador estiver bloqueado no destino. Uma solicitação de limpeza é enviada para um destino quando um cliente fecha seu identificador para o destino.

Os controladores SPB não são necessários para dar suporte a solicitações de IOCTL_SPB_LOCK_CONTROLLER e IOCTL_SPB_UNLOCK_CONTROLLER, e os drivers de dispositivo periféricos não devem assumir que têm suporte.

Se um driver de controlador SPB registrar uma função de retorno de chamada EvtSpbControllerLock, a extensão da estrutura SPB (SpbCx) chamará essa função para passar uma solicitação IOCTL_SPB_LOCK_CONTROLLER para o driver do controlador SPB para processamento.

bloco IOCTL_SPB_LOCK_CONTROLLER status

Se a operação for bem-sucedida, o membro Status será definido como STATUS_SUCCESS. Esse IOCTL pode retornar um erro status por vários motivos, incluindo falha ao configurar o controlador para operar no modo de acesso exclusivo. Nesse modo, o controlador mantém o dispositivo de destino selecionado para que ele seja o destino exclusivo para todas as transferências de E/S no barramento. O controlador permanece nesse modo até ser desbloqueado.

IOCTL_SPB_UNLOCK_CONNECTION código de controle

O código de controle de E/S IOCTL_SPB_UNLOCK_CONNECTION é usado por um cliente (driver periférico) para liberar o bloqueio de conexão em um dispositivo de destino conectado a SPB que é compartilhado com outro cliente. O cliente enviou anteriormente uma solicitação IOCTL_SPB_LOCK_CONNECTION para adquirir acesso exclusivo ao dispositivo.

As solicitações IOCTL_SPB_LOCK_CONNECTION e IOCTL_SPB_UNLOCK_CONNECTION adquirem e liberam o bloqueio de conexão em um dispositivo de destino anexado a um barramento periférico simples. A maioria dos clientes não usa essas solicitações de controle de E/S. Essas solicitações serão usadas somente se dois clientes compartilharem acesso ao mesmo dispositivo de destino. Para obter mais informações, consulte Bloqueios de conexão do SPB.

Depois que um cliente (driver periférico) envia uma solicitação de IOCTL_SPB_LOCK_CONNECTION para um dispositivo de destino no barramento e a solicitação é concluída com êxito, a conexão permanece bloqueada até que o cliente envie uma solicitação IOCTL_SPB_UNLOCK_CONNECTION para desbloquear a conexão.

O cliente envia uma solicitação IOCTL_SPB_UNLOCK_CONNECTION para liberar o bloqueio de conexão para o dispositivo de destino quando o cliente não exigir mais acesso exclusivo ao dispositivo. A conexão deve ser desbloqueada para que o outro cliente possa acessar o dispositivo.

bloco IOCTL_SPB_UNLOCK_CONNECTION status

Se a operação for bem-sucedida, o membro Status será definido como STATUS_SUCCESS.

Se a operação falhar, o membro Status será definido como um erro apropriado status código. Se o cliente não mantiver o bloqueio de conexão no dispositivo de destino ou se o cliente ainda mantiver o bloqueio de conexão no controlador SPB, essa operação falhará com Status = STATUS_INVALID_DEVICE_REQUEST. Essa operação pode falhar por outros motivos, que podem incluir poucos recursos, entrada inválida do cliente e mau funcionamento do dispositivo.

código de controle IOCTL_SPB_UNLOCK_CONTROLLER

O código de controle de E/S IOCTL_SPB_UNLOCK_CONTROLLER é usado por um cliente (driver periférico) para desbloquear o controlador SPB. O cliente bloqueou anteriormente o controlador para obter uso exclusivo do barramento para acessar um dispositivo de destino no barramento.

Depois que um cliente (driver periférico) envia uma solicitação de controle de E/S IOCTL_SPB_LOCK_CONTROLLER para um dispositivo de destino no barramento, o controlador permanece bloqueado até que o cliente envie uma solicitação de controle de E/S IOCTL_SPB_UNLOCK_CONTROLLER para desbloquear o controlador. O cliente envia essas solicitações de controle de E/S para o objeto de arquivo para o dispositivo de destino.

O cliente envia uma solicitação de IOCTL_SPB_UNLOCK_CONTROLLER quando conclui uma sequência de transferências no barramento e deseja liberar o dispositivo de destino. O controlador deve ser desbloqueado para que possa processar solicitações de E/S para outros destinos no barramento.

Os controladores SPB não são necessários para dar suporte a solicitações de IOCTL_SPB_LOCK_CONTROLLER e IOCTL_SPB_UNLOCK_CONTROLLER, e os drivers de dispositivo periféricos não devem assumir que têm suporte.

A extensão da estrutura SPB (SpbCx) chama a função de retorno de chamada EvtSpbControllerUnlock opcional do driver do controlador SPB para passar uma solicitação de IOCTL_SPB_LOCK_CONTROLLER para o driver do controlador SPB para processamento.

bloco IOCTL_SPB_UNLOCK_CONTROLLER status

Se a operação for bem-sucedida, o membro Status será definido como STATUS_SUCCESS.

Essa IOCTL só poderá falhar se for enviada por um cliente que não tenha o controlador bloqueado para acesso exclusivo ao destino designado.