Portando drivers de miniporta NDIS para NetAdapterCx

Artigo
05/03/2024

Esta página descreve como converter um driver de miniporta NDIS 6.x em um driver de cliente NetAdapterCx.

Para obter informações gerais sobre o WDF, consulte o Guia de desenvolvimento de drivers WDF.

Configurações de compilação

Abra seu projeto de driver de miniporta NDIS existente no Visual Studio e use as etapas a seguir para convertê-lo em um projeto KMDF.

Primeiro, navegue até Configuration Properties-Driver> Settings-Driver> Model e verifique se Type of driver está definido como KMDF e se KMDF Version Major e KMDF Version Minor estão vazios.
Nas propriedades do projeto, abra Driver Settings-Network> Adapter Driver e defina Link para a Extensão de Classe do Adaptador de Rede como Sim.
- Se o driver convertido ainda chamar APIs NDIS, continue vinculando ao ndis.lib.
Remova macros de pré-processador NDIS, como NDIS650_MINIPORT=1.
Adicione os seguintes cabeçalhos a cada arquivo de origem (ou ao seu cabeçalho comum/pré-compilado):
```
#include <ntddk.h>
#include <wdf.h>
#include <netadaptercx.h>
```

Adicione decorações WDF padrão ao seu INF:

[Yourdriver.Wdf]
KmdfService = Yourdriverservice, Yourdriver.wdfsect

[Yourdriver.wdfsect]
KmdfLibraryVersion = <insert here>

Adicione novas palavras-chave de rede necessárias à seção NT do seu INF:
- *IfConnectorPresent
- *Tipo de conexão
- *DirectionType
- *Tipo de Acesso
- *HardwareLoopback
  
  Para obter mais informações sobre essas palavras-chave e um exemplo, consulte Arquivos INF para drivers de cliente NetAdapterCx.

Inicialização do driver

Remova a chamada para NdisMRegisterMiniportDriver de DriverEntry e adicione o seguinte:

WDF_DRIVER_CONFIG_INIT(&config, EvtDriverDeviceAdd);
status = WdfDriverCreate(. . . );
if (!NT_SUCCESS(status)) {
  return status;
}

Se estiver definido, remova o sinalizador WdfDriverInitNoDispatchOverride da chamada para WdfDriverCreate.

DriverUnload é uma rotina opcional para um driver de cliente de rede WDF, para que você possa removê-lo se desejar. Não chame NdisMDeregisterMiniportDriver de DriverUnload.

Inicialização do dispositivo

Em seguida, você distribuirá o código de MiniportInitializeEx para os manipuladores de retorno de chamada de eventos WDF apropriados, vários dos quais são opcionais. Para obter detalhes sobre a sequência de retorno de chamada, consulte Sequência de inicialização para um driver de cliente WDF do adaptador de rede.

Você chamará os métodos equivalentes a NdisMSetMiniportAttributes quando estiver iniciando o adaptador de rede, mas antes de chamar NetAdapterStart. No entanto, em vez de chamar uma rotina com uma estrutura de NDIS_MINIPORT_ADAPTER_ATTRIBUTES genérica, o driver cliente chama funções diferentes para definir diferentes tipos de recursos.

Para obter informações sobre os retornos de chamada que você precisará fornecer e quando iniciar um adaptador de rede, consulte Inicialização de dispositivo e adaptador.

Lendo a configuração do registro

Em seguida, substitua chamadas para NdisOpenConfigurationEx e funções relacionadas com os NetConfiguration* métodos. Os NetConfiguration* métodos são semelhantes às Ndis*Configuration* funções e você não precisará reestruturar seu código.

Para obter mais informações, consulte Acessando informações de configuração.

Recebendo códigos de controle de E/S (IOCTLs) do modo de usuário

Leia esta seção se o driver NDIS chamar NdisRegisterDeviceEx, uma rotina usada para criar um objeto de dispositivo de controle (CDO) para receber IOCTLs do modo de usuário.

Aqui estão duas maneiras de fazer isso no driver do cliente de rede WDF.

A porta mais simples é criar um objeto de dispositivo de controle chamando WdfControlDeviceInitAllocate a partir do retorno de chamada EVT_WDF_DRIVER_DEVICE_ADD do cliente. Para obter mais informações, consulte Usando objetos de dispositivo de controle.

No entanto, a solução recomendada é criar uma interface de dispositivo, conforme descrito em Usando interfaces de dispositivo.

Finalizando a inicialização do dispositivo

Neste ponto do EVT_WDF_DRIVER_DEVICE_ADD, você pode fazer qualquer outra coisa que quiser inicializar seu dispositivo, como alocar interrupções.

Manipulando notificações de alteração de estado de energia

Um driver de cliente WDF não recebe OID_PNP_SET_POWER para alterações de estado de energia.

Em vez disso, um cliente WDF registra funções opcionais de retorno de chamada para receber notificações de alteração de estado de energia. Para obter uma visão geral, consulte Suporte a PnP e gerenciamento de energia em drivers de função.

Normalmente, o código no manipulador de OID_PNP_SET_POWER se move para EVT_WDF_DEVICE_D0_EXIT e EVT_WDF_DEVICE_D0_ENTRY.

Como a máquina de estado de energia WDF é ligeiramente diferente, talvez seja necessário fazer pequenas modificações no código.

Especificamente, em sua função de retorno de chamada MiniportInitializeEx , um driver de miniporta NDIS executa tarefas de inicialização únicas, bem como trabalha para trazer o dispositivo para o estado D0. Em seguida, ele repete o trabalho para ir para D0 em seu manipulador OID_PNP_SET_POWER.

Por outro lado, um cliente WDF executa tarefas de inicialização únicas em retornos de chamada de eventos antes da EVT_WDF_DEVICE_D0_ENTRY, durante a qual o dispositivo está em um estado de baixo consumo de energia. Depois, faz o trabalho de ir para D0 em EVT_WDF_DEVICE_D0_ENTRY.

Para resumir, no WDF, você coloca seu código "ir para D0" em um lugar, em vez de dois.

Para obter detalhes sobre a sequência de retorno de chamada, consulte Sequência de inicialização para um driver de cliente NetAdapterCx.

Consultando e definindo recursos de gerenciamento de energia

Da mesma forma, um driver de cliente WDF não recebe OID_PM_PARAMETERS para consultar ou definir recursos de hardware de gerenciamento de energia do adaptador de rede.

Em vez disso, o driver consulta a configuração necessária de wake-on-LAN (WoL) do objeto NETPOWERSETTINGS. Para obter mais informações, consulte Configurando o gerenciamento de energia.

Os sinalizadores reais que você recebe de volta têm a mesma semântica que eles têm para uma miniporta NDIS 6, então você não precisa fazer alterações profundas na lógica. A principal diferença é que agora você pode consultar esses sinalizadores durante a sequência de desligamento. Consulte Sequência de desligamento para um driver de cliente NetAdapterCx.

Depois de mover esse código, você pode excluir seus manipuladores OID para OID_PNP_SET_POWER e OID_PM_PARAMETERS.

Como a estrutura NetAdapter mantém seu dispositivo em D0 enquanto o host usa a interface de rede, o cliente normalmente não implementa a lógica de energia; o comportamento de energia padrão do NetAdapter é suficiente.

Caminho de dados

O modelo de programação de caminho de dados mudou significativamente. Aqui estão algumas diferenças principais:

No modelo NetAdapter, o tráfego de rede não é mais por adaptador, como no NDIS, mas sim por fila WDF. Consulte Criando filas de E/S.
Em vez de pools de NET_BUFFER_LIST e NET_BUFFER, o NetAdapterCx introduz um buffer de anel que é composto por pacotes de rede, que são mapeados para NDIS da seguinte maneira:
- Um NET_PACKET é semelhante a um NET_BUFFER_LIST + NET_BUFFER.
- Um NET_PACKET_FRAGMENT é semelhante a uma lista de descritores de memória (MDL). Cada NET_PACKET tem um ou mais desses.
- Para obter detalhes sobre as estruturas de substituição e como usá-las, consulte Descritores e extensões de pacote.
No NDIS 6.x, a miniporta precisa lidar com a semântica de início e pausa. No modelo NetAdapterCx, esse não é mais o caso.
O retorno de chamada EVT_RXQUEUE_ADVANCE é semelhante ao MINIPORT_RETURN_NET_BUFFER_LISTS no NDIS 6.x.
O retorno de chamada EVT_TXQUEUE_ADVANCE é semelhante ao MINIPORT_SEND_NET_BUFFER_LISTS no NDIS 6.x.

Remoção de dispositivo

A remoção de dispositivo para um driver de NIC WDF é a mesma que em qualquer outro driver de dispositivo WDF, sem necessidade de processamento específico de rede. O caminho de dados de rede é desligado primeiro, seguido pelo dispositivo WDF. Para obter informações sobre o desligamento do WDF, consulte Um usuário desconecta um dispositivo.

Seu manipulador MiniportHaltEx provavelmente será distribuído entre EVT_WDF_DEVICE_D0_EXIT e EVT_WDF_DEVICE_RELEASE_HARDWARE.

O cliente WDF não precisa excluir o NetAdapter ou qualquer uma das filas de caminho de dados que ele criou. O WDF exclui esses objetos automaticamente.

Você pode excluir MiniportShutdownEx, MiniportResetEx e MiniportCheckForHangEx. Esses retornos de chamada não são mais suportados.

Equivalentes da função NDIS-WDF

A maioria das NdisXxx funções pode ser substituída por um equivalente WDF. Em geral, você deve achar que precisa de muito pouca funcionalidade importada do NDIS.SYS.

Para obter uma lista de equivalentes de função, consulte Equivalentes de função NDIS-WDF.

Depuração

Consulte Depurando um driver cliente NetAdapterCx.

A extensão do depurador !ndiskd.netadapter mostra resultados semelhantes ao que !ndiskd.miniport mostra para um driver NDIS 6.

Conclusão

Usando as etapas neste tópico, você deve ter um driver funcional que inicia e pára o dispositivo.

Nota: NetAdapterCx atualmente não suporta inicialização iSCSI.

Compartilhar via