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

Artigo
08/07/2023

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

Se definida como MiniportFilterResourceRequirements, essa função permitirá que um driver de miniporte modifique os requisitos de recurso para um dispositivo. Se definida como MiniportStartDevice, essa função permitirá que o driver de miniporte remova os recursos que ele adicionou no Função MiniportFilterResourceRequirements .

Nota Você deve declarar essa função usando o tipo 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 pelo 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 .

Retornar valor

MiniportPnpIrp retorna um dos seguintes valores:

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

Comentários

Comentários de MiniportFilterResourceRequirements

A função MiniportFilterResourceRequirements é uma função opcional. Os drivers de miniporte devem registrar essa função se oferecerem suporte a MSI-X e pelo menos um dos seguintes valores 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 depois que o NDIS recebe um IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP para uma NIC (cartão de interface de rede). O NDIS chama MiniportFilterResourceRequirements depois que os drivers de função subjacentes na pilha de dispositivos concluíram o processamento do IRP.

O driver de miniporte 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 miniporte 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áscara KAFFINITY no 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 NdisMConfigMSIXTableEntry .

Um driver de miniporte pode remover todos os recursos do tipo CmResourceTypeInterrupt que são recursos de interrupção de mensagem. Em seguida, o driver pode se registrar 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 miniporte pode liberar a memória para a lista antiga de requisitos de recursos 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 miniport não devem modificar outros recursos, como os recursos CmResourceTypeMemory e CmResourceTypePort . Os drivers de miniporte devem evitar adicionar um novo recurso à lista de recursos. No entanto, os drivers de miniport 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 miniporte 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.

O NDIS chama MiniportFilterResourceRequirements em IRQL = PASSIVE_LEVEL.

Exemplo de 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 a 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 chamada "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.

MiniportStartDevice Remarks

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 de Plug and Play (PnP) 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 miniporte 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 barramento 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 com êxito a solicitação, o NDIS chamará a função MiniportInitializeEx para inicializar o adaptador de miniporte.

O NDIS chama MiniportStartDevice em IRQL = PASSIVE_LEVEL.

Exemplo de 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 a 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
Cliente mínimo com suporte	Com suporte no NDIS 6.0 e posterior.
Plataforma de Destino	Windows
Cabeçalho	ndis.h (inclua Ndis.h)
IRQL	PASSIVE_LEVEL