OID_RECEIVE_FILTER_SET_FILTER

Article
06/15/2023

Un pilote qui se superpose émet une demande de méthode OID de OID_RECEIVE_FILTER_SET_FILTER pour définir un filtre sur une carte réseau.

Le membre InformationBuffer de la structure NDIS_OID_REQUEST contient un pointeur vers une mémoire tampon allouée à l’appelant. Cette mémoire tampon est mise en forme pour contenir les éléments suivants :

Structure NDIS_RECEIVE_FILTER_PARAMETERS qui spécifie les paramètres d’un filtre de réception NDIS.
Tableau de structures NDIS_RECEIVE_FILTER_FIELD_PARAMETERS qui spécifie le critère de test de filtre pour un champ dans un en-tête de paquet réseau.

Après un retour réussi à partir de la demande de méthode OID, le membre InformationBuffer de la structure NDIS_OID_REQUEST contient un pointeur vers une structure NDIS_RECEIVE_FILTER_PARAMETERS . Si le pilote qui se superpose crée un filtre de réception, NDIS met à jour cette structure avec un nouvel identificateur de filtre.

Notes

Les filtres de réception NDIS sont utilisés dans les interfaces NDIS suivantes :

NDIS Packet Coalescing. Pour plus d’informations sur l’utilisation des filtres de réception dans cette interface, consultez Gestion des filtres de réception de coalescing de paquets.
Virtualisation d’E/S racine unique (SR-IOV). Pour plus d’informations sur l’utilisation des filtres de réception dans cette interface, consultez Définition d’un filtre de réception sur un port virtuel.
Virtual Machine Queue (VMQ). Pour plus d’informations sur l’utilisation des filtres de réception dans cette interface, consultez Définition et suppression des filtres VMQ.

La demande de méthode OID de OID_RECEIVE_FILTER_SET_FILTER est obligatoire pour les pilotes miniports qui prennent en charge l’interface de fusion de paquets NDIS, SR-IOV ou VMQ.

Le pilote overlying initialise la structure NDIS_RECEIVE_FILTER_PARAMETERS avec sa configuration de filtre demandée. NDIS affecte un identificateur de filtre dans le membre FilterId de la structure NDIS_RECEIVE_FILTER_PARAMETERS et transmet la demande de méthode au pilote miniport sous-jacent.

Chaque filtre défini sur une file d’attente de réception a un identificateur de filtre unique pour une carte réseau. Autrement dit, les identificateurs de filtre ne sont pas dupliqués sur les différentes files d’attente que la carte réseau gère. Quand NDIS reçoit une demande OID pour définir un filtre sur une file d’attente de réception, il vérifie les paramètres de filtre. Une fois que NDIS alloue les ressources nécessaires et l’identificateur de filtre, il envoie la demande OID à la carte réseau sous-jacente. Si la carte réseau peut allouer correctement les ressources logicielles et matérielles nécessaires pour le filtre, elle termine la requête OID avec une status de retour de NDIS_STATUS_SUCCESS.

Note À compter de NDIS 6.30, le filtre de réception de fusion de paquets est uniquement pris en charge sur la file d’attente de réception par défaut de la carte réseau. Cette file d’attente de réception a un identificateur de NDIS_DEFAULT_RECEIVE_QUEUE_ID.

Le pilote miniport doit conserver les identificateurs de filtre pour les filtres de réception alloués. NDIS utilise l’identificateur d’un filtre dans les requêtes OID ultérieures pour modifier les paramètres de filtre de réception ou effacer le filtre de réception.

Une fois qu’un pilote miniport reçoit une requête OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE et qu’il a des filtres définis sur la file d’attente, la file d’attente est à l’état En cours d’exécution. Dans cet état, le pilote miniport peut démarrer des indications de paquets dans la file d’attente en appelant NdisMIndicateReceiveNetBufferLists.

Instructions supplémentaires pour l’interface SR-IOV

Les points suivants s’appliquent aux pilotes miniport qui prennent en charge l’interface SR-IOV :

Pour l’interface SR-IOV, une file d’attente de réception est créée sur un port virtuel par défaut ou non par défaut (VPort).

Note À compter de Windows Server 2012, l’interface SR-IOV prend uniquement en charge la file d’attente de réception par défaut d’un VPort.

Une fois qu’un VPort SR-IOV est alloué par le biais d’une demande de jeu OID de OID_NIC_SWITCH_CREATE_VPORT, les pilotes surdimensionnels peuvent définir des filtres sur le VPort avec les requêtes OID de OID_RECEIVE_FILTER_SET_FILTER.

Note Seul le pilote qui a alloué le VPort peut définir un filtre sur ce VPort.
Étant donné que le VPort par défaut existe toujours, les pilotes surclassés peuvent toujours définir un filtre sur le VPort par défaut.
Lorsque le VPort est créé, aucun filtre de réception n’est défini sur celui-ci. Dans ce cas, le pilote miniport ne doit pas indiquer de paquets de réception sur ce VPort avant que le pilote miniport ne reçoive une requête OID de OID_RECEIVE_FILTER_SET_FILTER pour le VPort. Une fois cette demande OID émise, le pilote miniport peut indiquer des paquets sur ce VPort.

Note Si le pilote miniport indique des paquets sur un VPort pendant qu’il traite une requête OID de OID_RECEIVE_FILTER_SET_FILTER, il doit terminer la requête OID et retourner un code NDIS_STATUS_SUCCESS status.

Instructions supplémentaires pour l’interface VMQ

Les points suivants s’appliquent aux pilotes miniport qui prennent en charge l’interface VMQ :

Une fois qu’une file d’attente de réception vmQ est allouée, les pilotes qui mentent trop peuvent définir des filtres sur la file d’attente de réception avec les requêtes OID de OID_RECEIVE_FILTER_SET_FILTER.

Note Seul le pilote de protocole qui a alloué une file d’attente de réception peut définir un filtre sur cette file d’attente.
Étant donné que la file d’attente par défaut existe toujours, les pilotes trop trop peuvent toujours définir un filtre sur la file d’attente par défaut. Si la carte réseau prend en charge une file d’attente de suppression, les pilotes trop étendus peuvent définir un filtre sur la file d’attente de suppression.

Les pilotes qui se superposent ne possèdent pas les files d’attente par défaut ou suppriment. Par conséquent, tous les pilotes de protocole liés à une carte réseau utilisent la file d’attente par défaut ou de suppression.
Lorsque la file d’attente de réception est créée, aucun filtre de réception n’y est défini. Dans ce cas, le pilote miniport ne doit pas indiquer de paquets de réception sur cette file d’attente de réception avant que le pilote miniport ne reçoive une requête OID de OID_RECEIVE_FILTER_SET_FILTER pour la file d’attente de réception. Une fois cette requête OID émise, le pilote miniport peut indiquer les paquets sur cette file d’attente de réception.

Note Si le pilote miniport indique des paquets sur une file d’attente pendant le traitement d’une requête OID de OID_RECEIVE_FILTER_SET_FILTER, il doit terminer la requête OID et retourner un code NDIS_STATUS_SUCCESS status.

Retourner les codes status

Le pilote miniport retourne l’un des codes status suivants pour la demande de méthode OID de OID_RECEIVE_FILTER_SET_FILTER :

NDIS_STATUS_SUCCESS
Le filtre a été défini sur la file d’attente avec succès. La mémoire tampon d’informations contient la structure NDIS_RECEIVE_FILTER_PARAMETERS mise à jour.

NDIS_STATUS_PENDING
La demande est en attente d’achèvement. Le dernier status code et les résultats seront passés au gestionnaire de saisie semi-automatique de la requête OID de l’appelant.

NDIS_STATUS_INVALID_PARAMETER
Un ou plusieurs des paramètres fournis par le pilote de sur-position n’étaient pas valides.

NDIS_STATUS_INVALID_LENGTH
La mémoire tampon d’informations était trop courte. NDIS définit les DONNÉES. METHOD_INFORMATION. BytesNeeded membre dans la structure NDIS_OID_REQUEST à la taille de mémoire tampon minimale requise.

NDIS_STATUS_NOT_SUPPORTED
La version NDIS du pilote miniport est une version antérieure à 6.20.

NDIS_STATUS_FAILURE
La demande a échoué pour d’autres raisons.