Comunicando verbos com o codec de áudio HD

Artigo
06/15/2023

O IOCTL_AZALIABUS_SENDVERBS IOCTL é usado pela ferramenta de configuração de pino Hdau.exe quando você define topologias de som para seus adaptadores de áudio. Não use este IOCTL para outras finalidades. Essas informações sobre IOCTL_AZALIABUS_SENDVERBS são fornecidas para documentar apenas seu design e implementação. Esse IOCTL tem suporte no driver de classe de áudio Hdaudio.sys do Windows 7.

Codecs de áudio de alta definição (HD) podem receber e responder a verbos. Esses verbos e as respostas dos codecs a esses verbos são documentados como parte da Especificação de Áudio HD.

No Windows 7 e versões posteriores dos sistemas operacionais Windows, o driver de classe de áudio HD usa o IOCTL_AZALIABUS_SENDVERBS IOCTL para comunicar verbos com o codec de áudio. IOCTL_AZALIABUS_SENDVERBS é definido conforme mostrado no exemplo a seguir:

#define IOCTL_AZALIABUS_SENDVERBS CTL_CODE(FILE_DEVICE_UNKNOWN, 1, METHOD_BUFFERED, FILE_ANY_ACCESS)

Para obter mais informações sobre FILE_DEVICE_UNKNOWN, METHOD_BUFFERED e FILE_ANY_ACCESS, consulte o arquivo de cabeçalho Devioctl.h no SDK do Windows.

Para iniciar a comunicação com o codec de áudio, o driver de classe chama a função DeviceIoControl com os parâmetros a seguir.

BOOL DeviceIoControl(
  (HANDLE) hDevice,                      // handle to device
  IOCTL_AZALIABUS_SENDVERBS,             // dwIoControlCode
  NULL,                                  // lpInBuffer
  0,                                     // nInBufferSize
  (LPVOID) lpOutBuffer,                  // output buffer
  (DWORD) nOutBufferSize,                // size of output buffer
  (LPDWORD) lpBytesReturned,             // number of bytes returned
  (LPOVERLAPPED) lpOverlapped            // OVERLAPPED structure
);

Se a chamada para DeviceIoControl for bem-sucedida, ela retornará um valor diferente de zero. Se a chamada falhar ou estiver pendente (não processada imediatamente), DeviceIoControl retornará um valor zero. O driver de classe pode chamar GetLastError para uma mensagem de erro mais detalhada.

Quando o driver de áudio deve alterar os padrões de configuração de pino, ele pode usar IOCTL_AZALIABUS_SENDVERBS para enviar e receber verbos Set e Get do codec de áudio. Se a comunicação com o codec de áudio não for sobre a configuração de pino, o codec de áudio responderá apenas ao verbo Get.

O exemplo a seguir mostra uma função que usa uma estrutura AzCorbeEntry e um HANDLE como parâmetros e retorna a AzRirbResponse do codec.

AzRirbEntry SendVerb(HANDLE handle, AzCorbEntry verb)
{
  UserModeCodecCommandPacket c;
  UserModeCodecResponsePacket r;
  c.NumCommands = 1;
  c.Command[0] = verb;
  DWORD BytesReturned;

//A nonzero value is returned for a successful call and it is interpreted as TRUE  
BOOL rc = DeviceIoControl(handle, IOCTL_AZALIABUS_SENDVERBS, &c, sizeof(c), &r, sizeof(r), &BytesReturned, 0);

  if(!rc)
  {
    printf("Failed to communicate with the device!\n");
    return 0;
  }

  if(BytesReturned != sizeof(r))
  {
    printf("Wrong number of bytes returned!\n");
    return 0;
  }

  return r.Response[0];
}

Os tipos de dados e estruturas usados no exemplo de código anterior são definidos no exemplo a seguir:

AzCorbEntry

struct AzCorbEntry
{
  ULONG Verb        : 20; // 0:19
  ULONG NodeId      : 7;  // 20:26
  ULONG IndirectNID : 1;  // 27
  ULONG LinkId      : 4;  // 28:31
  enum {Invalid = 0xffffffff};
  AzCorbEntry(ULONG x = 0)
  :
    Verb(x),
    NodeId(x >> 20),
    IndirectNID(x >> 27),
    LinkId(x >> 28) {}
  operator ULONG()
  {
    return Verb | NodeId << 20 | IndirectNID << 27 | LinkId << 28;
  }
};

AzRirbEntry

struct AzRirbEntry
{
  union
  {
    struct 
    {
      ULONG Response  : 21; // 0 : 20
      ULONG SubTag    : 5; // 21 : 25
      ULONG Tag       : 6; // 26 : 31
    } UnsolicitedForm;

    ULONG Response    : 32; // 0:31
  };
  ULONG Sdi         : 4;  // 32:35
  ULONG Unsolicited : 1;  // 36
  ULONG Reserved0   : 26; // 37:62
  ULONG Valid       : 1;  // 63 note this bit only exists
                          // on the "link". The fact that the response
                          // got into memory assures that it is valid
  AzRirbEntry (ULONGLONG x = 0)
  {
    Response = x & 0xffffffff;
    Sdi = x >> 32;
    Unsolicited = x >> 36;
    Reserved0 = x >> 37;
    Valid = x >> 63;
  }
  operator ULONGLONG()
  {
    return (ULONGLONG)Response | (ULONGLONG)Sdi << 32 | (ULONGLONG)Unsolicited << 36 | (ULONGLONG)Reserved0 << 37 | (ULONGLONG)Valid << 63;
  }
};

As duas estruturas a seguir são usadas junto com o IOCTL de transferência de verbo para habilitar as transferências de comando e resposta entre o driver de áudio e o codec de áudio HD.

UserModeCodecCommandPacket

typedef struct _UserModeCodecCommandPacket
{
  ULONG NumCommands;      // number of commands in this packet
  AzCorbEntry Command[1]; // variable length array of verbs
} UserModeCodecCommandPacket;

UserModeCodecResponsePacket

typedef struct _UserModeCodecResponsePacket
{
  ULONG NumResponses;       // on successful IOCTL, this will be updated with the number of responses.
  AzRirbEntry Response[1];  // Variable length array of responses. lpOutBuffer param to DeviceIoControl
                            // must point to sufficient space to hold this IOCTL with all its responses 
} UserModeCodecResponsePacket;

Partilhar via