EVT_SERCX2_APPLY_CONFIG fonction de rappel (sercx.h)

Article
08/07/2023

La fonction de rappel d’événement EvtSerCx2ApplyConfig est appelée par la version 2 de l’extension d’infrastructure série (SerCx2) pour fournir au pilote du contrôleur série une liste de paramètres de configuration spécifiques au périphérique à appliquer au matériel du contrôleur série.

Syntaxe

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

NTSTATUS EvtSercx2ApplyConfig(
  [in] WDFDEVICE Device,
  [in] PVOID ConnectionParameters
)
{...}

Paramètres

[in] Device

Un handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote du contrôleur série a créé cet objet dans sa fonction de rappel EvtDriverDeviceAdd . Pour plus d’informations, consultez SerCx2InitializeDevice.

[in] ConnectionParameters

Pointeur vers la structure des paramètres de connexion. Cette fonction doit convertir le pointeur vers le type de pointeur approprié, analyser la structure de données pour obtenir les paramètres de configuration et appliquer ces paramètres au matériel du contrôleur série. La structure des paramètres de connexion est définie par le fournisseur de la plateforme matérielle et est opaque à la fois pour SerCx2 et le système d’exploitation. Pour plus d'informations, consultez la section Notes.

Valeur retournée

La fonction EvtSerCx2ApplyConfig retourne STATUS_SUCCESS si l’appel réussit. Sinon, elle retourne une erreur appropriée status code.

Remarques

Votre pilote de contrôleur série doit implémenter cette fonction. Le pilote inscrit la fonction dans l’appel à la méthode SerCx2InitializeDevice qui termine l’initialisation de l’objet de périphérique d’infrastructure pour le contrôleur série.

SerCx2 appelle la fonction EvtSerCx2ApplyConfig pendant l’initialisation du contrôleur série pour s’assurer que le matériel est dans un état initial valide. En outre, cette fonction est appelée chaque fois qu’un client envoie une demande de IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION au contrôleur série.

SerCx2 obtient les paramètres de configuration à partir du champ de données défini par le fournisseur dans le descripteur de ressources ACPI pour l’appareil de contrôleur série. Le format de données utilisé par le microprogramme ACPI pour stocker ces paramètres de configuration doit être le même que celui attendu par le pilote de contrôleur série. Pour plus d’informations, consultez la description du descripteur de connexion de bus série UART dans la spécification ACPI 5.0.

Lorsqu’un client envoie une requête IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION à un port série géré par SerCx2, SerCx2 appelle la fonction EvtSerCx2ApplyConfig pour passer les paramètres de configuration au pilote de contrôleur série. Une fois ce rappel retourné, SerCx2 termine la requête et utilise la valeur de retour du rappel comme code status pour la requête.

Exemples

Pour définir une fonction de rappel EvtSerCx2ApplyConfig , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction de rappel EvtSerCx2ApplyConfig nommée MyApplyConfig, utilisez le type de fonction EVT_SERCX2_APPLY_CONFIG , comme indiqué dans cet exemple de code :

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

Ensuite, implémentez votre fonction de rappel comme suit :

_Use_decl_annotations_
NTSTATUS
  MyApplyConfig(
    WDFDEVICE  Device,
    PVOID  ConnectionParameters
    )
  {...}

Le type de fonction EVT_SERCX2_APPLY_CONFIG est défini dans le fichier d’en-tête Sercx.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction EVT_SERCX2_APPLY_CONFIG dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

L’exemple de code suivant montre une implémentation partielle d’une fonction EvtSerCx2ApplyConfig pour un UART :

//
// Define the UART ACPI descriptor, plus any vendor-specific
// data that is needed by the serial controller (UART) driver.
//

#define ANYSIZE_ARRAY 1
#include <pshpack1.h>

//
// Common resource name descriptor
//
typedef struct _PNP_IO_DESCRIPTOR_RESOURCE_NAME {
    UCHAR ResourceIndex;
    UCHAR ResourceName[ANYSIZE_ARRAY];
} PNP_IO_DESCRIPTOR_RESOURCE_NAME, *PPNP_IO_DESCRIPTOR_RESOURCE_NAME;

//
// Bus descriptor for a UART
//
typedef struct _PNP_UART_SERIAL_BUS_DESCRIPTOR {
    PNP_SERIAL_BUS_DESCRIPTOR SerialBusDescriptor;
    ULONG BaudRate;
    USHORT RxBufferSize;
    USHORT TxBufferSize;
    UCHAR Parity;
    // Include any optional vendor data here:
    ...
    // Append the PNP_IO_DESCRIPTOR_RESOURCE_NAME here:
    ....
} PNP_UART_SERIAL_BUS_DESCRIPTOR, *PPNP_UART_SERIAL_BUS_DESCRIPTOR;

#include <poppack.h>

EVT_SERCX_APPLY_CONFIG MyApplyConfig;

//
// Implementation of an EvtSerCx2ApplyConfig callback function
//
_Use_decl_annotations_
VOID
  MyApplyConfig(
    WDFDEVICE Device,
    PVOID ConnectionParameters
    )
{
    NTSTATUS status = STATUS_SUCCESS; 
    PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER connection;
    PPNP_SERIAL_BUS_DESCRIPTOR descriptor;
    PPNP_UART_SERIAL_BUS_DESCRIPTOR uartDescriptor;

    if (ConnectionParameters == NULL)
    {
        status = STATUS_INVALID_PARAMETER; 
    }

    if (NT_SUCCESS(status))
    {
        connection = (PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER)ConnectionParameters;

        if (connection->PropertiesLength < sizeof(PNP_SERIAL_BUS_DESCRIPTOR))
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        descriptor = (PPNP_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties;

        if (descriptor->SerialBusType != UART_SERIAL_BUS_TYPE)
        {
            status = STATUS_INVALID_PARAMETER;
        }
    }

    if (NT_SUCCESS(status))
    {
        uartDescriptor = (PPNP_UART_SERIAL_BUS_DESCRIPTOR)connection->ConnectionProperties; 

        // Apply the platform-specific configuration settings
        // from the UART descriptor here:
        ...
    }

    return status;
}

Les fichiers d’en-tête pshpack1.h et poppack.h dans l’exemple de code précédent contrôlent le mode d’alignement de la structure utilisé par le compilateur. Les types de pointeurs PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER et PPNP_SERIAL_BUS_DESCRIPTOR sont des pointeurs vers des structures RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER et PNP_SERIAL_BUS_DESCRIPTOR . Pour plus d’informations sur les membres de la structure PNP_UART_SERIAL_BUS_DESCRIPTOR , consultez le tableau 6-193 de la spécification ACPI 5.0.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 8.1.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	sercx.h
IRQL	Appelé à PASSIVE_LEVEL.