MINIPORT_PNP_IRP função de retorno de chamada (ndis.h)

Artigo
02/07/2025

A função MiniportPnpIrp permite que um driver de miniporto gerencie opcionalmente seus recursos de PnP (Plug and Play). MiniportPnpIrp em si nunca é definido diretamente por miniportores. Em vez disso, ele é definido como MiniportFilterResourceRequirements ou MiniportStartDevice.

Se definido como MiniportFilterResourceRequirements, essa função permite que um driver de miniporte modifique os requisitos de recursos de um dispositivo. Se definido como MiniportStartDevice, essa função permite que o driver de miniporte remova os recursos que ele adicionou no função MiniportFilterResourceRequirements.

Observação Você deve declarar essa função usando o tipo de MINIPORT_FILTER_RESOURCE_REQUIREMENTS ou o tipo MINIPORT_START_DEVICE. Para obter mais informações, consulte a seção Exemplos a seguir.

Sintaxe

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

Parâmetros

[in] MiniportAddDeviceContext

Um identificador para uma área de contexto alocada por driver que o driver de miniporto registrou com NDIS na função miniportAddDevice.

[in] Irp

Se essa função for definida como MiniportFilterResourceRequirements, esse parâmetro será um ponteiro para o IRP_MN_FILTER_RESOURCE_REQUIREMENTS para o driver manipular.

Se essa função for definida como MiniportStartDevice, esse parâmetro será um ponteiro para um IRP IRP_MN_START_DEVICE.

Valor de retorno

MiniportPnpIrp retorna um dos seguintes valores:

Código de retorno	Descrição
NDIS_STATUS_SUCCESS	O driver de miniporto lidou com a solicitação de dispositivo inicial com êxito.
NDIS_STATUS_RESOURCES	O driver de miniporto não pôde lidar com a solicitação de dispositivo inicial devido a recursos baixos.
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements falharam por motivos diferentes de recursos insuficientes.

Observações

Comentários MiniportFilterResourceRequirements

A função MiniportFilterResourceRequirements é uma função opcional. Os drivers de miniporto deverão registrar essa função se derem suporte a MSI-X e pelo menos um dos seguintes for verdadeiro:

O driver requer a capacidade de alterar a afinidade de interrupção para cada mensagem MSI-X.
O driver se registrará para interrupções baseadas em linha no função MiniportInitializeEx.

Para registrar MiniportFilterResourceRequirements, especifique o ponto de entrada no NDIS_MINIPORT_PNP_CHARACTERISTICS estrutura.

O NDIS chama a função MiniportFilterResourceRequirements após o NDIS receber um IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP para uma NIC (placa de interface de rede). Chamadas NDIS MiniportFilterResourceRequirements depois que os drivers de função subjacentes na pilha de dispositivos concluíram o processamento do IRP.

O driver de miniporto deve estar preparado para lidar com IRP_MN_FILTER_RESOURCE_REQUIREMENTS de miniportFilterResourceRequirements imediatamente após a função MiniportAddDevice retornar NDIS_STATUS_SUCCESS.

Um driver de miniporto pode definir uma política de afinidade para cada recurso do tipo CmResourceTypeInterrupt que descreve uma mensagem MSI-X. Se uma política de afinidade solicitar o direcionamento para um conjunto específico de processadores, o driver de miniporto também definirá uma máscaraKAFFINITYno membro Interrupt.TargetedProcessors na estrutura IO_RESOURCE_DESCRIPTOR.

Se um driver de miniporto NDIS 6.1 ou posterior exigir mais recursos de interrupção de mensagem, ele poderá adicionar mais recursos de interrupção de mensagem à lista de recursos. Se o sistema operacional puder fornecer mais recursos de interrupção de mensagem, o adaptador de miniporto receberá os recursos de interrupção de mensagem adicionados quando ele for iniciado.

Cada recurso de interrupção de mensagem na lista recebe um número de mensagem que corresponde à ordem que ele tem na lista de recursos. As mensagens são numeradas de 0 até o número total de recursos de interrupção de mensagem menos um.

Para atribuir uma entrada de tabela MSI-X a uma CPU em tempo de execução, o driver de miniporto pode chamar o função de NdisMConfigMSIXTableEntry.

Um driver de miniporto pode remover todos os recursos do tipo CmResourceTypeInterrupt que são recursos de interrupção de mensagem. Em seguida, o driver pode registrar-se para interrupções baseadas em linha na função MiniportInitializeEx. Se o driver de miniporto não remover esses recursos de interrupção de mensagem, o sistema operacional falhará se o driver tentar registrar a interrupção baseada em linha no MiniportInitializeEx.

Para alocar memória para uma nova lista de requisitos de recursos, use o função NdisAllocateMemoryWithTagPriority. O driver de miniporto pode liberar a memória da lista de requisitos de recursos antigos com a função NdisFreeMemory. O gerenciador PnP libera qualquer memória alocada por driver após a conclusão do IRP associado.

Os drivers de miniporto não devem modificar outros recursos, como CmResourceTypeMemory e recursos CmResourceTypePort. Os drivers de miniporto devem evitar a adição de um novo recurso à lista de recursos. No entanto, os drivers de miniporto podem adicionar mais recursos de interrupção de mensagem. Se o driver de miniporto adicionar mais recursos de interrupção de mensagem, o driver não deverá removê-los da função MiniportStartDevice.

Se um driver de miniporto retornar NDIS_STATUS_RESOURCES ou NDIS_STATUS_FAILURE de MiniportFilterResourceRequirements, o NDIS usará os requisitos de recurso, conforme especificado pelo motorista do ônibus pai.

O NDIS pode chamar MiniportFilterResourceRequirements várias vezes antes que o NDIS chame a função MiniportRemoveDevice. Mas o NDIS chama MiniportFilterResourceRequirements somente quando um dispositivo está no estado interrompido.

Chamadas NDIS MiniportFilterResourceRequirements em IRQL = PASSIVE_LEVEL.

Exemplo MiniportFilterResourceRequirements

Para definir uma função MiniportFilterResourceRequirements, primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda Análise de Código para Drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função MiniportFilterResourceRequirements denominada "MyFilterResourceRequirements", use o tipo MINIPORT_FILTER_RESOURCE_REQUIREMENTS conforme mostrado neste exemplo de código:

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

Em seguida, implemente sua função da seguinte maneira:

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

O tipo de função MINIPORT_FILTER_RESOURCE_REQUIREMENTS é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função MINIPORT_FILTER_RESOURCE_REQUIREMENTS no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Comentários do MiniportStartDevice

MiniportStartDevice é uma função opcional. Os drivers de miniport que dão suporte a MSI-X podem especificar um ponto de entrada para essa função no NDIS_MINIPORT_PNP_CHARACTERISTICS estrutura. Quando o NDIS recebe uma solicitação do gerenciador PnP (Plug and Play) para iniciar um dispositivo, o NDIS chama a função MiniportStartDevice, se houver. Se um driver de miniporto adicionar novos recursos no função MiniportFilterResourceRequirements, ela deve fornecer uma função MiniportStartDevice para remover os recursos.

Se um driver de miniporto modificar recursos de forma que um motorista de ônibus subjacente não possa reconhecer os recursos, o driver deverá fornecer uma função MiniportStartDevice para remover os recursos. Um motorista de ônibus subjacente poderá falhar em uma solicitação de dispositivo inicial se não reconhecer recursos que um driver de miniporto adicionou em MiniportFilterResourceRequirements. Se o driver de miniporto adicionar recursos de interrupção de mensagem, ele não deverá removê-los de MiniportStartDevice.

O NDIS chama MiniportStartDevice antes de encaminhar a solicitação de dispositivo inicial para os drivers subjacentes. Se um driver subjacente concluir a solicitação com êxito, o NDIS chamará a função MiniportInitializeEx para inicializar o adaptador de miniporto.

Chamadas NDIS miniportStartDevice no IRQL = PASSIVE_LEVEL.

Exemplo MiniportStartDevice

Para definir uma função MiniportStartDevice, primeiro você deve fornecer uma declaração de função que identifique o tipo de função que você está definindo. O Windows fornece um conjunto de tipos de função para drivers. Declarar uma função usando os tipos de função ajuda Análise de Código para Drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função MiniportStartDevice chamada "MyStartDevice", use o tipo MINIPORT_START_DEVICE conforme mostrado neste exemplo de código:

MINIPORT_START_DEVICE MyStartDevice;

Em seguida, implemente sua função da seguinte maneira:

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

O tipo de função MINIPORT_START_DEVICE é definido no arquivo de cabeçalho Ndis.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função MINIPORT_START_DEVICE no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers NDIS.

Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Com suporte no NDIS 6.0 e posterior.
da Plataforma de Destino	Windows
cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL