Compartilhar via

estrutura DXGK_SPB_INTERFACE (dispmprt.h)

  • Artigo

A estrutura DXGK_SPB_INTERFACE contém ponteiros para funções na Interface SPB (Barramento Periférico Simples) que um driver de driver de exibição do Windows (WDDM) 1.2 e o driver de miniportor de exibição posterior podem chamar para inspecionar e alterar recursos do SPB.

Sintaxe

typedef struct _DXGK_SPB_INTERFACE {
  USHORT                 Size;
  USHORT                 Version;
  PVOID                  Context;
  PINTERFACE_REFERENCE   InterfaceReference;
  PINTERFACE_DEREFERENCE InterfaceDereference;
  NTSTATUS(HANDLE DeviceHandle,LARGE_INTEGER SpbReourceId,UNICODE_STRING *SpbResourceSubName,ACCESS_MASK DesiredAccess,ULONG ShareAccess,ULONG OpenOptions,VOID **SpbResource)              * )(OpenSpbResource;
  NTSTATUS()(HANDLE DeviceHandle,VOID *SpbResource)              * CloseSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HReadSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HWriteSpbResource;
  NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG IoControlCode,ULONG InBufferSize,VOID *InputBuffer,ULONG OutBufferSize,VOID *OutputBuffer,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock)              * )(HSpbResourceIoControl;
} DXGK_SPB_INTERFACE, *PDXGK_SPB_INTERFACE;

Membros

Size

O tamanho, em bytes, dessa estrutura.

Version

O número de versão da interface SPB. As constantes de número de versão são definidas em Dispmprt.h (por exemplo, DXGK_SPB_INTERFACE_VERSION_1).

Context

Um ponteiro para um contexto fornecido pelo driver de miniporto de exibição.

InterfaceReference

Um ponteiro para uma função de referência de interface implementada pelo driver de miniporto de exibição.

InterfaceDereference

Um ponteiro para uma função de desreferência de interface implementada pelo driver de miniporto de exibição.

OpenSpbResource

Abre um recurso SPB (Barramento Periférico Simples). Todos os parâmetros de entrada são fornecidos pelo driver de miniporto de exibição.

Parâmetro OpenSpbResource Descrição
DeviceHandle Identificador que representa um adaptador de exibição. O driver de miniporto de exibição obteve anteriormente esse identificador no membro DeviceHandle da estrutura DXGKRNL_INTERFACE que foi passada para a função DxgkDdiStartDevice .
SpbReourceId A ID do recurso do hub de recursos do SPB.
SpbResourceSubName Ponteiro opcional para o subname de recurso do SPB Unicode.
DesiredAccess Um valor ACCESS_MASK que determina o acesso solicitado ao recurso SPB. Para obter mais informações, consulte o parâmetro DesiredAccess da função ZwCreateFile .
ShareAccess Tipo de acesso de compartilhamento para o arquivo. Para obter mais informações, consulte o parâmetro ShareAccess de ZwCreateFile.
OpenOptions As opções a serem aplicadas ao abrir o recurso SPB. Para obter mais informações, consulte o parâmetro CreateOptions de ZwCreateFile.
SpbResource Um ponteiro para um buffer usado para retornar o identificador para o recurso SPB.

CloseSpbResource

Fecha um recurso do SPB. Todos os parâmetros de entrada são fornecidos pelo driver de miniporto de exibição.

Fechar um identificador de objeto aberto faz com que esse identificador se torne inválido. O sistema também diminui a contagem de identificadores do objeto e verifica se o objeto pode ser excluído. Na verdade, o sistema não exclui o objeto até que todos os identificadores do objeto sejam fechados e nenhum ponteiro referenciado permaneça.

O driver deve chamar CloseSpbResource para fechar todos os identificadores abertos com OpenSpbResource assim que o identificador não for mais necessário.

Os chamadores de CloseSpbResource não devem pressupor que essa função aguarde automaticamente a conclusão de toda a E/S antes do retorno.

Parâmetro CloseSpbResource Descrição
DeviceHandle Um identificador que representa um adaptador de exibição. O driver de miniporto de exibição obteve anteriormente esse identificador no membro DeviceHandle da estrutura DXGKRNL_INTERFACE que foi passada para a função DxgkDdiStartDevice .
SpbResource Um ponteiro para um recurso SPB que o driver de miniporto de exibição abriu usando a função OpenSpbResource .

ReadSpbResource

Lê dados de um recurso SPB aberto. Todos os parâmetros de entrada são fornecidos pelo driver de miniporto de exibição.

Se a chamada para OpenSpbResource definir um dos sinalizadores do OpenOptionsFILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT (definido em Wdm.h), o Gerenciador de E/S manterá a posição do arquivo atual. Nesse caso, o chamador de ReadSpbResource pode especificar que o deslocamento de posição do arquivo atual seja usado em vez de um valor byteOffset explícito. Essa especificação pode ser feita usando um dos seguintes métodos:

  • Especifique um ponteiro para um valor LARGE_INTEGER com o membro HighPart definido como -1 e o membro LowPart definido como o valor definido pelo sistema FILE_USE_FILE_POINTER_POSITION (definido em Wdm.h).
  • Passe um ponteiro NULL para ByteOffset.

ReadSpbResource atualiza a posição do arquivo atual adicionando o número de bytes lidos quando conclui a operação de leitura, se estiver usando a posição de arquivo atual mantida pelo Gerenciador de E/S.

Mesmo quando o Gerenciador de E/S está mantendo a posição do arquivo atual, o chamador pode redefinir essa posição passando um valor byteOffset explícito para ReadSpbResource. Fazer isso altera automaticamente a posição do arquivo atual para esse valor ByteOffset , executa a operação de leitura e atualiza a posição de acordo com o número de bytes realmente lidos. Essa técnica fornece ao chamador um serviço de busca e leitura atômica.

Parâmetro OpenSpbResource Descrição
DeviceHandle Um identificador que representa um adaptador de exibição. O driver de miniporto de exibição obteve anteriormente esse identificador no membro DeviceHandle da estrutura DXGKRNL_INTERFACE que foi passada para a função DxgkDdiStartDevice .
SpbResource Um ponteiro para um recurso SPB que o driver de miniporto de exibição abriu usando a função OpenSpbResource .
Comprimento O tamanho, em bytes, do buffer apontado pelo parâmetro Buffer .
Buffer Um ponteiro para um buffer que recebe os dados lidos do recurso SPB especificado.
ByteOffset Um ponteiro opcional para uma variável que especifica o deslocamento de bytes inicial no recurso SPB em que a operação de leitura será iniciada. Se for feita uma tentativa de leitura além do final do arquivo, ReadSpbResource retornará um erro.
EventHandle Um identificador opcional para um evento criado pelo chamador. Se esse parâmetro for fornecido, o chamador será colocado em um estado de espera até que a operação de leitura seja concluída e o evento fornecido seja definido como o estado Sinalizado . Este parâmetro pode ser NULL.
IoStatusBlock Um ponteiro para uma estrutura de IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação de leitura solicitada. O membro Information da estrutura IO_STATUS_BLOCK recebe o número de bytes realmente lidos do recurso SPB.

WriteSpbResource

Grava dados em um recurso de SPB aberto.

Se a chamada para a função OpenSpbResource definir apenas o sinalizador DesiredAccessFILE_APPEND_DATA, o parâmetro ByteOffset será ignorado. Nesse caso, os dados no buffer apontados pelo parâmetro Buffer , para Bytes de comprimento , são gravados começando no final atual do arquivo.

Se a chamada para OpenSpbResource definir um dos sinalizadores CreateOptions , FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT, o Gerenciador de E/S manterá a posição do arquivo atual. Nesse caso, o chamador de WriteSpbResource pode especificar que o deslocamento de posição do arquivo atual seja usado em vez de um valor byteOffset explícito. Essa especificação pode ser feita usando um dos seguintes métodos:

  • Especifique um ponteiro para um valor LARGE_INTEGER com o membro HighPart definido como -1 e o membro LowPart definido como o valor definido pelo sistema FILE_USE_FILE_POINTER_POSITION (definido em Wdm.h).
  • Passe um ponteiro NULL para ByteOffset.

WriteSpbResource atualiza a posição do arquivo atual adicionando o número de bytes gravados quando conclui a operação de gravação, se estiver usando a posição de arquivo atual mantida pelo Gerenciador de E/S.

Mesmo quando o Gerenciador de E/S está mantendo a posição do arquivo atual, o chamador pode redefinir essa posição passando um valor byteOffset explícito para WriteSpbResource. Fazer isso altera automaticamente a posição do arquivo atual para esse valor ByteOffset , executa a operação de gravação e atualiza a posição de acordo com o número de bytes realmente gravados. Essa técnica fornece ao chamador um serviço atômico de busca e gravação.

Também é possível fazer com que uma operação de gravação comece no final atual do arquivo especificando para ByteOffset um ponteiro para um valor LARGE_INTEGER com HighPart definido como -1 e LowPart definido como FILE_WRITE_TO_END_OF_FILE. Isso funciona independentemente de o Gerenciador de E/S manter a posição do arquivo atual.

Parâmetro WriteSpbResource Descrição
DeviceHandle Um identificador que representa um adaptador de exibição. O driver de miniporta de exibição obteve anteriormente esse identificador no membro DeviceHandle da estrutura DXGKRNL_INTERFACE que foi passada para a função DxgkDdiStartDevice .
SpbResource Um ponteiro para um recurso SPB que o driver de miniporto de exibição abriu usando a função OpenSpbResource .
Comprimento O tamanho, em bytes, do buffer apontado pelo parâmetro Buffer .
Buffer Um ponteiro para um buffer alocado pelo chamador que contém os dados a serem gravados no recurso SPB especificado.
ByteOffset Um ponteiro opcional para uma variável que especifica o deslocamento de bytes inicial no recurso SPB em que a operação de gravação será iniciada. Se os parâmetros Length e ByteOffset especificarem uma operação de gravação após a marca de fim de arquivo atual, WriteSpbResource estenderá automaticamente o arquivo e atualizará a marca de fim do arquivo; todos os bytes que não são gravados explicitamente entre essas marcas de fim de arquivo antigas e novas são definidos como zero.
EventHandle Um identificador opcional para um evento criado pelo chamador. Se esse parâmetro for fornecido, o chamador será colocado em um estado de espera até que a operação de gravação seja concluída e o evento fornecido seja definido como o estado Sinalizado . Este parâmetro pode ser NULL.
IoStatusBlock Um ponteiro para uma estrutura IO_STATUS_BLOCK que recebe a status de conclusão final e informações sobre a operação de gravação solicitada. O membro Information da estrutura IO_STATUS_BLOCK recebe o número de bytes realmente gravados no recurso SPB.

SpbResourceIoControl

Executa uma operação de controle de E/S em um recurso SPB (Barramento Periférico Simples) aberto. Todos os parâmetros de entrada são fornecidos pelo driver de miniporta de exibição.

Se o chamador abriu o arquivo para E/S assíncrona (sem FILE_SYNCHRONOUS_XXX conjunto de opções de criação/abertura), o evento especificado, se houver, será definido como o estado Sinalizado quando a operação de controle do dispositivo for concluída. Caso contrário, o objeto de arquivo especificado pelo parâmetro DeviceHandle será definido como o estado Signaled .

Parâmetro SpbResourceIoControl Descrição
DeviceHandle Um identificador que representa um adaptador de exibição. O driver de miniporta de exibição obteve anteriormente esse identificador no membro DeviceHandle da estrutura DXGKRNL_INTERFACE que foi passada para a função DxgkDdiStartDevice .
SpbResource Um ponteiro para um recurso SPB que o driver de miniporto de exibição abriu usando a função OpenSpbResource .
Iocontrolcode Um código de controle de E/S do dispositivo (IOCTL_XXX) que indica em qual operação de controle de E/S do dispositivo deve ser executada, geralmente pelo driver de dispositivo subjacente. O valor desse parâmetro determina o formato e o comprimento necessário dos parâmetros InputBuffer e OutputBuffer , bem como quais dos pares de parâmetros a seguir são necessários.
InBufferSize O tamanho, em bytes, do buffer apontado pelo parâmetro InputBuffer . Esse valor será ignorado se InputBuffer for NULL.
Inputbuffer Um ponteiro para um buffer de entrada alocado pelo chamador que contém informações específicas do dispositivo a serem fornecidas ao dispositivo de destino. Se o parâmetro IoControlCode especificar uma operação que não exige dados de entrada, esse ponteiro poderá ser NULL.
OutBufferSize O tamanho, em bytes, do buffer apontado pelo parâmetro OutputBuffer . Esse valor será ignorado se OutputBuffer for NULL.
OutputBuffer Um ponteiro para um buffer de saída alocado pelo chamador no qual as informações são retornadas do dispositivo de destino. Se o parâmetro IoControlCode especificar uma operação que não produz dados de saída, esse ponteiro poderá ser NULL.
EventHandle Um identificador opcional para um evento criado pelo chamador. Se esse parâmetro for fornecido, o chamador será colocado em um estado de espera até que a operação solicitada seja concluída e o evento fornecido seja definido como o estado Sinalizado . Este parâmetro pode ser NULL.
IoStatusBlock Um ponteiro para uma variável que recebe a conclusão final status e informações sobre a operação de controle de E/S solicitada. Para chamadas bem-sucedidas que retornam dados, o número de bytes gravados no buffer apontado pelo parâmetro OutputBuffer é retornado no membro Information da estrutura IO_STATUS_BLOCK .

Comentários

Para usar as funções dessa estrutura, primeiro forneça os membros Size e Version da estrutura DXGK_SPB_INTERFACE . Em seguida, chame a função DxgkCbQueryServices com o parâmetro ServicesType definido como um valor de DxgkServicesFirmwareTable e defina o parâmetro Interface como o endereço (convertido como PINTERFACE) da estrutura DXGK_SPB_INTERFACE .

Para obter mais informações sobre a arquitetura do SPB, consulte Simple Peripheral Buses and SPB Peripheral Driver Design Guide**.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8
Servidor mínimo com suporte Windows Server 2012
Cabeçalho dispmprt.h (inclua Dispmprt.h)