EVT_SERCX2_APPLY_CONFIG fonction de rappel (sercx.h)

Article
10/30/2024

La fonction de rappel d’événement EvtSerCx2ApplyConfig est appelée par la version 2 de l’extension de l’infrastructure série (SerCx2) pour fournir le pilote du contrôleur série avec une liste de paramètres de configuration spécifiques à l’appareil à 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

Handle WDFDEVICE pour l’objet d’appareil framework qui représente le contrôleur série. Le pilote de 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 caster 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 Remarques.

Valeur de retour

La fonction EvtSerCx2ApplyConfig retourne STATUS_SUCCESS si l’appel réussit. Sinon, elle retourne un code d’état d’erreur approprié.

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 d’appareil framework 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 du champ de données défini par le fournisseur dans le descripteur de ressource ACPI pour l’appareil du 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 format de données que celui attendu par le pilote du 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 demande de 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 du contrôleur série. Une fois que ce rappel est retourné, SerCx2 termine la requête et utilise la valeur de retour du rappel comme code d’état pour la requête.

Exemples

Pour définir une EvtSerCx2ApplyConfig fonction de rappel, 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 fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 illustré 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 lorsque vous exécutez les 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 annoter le comportement de la fonction.

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 structure utilisé par le compilateur. Les types de pointeur 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 dans la spécification ACPI 5.0.