Interfaces do driver IHV da 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 de miniporto WLAN nativo para os manipuladores NDIS são divididas entre o componente MS e o driver IHV do WDI. O componente WLAN da Microsoft cuida dos requisitos de NDIS aplicáveis a todos os miniportos Wi-Fi para que cada IHV não precise refazer todo esse trabalho. O mapeamento de e as alterações de comportamento para os manipuladores NDIS para o miniporto IHV da WLAN nativa quando aplicado a um miniporto IHV WDI são descritos abaixo.

• Instalação do driver
• DriverEntry
• MiniportSetOptions
• MiniportInitializeEx
• MiniportHaltEx
• MiniportDriverUnload
• MiniportPause
• MiniportRestart
• MiniportResetEx
• MiniportDevicePnPEventNotify
• MiniportShutdownEx
• MiniportOidRequest
• MiniportCancelOidRequest
• NdisMIndicateStatusEx
• MiniportDirectOidRequest
• MiniportCancelDirectOidRequest
• MiniportSendNetBufferLists
• MiniportCancelSend
• MiniportReturnNetBufferLists
• Manipulador WDI: MiniportWdiOpenAdapter
• Manipulador WDI: MiniportWdiCloseAdapter

Instalação do driver

Não há alterações na forma 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 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 miniportO WDI IHV. O miniporto IHV segue a maioria das diretrizes da rotina driverEntry de um miniporto NDIS regular. A única exceção é que, em vez de chamar NdisMRegisterMiniportDriver, o miniporto IHV chama NdisMRegisterWdiMiniportDriver para informar ao sistema operacional para habilitar o componente WLAN da Microsoft.

Veja a seguir os principais parâmetros de NdisMRegisterWdiMiniportDriver.

• NDIS_MINIPORT_DRIVER_CHARACTERISTICS: essa é a estrutura NDIS original que um miniporto native Wi-Fi usa para 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 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 manipuladores de NDIS_MINIPORT_DRIVER_CHARACTERISTICS e chama 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 ao driver de miniporto WDI IHV.

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

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

MiniportSetOptions

Conforme mostrado no diagrama 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 que chama 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 quaisquer requisitos de sincronização para esses manipuladores.

MiniportInitializeEx

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

1. Chame MiniportWdiAllocateAdapter.

   Quando o sistema operacional encontra uma instância do hardware IHV, essa é a primeira chamada para o driver de miniporto IHV da WDI. Nessa 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 de 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 baixo 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. Chame MiniportWdiOpenAdapter.

   Após 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 tarefas/propriedades/chamadas a seguir 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 MiniportInitializeEx do Componente da Microsoft. No entanto, até que MiniportWdiStartOperation seja 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. Chame MiniportWdiStartOperation.

   Esse é um manipulador de miniporto WDI opcional dentro de NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS que o driver IHV pode usar para executar tarefas adicionais do MiniportInitializeEx. Ele também pode ser usado pelo miniporto IHV como uma dica de que o componente da Microsoft terminou de inicializar o miniporto e o miniporto pode iniciar as atividades em segundo plano necessárias.

   O diagrama abaixo mostra o fluxo de MiniportInitializeEx.

   

   Se uma operação intermediária falhar, o componente da Microsoft desfaz as operações anteriores e falha no 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 de Wi-Fi nativo, MiniportHaltEx é usado para informar o miniporto para interromper operações e limpo 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. Chame 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 da Microsoft envia tarefas/propriedades para o miniporto IHV para limpo 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 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 limpo 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 a seguir mostra o fluxo de MiniportHaltEx.

O processamento de MiniportHaltEx não será executado 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 desligamento do sistema, consulte o comportamento do manipulador MiniportShutdownEx .

MiniportDriverUnload

MiniportDriverUnload é o manipulador que é chamado antes que o miniporto IHV WDI seja descarregado. O driver de miniporto WDI IHV chama o componente da Microsoft para cancelar o registro em si. O componente da Microsoft chama NdisMDeregisterMiniportDriver.

O diagrama a seguir mostra o fluxo de MiniportDriverUnload.

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 limpo para cima. O miniporto WDI IHV pode, opcionalmente, registrar-se para um retorno de chamada MiniportWdiPostAdapterPause que é chamado pelo componente da Microsoft depois de concluir a limpeza do caminho de dados.

O diagrama a seguir mostra o fluxo de MiniportPause.

MiniportRestart

Os requisitos do MiniportRestart do NDIS 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. O miniporto IHV do WDI pode, opcionalmente, registrar-se para um retorno de chamada MiniportWdiPostAdapterRestart que é chamado pelo componente da Microsoft depois de concluir a reinicialização do caminho de dados.

O diagrama a seguir mostra o fluxo de MiniportRestart.

MiniportResetEx

MiniportResetEx não é manipulado pelo componente da Microsoft. O miniporto IHV do WDI pode, opcionalmente, registrar-se para um retorno de chamada 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 que é encaminhada para o componente IHV não é serializada com outras tarefas e retornos de chamada.

O diagrama a seguir mostra o fluxo de MiniportDevicePnPEventNotify.

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 a seguir mostra o fluxo de MiniportShutdownEx.

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

1. Os OIDs 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 no DATA. METHOD_INFORMATION. InformationBuffer e DATA. METHOD_INFORMATION. Campos 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 de nível de Wi-Fi.
3. Para tarefas e propriedades, o número da porta da solicitação está no campo WDI_MESSAGE_HEADER PortId. 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 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 DATA. METHOD_INFORMATION. O campo OutputBufferLength para preencher a resposta conclui o OID com NDIS_STATUS_BUFFER_TOO_SHORT e preenche os DADOS. METHOD_INFORMATION. Campo 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 foi 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 WDI e envia a solicitação OID WDI para o miniporto IHV. Quando o miniporto IHV conclui o OID, o componente da Microsoft conclui adequadamente a solicitação OID original.

Se 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 a limpo.

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

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

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 concluí-lo de forma síncrona ou assíncrona com uma chamada para NdisMOidRequestComplete.

MiniportCancelOidRequest

Esse é um manipulador opcional usado por um miniporto IHV WDI que precisa 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 IHV tentar cancelar um OID pendente. O cancelamento de tarefas WDI é tratado usando a solicitação OID de tarefa de cancelamento apropriada. 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 a seguir mostra um exemplo de uma indicação WDI que tem uma indicação de Wi-Fi NDIS/Nativo correspondente. Quando a indicação é enviada pelo miniporto IHV para o componente da Microsoft, o componente da Microsoft a converte em uma indicação existente e a encaminha para o sistema operacional.

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

O diagrama a seguir mostra uma indicação que não é reconhecida pelo componente da Microsoft. A indicação é encaminhada no estado em que se encontra para o sistema operacional.

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

MiniportDirectOidRequest

Esse é um manipulador opcional que é registrado por um driver de miniporto IHV WDI 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

Esse é um manipulador opcional usado por um miniporto IHV WDI que precisa lidar com OIDs Diretos que não são mapeados para 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 caminho de dados registrados por meio de NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS para enviar pacotes 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 por meio de NDIS_MINIPORT_DRIVER_WDI_CHARACTERISTICS para retornar pacotes recebidos para o miniporto IHV.

Manipulador WDI: MiniportWdiOpenAdapter

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