Compartilhar via

Interfaces de driver IHV do WDI

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

Driver installation

Não há alterações na maneira como o driver de miniporto WDI IHV é carregado e instalado no sistema. O INF e o processo de instalação são semelhantes ao de um driver de miniporto WLAN nativo de um IHV. Assim como os drivers NDIS existentes, quando o driver IHV precisa ser carregado para trabalhar com o adaptador WLAN do IHV, o sistema operacional chama a rotina DriverEntry do driver de miniporto IHV.

DriverEntry

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

Veja a seguir os principais parâmetros do NdisMRegisterWdiMiniportDriver.

  • NDIS_MINIPORT_DRIVER_CHARACTERISTICS: esta é a estrutura NDIS original que um miniporto nativo Wi-Fi usa para registrar-se no 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 passar mensagens WDI para o driver IHV. Se qualquer outro manipulador for especificado, o componente WLAN da Microsoft geralmente chamará o manipulador depois de executar seu próprio processamento para o manipulador.
  • NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS: esse é o novo conjunto de manipuladores que um driver de miniporto 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 o miniporto IHV chama NdisMRegisterWdiMiniportDriver, o componente WLAN da Microsoft atualiza os handlers de NDIS_MINIPORT_DRIVER_CHARACTERISTICS e chama o NdisMRegisterMiniportDriver do NDIS. As atualizações são feitas para que o componente WLAN da Microsoft possa interceptar os manipuladores para os quais ele pode fornecer assistência/simplificação para o driver de miniporto WDI IHV.

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

fluxo de DriverEntry wdi.

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

MiniportSetOptions

Conforme mostrado no diagrama de DriverEntry acima, se o miniporto WDI IHV tiver registrado o manipulador MiniportSetOptions , o sistema operacional chamará essa função no contexto do driver de miniporto chamando NdisMRegisterWdiMiniportDriver.

Se o driver de miniporto IHV registrar qualquer manipulador de opção usando NdisSetOptionalHandlers, esses manipuladores poderão não ser serializados por meio da camada WDI pelo componente da Microsoft. Portanto, o componente IHV é responsável por lidar com todos os 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, essa é a primeira chamada para o driver de miniporto WDI IHV. Nesta chamada, o miniporto 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 posteriormente quando o componente da Microsoft envia comandos WDI para executar inicializações específicas.

    Usando dados obtidos do driver de miniporto 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 da Microsoft. O driver IHV deve preencher os campos MiniportAdapterContext e InterfaceType .

    Depois que essa chamada retorna do driver de miniporto IHV, ela começa a receber comandos WDI por meio de seu manipulador MiniportOidRequest . Durante essa chamada, o componente da Microsoft pode não ser capaz de executar operações de redefinição/recuperação, portanto, qualquer atividade executada 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.

    Após MiniportWdiOpenAdapter, o componente da Microsoft envia as seguintes tarefas/propriedades/chamadas para o miniporto IHV.

    1. Chame MiniportWdiTalTxRxInitialize para inicializar o caminho de dados e os manipuladores de troca.
    2. Chame 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 do MiniportInitializeEx do Componente Microsoft. No entanto, até MiniportWdiStartOperation ser chamado, o componente da Microsoft não enviará nenhuma tarefa que precise de comunicação over-the-air. Exceto por OID_WDI_TASK_OPEN sempre sendo enviados primeiro, a ordem dos outros comandos/chamadas pode ser alterada.

    Usando dados obtidos do driver de miniporto 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.

    Esse é um manipulador de miniporto WDI opcional dentro NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS que o driver IHV pode usar para executar quaisquer tarefas adicionais do MiniportInitializeEx. Ele também pode ser utilizado pelo miniporto IHV como um indicativo de que o componente da Microsoft concluiu a inicialização do miniporto e o miniporto pode iniciar as atividades necessárias em segundo plano.

    O diagrama abaixo mostra o fluxo de MiniportInitializeEx.

    Fluxo de inicialização do miniporto WDI.

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

MiniportHaltEx

Em um miniporto nativo Wi-Fi, MiniportHaltEx é usado para instruir o miniporto a interromper as operações e limpar a instância do adaptador. No modelo WDI, o componente da Microsoft manipula a chamada miniportHaltEx original e a divide em várias chamadas de interface WDI.

  1. Call MiniportWdiStopOperation.

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

  2. Vários comandos WDI usando MiniportOidRequest.

    Após MiniportWdiStopOperation, o componente Microsoft envia tarefas/propriedades ao miniport IHV para limpar o estado atual do driver IHV. Essa limpeza pode incluir o seguinte.

    1. Chame OID_WDI_TASK_DISCONNECT/OID_WDI_TASK_STOP_AP para derrubar 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 desinitializar o caminho de dados.
    5. Chame 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 forem chamados, o componente da Microsoft chamará MiniportWdiFreeAdapter para que o driver IHV exclua qualquer estado de software que possa ter.

O diagrama abaixo mostra o fluxo de MiniportHaltEx.

fluxo de interrupção do miniport wdi.

O processamento MiniportHaltEx não será executado se o dispositivo for removido de surpresa ou se o sistema estiver sendo desligado. Para a 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 do miniporto WDI IHV ser descarregado. O driver de miniporto WDI IHV chama o componente da Microsoft para se desregistrar. O componente da Microsoft chama NdisMDeregisterMiniportDriver.

O diagrama abaixo mostra o fluxo de MiniportDriverUnload.

fluxo de descarregamento do driver do miniporto wdi.

MiniportPause

Os requisitos do NDIS MiniportPause são tratados pelo componente da Microsoft. Como parte do MiniportPause, o componente da Microsoft interrompe o caminho de dados e aguarda que ele seja limpo. Opcionalmente, o miniporto IHV do WDI pode registrar-se para um callback MiniportWdiPostAdapterPause, que é acionado pelo componente Microsoft após concluir a limpeza do caminho de dados.

O diagrama abaixo mostra o fluxo de MiniportPause.

fluxo de pausa do miniport WDI.

MiniportRestart

Os requisitos do NDIS MiniportRestart são tratados pelo componente da Microsoft. Como parte do MiniportRestart, o componente da Microsoft desfaz o trabalho de pausa do caminho de dados executado como parte do MiniportPause. Opcionalmente, o miniporto IHV do WDI pode se registrar para um retorno de chamada MiniportWdiPostAdapterRestart chamado pelo componente da Microsoft depois que ele terminar de reiniciar o caminho de dados.

O diagrama abaixo mostra o fluxo de MiniportRestart.

fluxo de reinicialização do miniporto WDI.

MiniportResetEx

MiniportResetEx não é tratado pelo componente da Microsoft. Opcionalmente, o miniporto IHV do WDI pode registrar-se para um callback MiniportResetEx que é chamado pelo componente da Microsoft.

MiniportDevicePnPEventNotify

MiniportDevicePnPEventNotify é usado para notificar um driver NDIS de eventos PNP, como a remoção surpresa de um dispositivo. Quando o NDIS envia essa notificação, ele é encaminhado pela primeira vez para o miniporto WDI IHV para processamento. Depois que o componente IHV terminar de processá-lo, o componente da Microsoft executará 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 do driver miniport WDI.

MiniportShutdownEx

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

O diagrama abaixo mostra o fluxo de MiniportShutdownEx.

fluxo de desligamento do miniporto wdi.

MiniportOidRequest

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

A chamada MiniportOidRequest para o miniporto WDI IHV deve ser considerada como a mensagem M1 para um comando WDI. A conclusão do OID (por meio de 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 em que um código NDIS_STATUS pode ser retornado para a operação: o código de status da chamada MiniportOidRequest (ou NdisMOidRequestComplete) e o código de status no campo WDI_MESSAGE_HEADER (na conclusão do OID ou por meio de NdisMIndicateStatusEx). O componente da Microsoft sempre verifica o NDIS_STATUS da conclusão do OID antes de examinar o campo WDI_MESSAGE_HEADERStatus. As expectativas do componente IHV para o processamento de OID WDI são as seguintes.

  1. Os OIDs do WDI são enviados para o componente IHV usando um NDIS_OID_REQUESTRequestType de NdisRequestMethod, e a mensagem e o comprimento da mensagem correspondentes estão nos campos DATA.METHOD_INFORMATION.InformationBuffer e DATA.METHOD_INFORMATION.InputBufferLength, respectivamente.
  2. O componente IHV relatará um erro na conclusão do OID se houver um erro durante o processamento do comando e definirá o campo Status do WDI_MESSAGE_HEADER como sem êxito se ele tiver uma falha no 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 é sempre definido como 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 concluir a 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 conclui o OID com NDIS_STATUS_BUFFER_TOO_SHORT e preenche o campo DATA.METHOD_INFORMATION.BytesNeeded. O componente da 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ó deverá ser indicado se a tarefa tiver sido relatada como iniciada com êxito-- a conclusão do OID é bem-sucedida e o Status no WDI_MESSAGE_HEADER na conclusão do OID foi bem-sucedido.

O diagrama a seguir mostra um exemplo de uma solicitação OID do NDIS que é mapeada 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 do WDI e envia a solicitação OID do WDI para o miniporto IHV. Quando o miniporto IHV conclui o OID, o componente da Microsoft conclui adequadamente a solicitação OID original.

Sequência de solicitação de OID do miniport WDI para comando único WDI.

Se o OriginalOidRequest for mapeado para vários WDI OidRequests e uma das solicitações WDI falhar, 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 dão suporte à limpeza.

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

sequência de solicitação de oid do miniport wdi para oids tratados pelo componente da microsoft.

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

sequência de solicitação oid miniport wdi para oids não tratados pelo componente microsoft.

O comportamento de MiniportOidRequest é inalterado para o driver de miniporto WDI IHV (em comparação com um miniporto de Wi-Fi nativo). As chamadas são serializadas e o miniporto IHV pode completá-lo de forma síncrona ou assíncrona com uma chamada para NdisMOidRequestComplete.

MiniportCancelOidRequest

Este é um manipulador opcional usado por um miniporto IHV WDI que necessita lidar com OIDs que não são mapeados para mensagens WDI. Esse manipulador não é usado para os OIDs do WDI. Os OIDs do WDI devem ser concluídos rapidamente, e não há necessidade de o driver de miniporto do IHV tentar 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 pelo miniporto WDI IHV para enviar indicações ao componente da Microsoft. As indicações podem ser indicações não solicitadas, como falhas de MIC TKIP 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 correspondente indicação NDIS/Native Wi-Fi. Quando a indicação é enviada pelo miniporto IHV para o componente da Microsoft, o componente da Microsoft converte-o em uma indicação existente e encaminha-o para o sistema operacional.

fluxo de indicação de status do miniporto wdi.

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

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

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

indicação de status wdi não reconhecida pelo componente da Microsoft.

O comportamento de NdisMIndicateStatusEx é inalterado para o driver de miniporto WDI IHV (em comparação com um miniporto Nativo Wi-Fi).

MiniportDirectOidRequest

Esse é um manipulador opcional que é registrado por um driver de miniporto WDI IHV se precisar lidar com OIDs Diretos que não são mapeados para mensagens WDI. Todos os OIDs Diretos existentes para Wi-Fi Direct são mapeados para mensagens WDI, portanto, esse manipulador não é necessário para dar suporte a essa funcionalidade. Os OIDs Diretos sem suporte não são serializados pelo componente da Microsoft.

MiniportCancelDirectOidRequest

Este é um gerenciador opcional usado por um miniporto WDI IHV que precisa lidar com OIDs Diretos que não são associados a mensagens WDI. Para OIDs não mapeados, o comportamento esperado é definido pelo NDIS.

MiniportSendNetBufferLists

Esse manipulador não é usado em um driver de miniporto WDI IHV e não deve ser fornecido. O componente da Microsoft usa os manipuladores de trajetória de dados registrados através de NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS para encaminhar pacotes de envio para o miniporto IHV.

MiniportCancelSend

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

MiniportReturnNetBufferLists

Esse manipulador não é usado em um driver WDI IHV Miniport e não deve ser fornecido. O componente da Microsoft usa os manipuladores de caminho de dados registrados através de NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS para retornar pacotes recebidos ao miniporto IHV.

Manipulador WDI: MiniportWdiOpenAdapter

O manipulador MiniportWdiOpenAdapter é usado pelo componente da Microsoft para iniciar a operação Tarefa Aberta 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 nesta chamada e chamar o manipulador OpenAdapterComplete que é passado para o parâmetro NDIS_WDI_INIT_PARAMETERS de MiniportWdiAllocateAdapter.

Manipulador WDI: MiniportWdiCloseAdapter

O manipulador MiniportWdiCloseAdapter é usado pelo componente da Microsoft para iniciar a operação Fechar 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 nesta chamada e chamar o manipulador CloseAdapterComplete que é passado para o parâmetro NDIS_WDI_INIT_PARAMETERS do MiniportWdiAllocateAdapter.

  • Last updated on