Partilhar via

Interfaces de driver IHV WDI

A miniporta WDI IHV é como qualquer outro driver de miniporta NDIS e seguiria as práticas de desenvolvimento e a documentação para qualquer miniporta NDIS. As responsabilidades de um driver de miniporta WLAN nativo para os manipuladores NDIS são divididas entre o componente MS e o driver IHV WDI. O componente Microsoft WLAN cuida dos requisitos NDIS aplicáveis a todas as miniportas Wi-Fi para que cada IHV não precise refazer todo esse trabalho. O mapeamento e as alterações no comportamento dos controladores NDIS para a miniporta IHV de WLAN nativa, quando aplicados a uma miniporta IHV de WDI, são descritos abaixo.

Driver installation

Não há alterações na forma como o driver de miniporta WDI IHV é carregado e instalado no sistema. O INF e o processo de instalação são semelhantes aos de um driver de miniporta WLAN nativo IHV. Tal como acontece com os drivers NDIS existentes, quando o driver IHV precisa ser carregado para funcionar com o adaptador WLAN do IHV, o sistema operativo chama a rotina DriverEntry do driver de miniporta IHV.

DriverEntry

O sistema operativo chama diretamente a rotina DriverEntry do driver de miniporta WDI IHV. O miniporto IHV segue a maioria das normas da rotina DriverEntry de um miniporto NDIS regular. A única exceção é que, em vez de chamar NdisMRegisterMiniportDriver, a miniporta IHV chama NdisMRegisterWdiMiniportDriver para informar ao sistema operacional para habilitar o componente WLAN da Microsoft.

A seguir estão os principais parâmetros do NdisMRegisterWdiMiniportDriver.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: Esta é a estrutura NDIS original que uma miniporta Wi-Fi nativa usa para se registrar com o NDIS. Para um modelo WDI, a maioria dos parâmetros do manipulador são opcionais. Os únicos manipuladores necessários são MINIPORT_OID_REQUEST_HANDLER e MINIPORT_DRIVER_UNLOAD. MINIPORT_OID_REQUEST_HANDLER é usado para transmitir mensagens WDI para o driver IHV. Se qualquer outro manipulador for especificado, o componente WLAN da Microsoft geralmente chama o manipulador depois que ele executa seu próprio processamento para o manipulador.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: Este é o novo conjunto de manipuladores que um driver de miniporta WDI deve implementar. Ele é usado pelo driver IHV para registrar manipuladores adicionais para o caminho de controle e o conjunto completo de manipuladores para o caminho de dados.

Quando a miniporta IHV chama NdisMRegisterWdiMiniportDriver, o componente Microsoft WLAN atualiza os manipuladores de NDIS_MINIPORT_DRIVER_CHARACTERISTICS e chama o NdisMRegisterMiniportDriver da NDIS. As atualizações são feitas para que o componente Microsoft WLAN possa intercetar os manipuladores para os quais ele pode fornecer assistência/simplificação para o driver de miniporta WDI IHV.

Abaixo está o fluxo típico do processo DriverEntry para o driver de miniporta WDI IHV

fluxo de entrada de driver WDI.

Para obter mais informações sobre DriverEntry, consulte DriverEntry of NDIS Miniport Drivers.

MiniportSetOptions

Como mostrado no diagrama DriverEntry acima, se a miniporta IHV WDI tiver registrado o manipulador de MiniportSetOptions, o sistema operativo chamará essa função no contexto de o driver de miniporta chamar NdisMRegisterWdiMiniportDriver.

Se o driver de miniporta IHV registrar quaisquer manipuladores de opção usando NdisSetOptionalHandlers, esses manipuladores não podem ser serializados através da camada WDI pelo componente Microsoft. Portanto, o componente IHV é responsável por lidar com quaisquer requisitos de sincronização para esses manipuladores.

MiniportInitializeEx

O modelo WDI divide o comportamento MiniportInitializeEx em várias chamadas de interface WDI.

  1. Call MiniportWdiAllocateAdapter.

    Quando o sistema operacional encontra uma instância do hardware IHV, esta é a primeira chamada para o driver de miniporta WDI IHV. Nesta chamada, a miniporta WDI executa as ações necessárias para criar uma representação de software (MiniportAdapterContext) do dispositivo. Ele também determina informações sobre o dispositivo para preencher a estrutura NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. A inicialização real do dispositivo e da pilha de Wi-Fi é feita mais tarde, quando o componente da Microsoft envia comandos WDI para baixo para executar inicializações específicas.

    Usando dados obtidos do driver de miniporta WDI IHV, o componente da Microsoft chama NdisMSetMiniportAttributes e define o NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES no NDIS. A maioria dos campos de NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES são preenchidos com padrões pelo componente Microsoft. O driver IHV deve preencher os campos MiniportAdapterContext e InterfaceType.

    Quando esta chamada retorna do driver de miniporta IHV, ele começa a receber comandos WDI por meio do seu manipulador de MiniportOidRequest. Durante esta chamada, o componente Microsoft pode não ser capaz de executar operações de redefinição/recuperação, portanto, qualquer atividade realizada aqui deve ser rápida e confiável.

  2. Call MiniportWdiOpenAdapter.

    Depois de MiniportWdiAllocateAdapter, o componente da Microsoft chama MiniportWdiOpenAdapter para carregar o firmware e inicializar o hardware.

  3. Vários comandos WDI usando MiniportOidRequest.

    Depois de MiniportWdiOpenAdapter, o componente Microsoft envia as seguintes tarefas, propriedades ou chamadas à miniporta IHV.

    1. Chame MiniportWdiTalTxRxInitialize para inicializar o caminho de dados e os manipuladores de câmbio.
    2. Ligue para OID_WDI_GET_ADAPTER_CAPABILITIES para obter os recursos do adaptador.
    3. Chame OID_WDI_SET_ADAPTER_CONFIGURATION para configurar o adaptador.
    4. Chame OID_WDI_TASK_SET_RADIO_STATE para definir o estado de rádio inicial se ele ainda não estiver no estado esperado.
    5. Chame MiniportWdiTalTxRxStart para configurar o caminho de dados.
    6. Chame OID_WDI_TASK_CREATE_PORT para criar a porta inicial.

    Outros comandos também podem ser enviados para o componente IHV como parte do processamento MiniportInitializeEx do componente Microsoft. No entanto, até que MiniportWdiStartOperation seja chamado, o componente da Microsoft não envia nenhuma tarefa que necessite de comunicação via rádio. Exceto por OID_WDI_TASK_OPEN serem sempre enviados primeiro, a ordem dos outros comandos/chamadas pode mudar.

    Usando dados obtidos do driver de miniporta WDI IHV, o componente da Microsoft chama NdisMSetMiniportAttributes e define NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES e NDIS_MINIPORT_ADAPTER_NATIVE_802_11_ATTRIBUTES no NDIS.

  4. Call MiniportWdiStartOperation.

    Este é um manipulador de miniporta WDI opcional dentro NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS que o driver IHV pode usar para executar quaisquer tarefas adicionais MiniportInitializeEx. Também pode ser usado pela miniporta IHV como um sinal de que o componente da Microsoft terminou de inicializar a miniporta e que esta pode iniciar quaisquer atividades de fundo necessárias.

    O diagrama abaixo mostra o fluxo de MiniportInitializeEx.

    fluxo de inicialização de miniporta WDI.

    Se uma operação intermediária falhar, o componente da Microsoft desfaz as operações anteriores e falha na inicialização da miniporta. Por exemplo, se OID_WDI_TASK_CREATE_PORT falhar, o caminho de dados será limpo, OID_WDI_TASK_CLOSE será enviado e a miniporta falhará.

MiniportHaltEx

Em uma miniporta Wi-Fi nativa, MiniportHaltEx é usado para instruir a miniporta a interromper as operações e limpar a instância do adaptador. No modelo WDI, o componente Microsoft lida com a chamada original MiniportHaltEx e a divide em várias chamadas de interface WDI.

  1. Call MiniportWdiStopOperation.

    Este é um manipulador de miniporta WDI opcional dentro de NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS que o driver IHV pode usar para desfazer as operações executadas em MiniportWdiStartOperation.

  2. Múltiplos comandos WDI usando MiniportOidRequest.

    Após MiniportWdiStopOperation, o componente Microsoft envia tarefas e propriedades para a miniporta IHV para restaurar o estado atual do driver IHV. Esta limpeza pode incluir o seguinte.

    1. Ligue para OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP para desconectar todas as conexões existentes.
    2. Chame OID_WDI_TASK_DELETE_PORT para excluir todas as portas criadas.
    3. Chame MiniportWdiTalTxRxStop para interromper o caminho de dados.
    4. Chame MiniportWdiTalTxRxDeinitialize para desinicializar o caminho de dados.
    5. Ligue para limpar o estado do hardware. Isso é enviado para o IHV usando o MiniportWdiCloseAdapter que foi registrado pelo driver IHV.

  3. Depois que todos os comandos acima são chamados, o componente da Microsoft chama MiniportWdiFreeAdapter para que o driver IHV exclua qualquer estado de software que ele possa ter.

O diagrama abaixo mostra o fluxo do MiniportHaltEx.

fluxo de parada da miniporta WDI.

O processamento MiniportHaltEx não é realizado se o dispositivo for removido de surpresa ou se o sistema estiver sendo desligado. Para remoção surpresa, consulte o comportamento do manipulador MiniportDevicePnPEventNotify. Para o desligamento do sistema, consulte o comportamento do manipulador MiniportShutdownEx.

MiniportDriverUnload

MiniportDriverUnload é o manipulador que é chamado antes que a miniporta WDI IHV seja descarregada. O driver de miniporta WDI IHV chama o componente da Microsoft para cancelar o registro. O componente da Microsoft chama NdisMDeregisterMiniportDriver.

O diagrama abaixo mostra o fluxo de MiniportDriverUnload.

fluxo de descarga do driver de miniporta WDI.

MiniportPause

O NDIS MiniportPause requisitos são tratados pelo componente Microsoft. Como parte do MiniportPause, o componente da Microsoft para o caminho de dados e aguarda que ele seja limpo. A miniport WDI IHV pode, opcionalmente, registrar-se para um MiniportWdiPostAdapterPause retorno de chamada que é invocado pelo componente da Microsoft depois de concluir a limpeza do caminho de dados.

O diagrama abaixo mostra o fluxo de MiniportPause.

fluxo de pausa da miniporta WDI.

MiniportRestart

Os requisitos NDIS MiniportRestart são tratados pelo componente Microsoft. Como parte do MiniportRestart, o componente da Microsoft desfaz o processo de pausa do caminho de dados que realizou como parte do MiniportPause. A miniporta WDI IHV pode, opcionalmente, registrar-se para um MiniportWdiPostAdapterRestart retorno de chamada invocado pelo componente da Microsoft após concluir a reinicialização do caminho de dados.

O diagrama abaixo mostra o fluxo de MiniportRestart.

fluxo de reinicialização da miniporta WDI.

MiniportResetEx

MiniportResetEx não é manipulado pelo componente Microsoft. A miniporta WDI IHV pode, opcionalmente, registrar-se para um retorno de chamada MiniportResetEx que é chamado pelo componente da Microsoft.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify é usado para notificar um driver NDIS sobre eventos PNP, como a remoção surpresa de um dispositivo. Quando o NDIS envia essa notificação, ela é primeiro encaminhada para a miniporta WDI IHV para processamento. Depois que o componente IHV terminar de processá-lo, o componente Microsoft executa o processamento apropriado para esse evento. A chamada encaminhada para o componente IHV não é serializada com outras tarefas e retornos de chamada.

O diagrama abaixo mostra o fluxo de MiniportDevicePnPEventNotify.

fluxo de notificação PNP da unidade de miniporta WDI.

MiniportShutdownEx

MiniportShutdownEx é usado para notificar um driver NDIS sobre eventos de desligamento do sistema. Quando o NDIS envia essa notificação, ela é primeiro manipulada pelo componente da Microsoft. Depois que o componente da Microsoft termina de processá-lo, ele passa o evento para a miniporta WDI IHV para processamento.

O diagrama abaixo mostra o fluxo de MiniportShutdownEx.

fluxo de desligamento da miniporta WDI.

MiniportOidRequest

O manipulador MiniportOidRequest é um manipulador necessário que a miniporta IHV WDI deve implementar. Ele é usado pelo componente Microsoft para enviar comandos WDI para a miniporta IHV. Ele também é usado para encaminhar OIDs que o componente da Microsoft não manipula para a miniporta IHV.

A chamada MiniportOidRequest para a miniporta WDI IHV deve ser considerada como a mensagem M1 para um comando WDI. A conclusão do OID (via NdisMOidRequestComplete ou por meio de um retorno não PENDENTE de MiniportOidRequest) deve ser considerada como a mensagem M3 para uma tarefa/comando WDI.

Para cada comando WDI, há dois campos potenciais onde um código NDIS_STATUS pode ser retornado para a operação -- o código de status da chamadaMiniportOidRequest(ou NdisMOidRequestComplete) e o código de status no campo WDI_MESSAGE_HEADER (na conclusão do OID ou via NdisMIndicateStatusEx). O componente Microsoft analisa sempre o NDIS_STATUS da conclusão do OID antes de examinar o campo WDI_MESSAGE_HEADERStatus. As expectativas do componente IHV para o processamento WDI OID são as seguintes.

  1. Os OIDs WDI são enviados para o componente IHV usando umRequestType NDIS_OID_REQUEST de NdisRequestMethod, e a mensagem correspondente e o comprimento da mensagem estão no DATA. METHOD_INFORMATION. InformationBuffer e DATA. METHOD_INFORMATION. InputBufferLength campos respectivamente.
  2. O componente IHV relata um erro na completação do OID se houver um erro durante o processamento do comando, e define o campo Status do WDI_MESSAGE_HEADER como sem êxito, em caso de uma falha de nível Wi-Fi.
  3. Para tarefas e propriedades, o número da porta da solicitação está no campo WDI_MESSAGE_HEADERPortId. O PortNumber no NDIS_OID_REQUEST está sempre definido para 0.
  4. Para a conclusão do OID, é aceitável que o MiniportOidRequest retorne NDIS_STATUS_PENDING e conclua o OID posteriormente (de forma síncrona ou assíncrona) com NdisMOidRequestComplete .
  5. Se o componente IHV completar o OID com NDIS_STATUS_SUCCESS, ele deverá preencher o campo BytesWritten da solicitação OID com o número apropriado de bytes, incluindo espaço para o WDI_MESSAGE_HEADER.
  6. Se o componente IHV não tiver espaço suficiente no campo DATA.METHOD_INFORMATION.OutputBufferLength para preencher a resposta, ele finaliza o OID com NDIS_STATUS_BUFFER_TOO_SHORT e indica o número de DATA.METHOD_INFORMATION.BytesNeeded necessários. O componente Microsoft pode tentar alocar um buffer do tamanho solicitado e enviar uma nova solicitação para o IHV.
  7. Se for uma tarefa, o M4 da tarefa (NdisMIndicateStatusEx) só deve ser indicado se a tarefa foi relatada como iniciada com êxito -- a conclusão do OID foi bem-sucedida e o de Status do no WDI_MESSAGE_HEADER na conclusão do OID foi bem-sucedido.

O diagrama abaixo mostra um exemplo de uma solicitação NDIS OID que mapeia para um único comando WDI. Quando a solicitação OID é enviada pelo sistema operacional, o componente da Microsoft a converte em uma solicitação OID WDI e envia a solicitação OID WDI para a miniporta IHV. Quando a miniporta IHV conclui o OID, o componente da Microsoft conclui adequadamente a solicitação OID original.

sequência de solicitação de OID de miniporta WDI para comando WDI único.

Se a solicitação OriginalOidRequest for mapeada para várias solicitações de Oid WDI e uma das solicitações WDI falhar, a solicitação OriginalOidRequest também falhará. Se um subconjunto das operações intermediárias já tiver sido concluído, o componente da Microsoft tentará desfazer as operações que oferecem suporte à limpeza.

O diagrama abaixo mostra um exemplo de uma solicitação NDIS OID que é processada e concluída pelo componente Microsoft. Quando a solicitação OID é enviada pelo sistema operacional, o componente Microsoft processa e conclui o OID. Este OID não é passado para a miniporta WDI IHV.

sequência de pedidos de OID do miniport WDI para OIDs geridos pelo componente Microsoft.

OIDs que não são compreendidos pelo componente Microsoft são encaminhados diretamente para o componente IHV para processamento.

sequência de solicitação de OID de miniporta WDI para OIDs não manipulados pelo componente Microsoft.

O comportamento de MiniportOidRequest permanece inalterado para o driver de miniporta WDI IHV (em comparação com uma miniporta Wi-Fi nativa). As chamadas são serializadas e a miniporta IHV pode concluí-la de forma síncrona ou assíncrona com uma chamada para NdisMOidRequestComplete.

MiniportCancelOidRequest

Este é um gestor opcional utilizado por um miniport IHV WDI que necessita lidar com OIDs que não estão mapeados para mensagens WDI. Este manipulador não é usado para nenhuns OIDs de WDI. Os OIDs WDI devem ser concluídos rapidamente, e não é necessário que o controlador de miniporta IHV tente cancelar um OID pendente. O cancelamento de tarefas WDI é tratado usando a solicitação apropriada de OID para cancelamento de tarefa. Para OIDs não mapeados, o comportamento esperado é definido pelo NDIS.

NdisMIndicateStatusEx

NdisMIndicateStatusEx é usado pela miniporta WDI IHV para enviar indicações para o componente Microsoft. As indicações podem ser indicações não solicitadas, tais como falhas no TKIP MIC, ou indicações solicitadas para a conclusão (M4) de uma tarefa.

O diagrama abaixo mostra um exemplo de uma indicação WDI que tem uma indicação NDIS/Native Wi-Fi correspondente. Quando a indicação é enviada pela miniporta IHV para o componente Microsoft, o componente Microsoft a converte em uma indicação existente e a encaminha para o sistema operacional.

fluxo de indicação de status da miniporta WDI.

O diagrama abaixo mostra um exemplo de uma indicação WDI que não tem nenhuma indicação NDIS/Native Wi-Fi correspondente. Isso é tratado pelo componente Microsoft.

indicação de estado do WDI sem mapeamento direto para NDIS.

O diagrama abaixo mostra uma indicação que não é reconhecida pelo componente Microsoft. A indicação é encaminhada as-is para o sistema operacional.

Indicação de status WDI não reconhecida pelo componente Microsoft.

O comportamento de NdisMIndicateStatusEx é inalterado para o driver de miniporta WDI IHV (em comparação com uma miniporta Wi-Fi nativa).

MiniportDirectOidRequest

Este é um manipulador opcional que é registado por um controlador de miniporta WDI IHV, se precisar lidar com OIDs diretos que não são mapeados para mensagens WDI. Todos os Direct OIDs existentes para Wi-Fi Direct são mapeados para mensagens WDI, portanto, esse manipulador não é necessário para suportar essa funcionalidade. OIDs diretos sem suporte não são serializados pelo componente Microsoft.

MiniportCancelDirectOidRequest

Este é um manipulador opcional que é usado por uma miniporta IHV WDI que precisa lidar com Direct OIDs que não são mapeados para mensagens WDI. Para OIDs não mapeados, o comportamento esperado é definido pelo NDIS.

MiniportSendNetBufferLists

Este manipulador não é usado em um driver de miniporta WDI IHV e não deve ser fornecido. O componente Microsoft usa os manipuladores de caminho de dados registados por meio do NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS para submeter pacotes de transmissão para a miniporta IHV.

MiniportCancelSend

Este manipulador não é usado em um driver de miniporta WDI IHV e não deve ser fornecido.

MiniportReturnNetBufferLists

Este manipulador não é usado em um driver de Miniporta WDI IHV e não deve ser fornecido. O componente Microsoft usa os manipuladores de caminho de dados registrados por meio do NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS para retornar pacotes recebidos para a miniporta IHV.

Manipulador WDI: MiniportWdiOpenAdapter

O manipulador de MiniportWdiOpenAdapter é utilizado pelo componente Microsoft para iniciar a operação de abertura de tarefa no driver IHV. Essa chamada deve ser concluída rapidamente e, se a operação aberta tiver sido iniciada com êxito, o IHV deverá retornar NDIS_STATUS_SUCCESS nessa chamada e chamar o manipulador deOpenAdapterCompleteque é passado para o parâmetro NDIS_WDI_INIT_PARAMETERS de MiniportWdiAllocateAdapter.

Manipulador WDI: MiniportWdiCloseAdapter

O manipulador MiniportWdiCloseAdapter é usado pelo componente Microsoft para iniciar a operação de Encerramento de Tarefa no driver IHV. Essa chamada deve ser concluída rapidamente e, se a operação de abertura tiver sido iniciada com êxito, o IHV deverá retornar NDIS_STATUS_SUCCESS nesta chamada e deverá chamar o manipulador de CloseAdapterComplete que é passado para o parâmetro NDIS_WDI_INIT_PARAMETERS do MiniportWdiAllocateAdapter.

  • Last updated on