Visão geral da interface do analisador TLV do WDI

Modelo de alocação de destinatário

Um ponto de entrada dentro do driver recebe uma mensagem ou indicação que contém TLVs. Depois que o código extrai a ID da mensagem e determina se é uma ID que ele deseja manipular, ele chama a rotina de análise genérica e passa o blob TLV (depois de passar pela WDI_MESSAGE_HEADER) para analisar as TLVs em uma estrutura C.

ndisStatus = Parse(
    cbBufferLength,
    pvBuffer,
    messageId,
    &Context,
    &pParsed);

Depois de verificar o retorno de erros, o código pode converter o buffer de saída (pParsed) em um tipo concreto, como no exemplo abaixo.

((WDI_INDICATION_BSS_ENTRY_LIST_PARAMETERS*)pParsed)

Depois que o chamador for concluído com os dados analisados, o chamador deverá retornar a memória de volta ao analisador. O analisador precisa saber a ID da mensagem original usada para alocar para liberar os dados corretos.

FreeParsed(messageId, pParsed);
pParsed = NULL;

Modelo de alocação de chamador

Nesse modelo, o chamador já determinou o TLV específico correto para analisar e possivelmente está usando uma pilha local para evitar alocações no heap. O chamador cria o local e chama uma rotina de análise específica. A API não precisa da ID da mensagem e o parâmetro é fortemente tipado com um nível a menos de indireção.

WDI_GET_ADAPTER_CAPABILITIES_PARAMETERS adapterCapabilitiesParsed;

ndisStatus = ParseWdiGetAdapterCapabilities(
    cbBufferLength,
    pvBuffer,
    &Context
    &adapterCapabilitiesParsed);

Depois que o chamador terminar de usar a estrutura, o chamador deverá dar ao analisador a chance de limpo qualquer alocação feita durante a análise e apagar a estrutura para que ela esteja pronta para ser reutilizada. O parâmetro é fortemente tipado, portanto, o receptor não precisa de parâmetros adicionais.

CleanupParsedWdiGetAdapterCapabilities(&adapterCapabilitiesParsed);

Depois de chamar a API CleanupParse, todos os dados na estrutura são inválidos.

Algumas mensagens não têm dados associados. Para a integridade da API, métodos de Análise apropriadamente nomeados são fornecidos. Esses métodos validam que o fluxo de bytes está vazio. Typedefs são fornecidos para o tipo de parâmetro, mas os chamadores também podem passar NULL para o parâmetro out se usarem o Modelo de Alocação de Chamador. Em todos os casos, o Analisador evita alocações retornando uma estrutura de análise vazia constante. Os chamadores nunca devem gravar nessa estrutura vazia retornada (portanto, o único campo é nomeado _Reserved). Essas mensagens são documentadas como "Nenhum dado adicional. Os dados no cabeçalho são suficientes".

Direção da mensagem

A maioria das mensagens tem um formato diferente para seu M1 versus M0, M3 ou M4. Para acomodar isso, essas mensagens têm uma análise diferente e geram APIs. Para mensagens M1, as APIs seguem a convenção de nomenclatura de Analisar<MessageName>ToIhv ou Gerar<MessageName>ToIhv. Para mensagens M0, M3 ou M4, as APIs seguem a convenção de nomenclatura de Analisar<MessageName>FromIhv ou Gerar<MessageName>FromIhv. No entanto, para simplificar o código no miniporto IHV, defines são adicionados ao alias Parse<MessageName> para Analisar<MessageName>ToIhv e Gerar<MessageName> para Gerar<MessageName>FromIhv. O código IHV só precisa estar ciente desse aliasing se precisar analisar seu próprio M3 ou gerar um M1.

Códigos do Erro

O gerador de analisador TLV pode retornar vários códigos de NDIS_STATUS diferentes. Para obter mais informações, examine os logs de rastreamento do WPP. Os logs sempre devem indicar a causa raiz. Aqui está uma lista dos códigos de erro mais comuns e o que eles significam.

NDIS_STATUS_INVALID_DATA	Ao analisar, isso indica que um TLV de tamanho fixo é do tamanho incorreto. Para listas, isso significa que o tamanho geral não é um múltiplo do tamanho do elemento individual ou há mais elementos do que deveria haver. Isso também pode significar uma lista que contém 0 elementos, quando 1 ou mais é necessário. Se 0 elementos for desejado, Optional_IsPresent deverá ser definido como false (o cabeçalho TLV não deve estar no fluxo de bytes).
NDIS_STATUS_BUFFER_OVERFLOW	Ao gerar, isso indica que, devido ao número de elementos em uma matriz (lista), ele transborda o campo Comprimento de 2 bytes dentro do cabeçalho TLV. Você deve reduzir o número de elementos. Isso também pode ocorrer quando um TLV externo tem muitas (ou muito grandes) TLVs internas, estourando novamente o campo Comprimento de 2 bytes do cabeçalho. Ao analisar, isso indica que o campo Comprimento de um cabeçalho TLV é maior que o TLV externo ou o fluxo de bytes.
NDIS_STATUS_FILE_NOT_FOUND	Ao analisar, isso indica que um TLV necessário não está presente no fluxo de bytes. Geralmente, é um bug com o gerador do fluxo de bytes.
NDIS_STATUS_RESOURCES	Ao gerar, isso indica que o alocador falhou.
NDIS_STATUS_UNSUPPORTED_REVISION	Ao analisar ou gerar, o parâmetro Context é NULL ou PeerVersion é menor que WDI_VERSION_MIN_SUPPORTED.