IOCTL_ATA_PASS_THROUGH IOCTL (ntddscsi.h)

  • Artigo

Permite que um aplicativo envie quase qualquer comando do ATA para um dispositivo de destino, com as seguintes restrições:

  • Se existir um driver de classe para o tipo de dispositivo de destino, o aplicativo deverá enviar a solicitação para o driver de classe. Portanto, um aplicativo poderá enviar essa solicitação diretamente para o driver de porta do sistema para uma LU (unidade lógica) de destino somente se não houver nenhum driver de classe para o tipo de dispositivo conectado a esse LU. O driver de porta do sistema não marcar determinar se um dispositivo foi reivindicado por um driver de classe antes de processar uma solicitação de passagem. Portanto, se um aplicativo ignorar um driver de classe que reivindicou um dispositivo e enviar uma solicitação de passagem para esse dispositivo diretamente para o driver de porta, um conflito para o controle do dispositivo poderá ocorrer entre o driver de classe e o aplicativo.
  • Essa solicitação não poderá ser usada se o comando exigir que o driver subjacente acesse a memória diretamente. Se o comando do chamador puder exigir acesso direto à memória, use IOCTL_ATA_PASS_THROUGH_DIRECT .
  • Os aplicativos não devem tentar enviar uma solicitação de passagem de forma assíncrona. Todas as solicitações de passagem devem ser síncronas.
  • Os aplicativos não exigem privilégios administrativos para enviar uma solicitação de passagem para um dispositivo, mas devem ter acesso de leitura/gravação ao dispositivo.
O aplicativo de chamada fornece o conteúdo do registro de arquivo de tarefa do ATA para o comando pretendido na estrutura ATA_PASS_THROUGH_EX . O sistema faz buffer duplo de todas as transferências de dados. Normalmente, essa solicitação é usada para transferir pequenas quantidades de dados (menos de 16 KB).

Código principal

IRP_MJ_DEVICE_CONTROL

Buffer de entrada

O buffer em Irp-AssociatedIrp.SystemBuffer> deve conter uma estrutura ATA_PASS_THROUGH_EX, que inclui um conjunto de registros de entrada de arquivo de tarefa que indicam o tipo de comando a ser executado e seus parâmetros. O chamador deve inicializar todos os membros dessa estrutura, exceto PathId, TargetId e Lun, que o driver de porta preenche. Para um comando de saída de dados, o membro DataBufferOffset da estrutura deve apontar para um buffer alinhado ao cache que contém os dados a serem gravados.

Comprimento do buffer de entrada

Parameters.DeviceIoControl.InputBufferLength indica o tamanho em bytes do buffer em Irp->AssociatedIrp.SystemBuffer. Se o comando do ATA inserido for uma operação de gravação, o tamanho do buffer de entrada deverá ser a soma de sizeof(ATA_PASS_THROUGH_EX) e o valor no membro DataTransferLength de ATA_PASS_THROUGH_EX. O exemplo de pseudocódigo a seguir mostra como calcular o tamanho do buffer:
ULONG buffsize; // size of the buffer
ATA_PASS_THROUGH_EX hdr;
hdr.DataTransferLength = size in bytes of the data transfer
buffsize = sizeof (ATA_PASS_THROUGH_EX) + hdr.DataTransferLength

Se o comando do ATA inserido for uma operação de leitura ou uma operação de controle de dispositivo que não envolva transferência de dados, InputBufferLength deverá ser igual a sizeof (ATA_PASS_THROUGH_EX).

Em ambos os casos, se InputBufferLength for menor que sizeof (ATA_PASS_THROUGH_EX), o driver de porta falhará na solicitação de E/S e retornará um erro.

Buffer de saída

O driver de porta formata os dados de retorno usando uma estrutura ATA_PASS_THROUGH_EX e armazena os dados no buffer em Irp-AssociatedIrp.SystemBuffer>.

O driver de porta preenche o membro CurrentTaskFile com os valores presentes nos registros de saída do dispositivo na conclusão do comando do ATA inserido. Se o comando foi uma transferência de dados, o driver de porta armazena os dados transferidos em um buffer alinhado ao cache localizado em um deslocamento de bytes DataBufferOffset desde o início da estrutura. O aplicativo é responsável por interpretar o conteúdo dos registros de saída para determinar quais erros, se houver, foram retornados pelo dispositivo.

Comprimento do buffer de saída

O driver de porta atualiza o membro DataTransferLength do ATA_PASS_THROUGH_EX para indicar a quantidade de dados realmente transferidos do dispositivo. Se o comando do ATA inserido for uma operação de gravação ou uma operação de controle de dispositivo que não transfere dados, OutputBufferLength será igual a sizeof(ATA_PASS_THROUGH_EX). Se o comando do ATA inserido for uma operação de leitura, OutputBufferLength será igual a sizeof(ATA_PASS_THROUGH_EX) + DataTransferLength.

Bloco de status

O membro Information é definido como o número de bytes retornados no buffer de saída em Irp-AssociatedIrp.SystemBuffer>. O membro Status é definido como STATUS_SUCCESS ou possivelmente como STATUS_BUFFER_TOO_SMALL ou STATUS_INVALID_PARAMETER se o valor status de entrada em ATA_PASS_THROUGH_EX estiver definido incorretamente.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível a partir do Windows Server 2003.
Cabeçalho ntddscsi.h (inclua Ntddscsi.h)

Confira também

ATA_PASS_THROUGH_EX

IOCTL_ATA_PASS_THROUGH_DIRECT