EVT_SERCX_APPLY_CONFIG fonction de rappel (sercx.h)

Article
02/26/2024

La fonction de rappel d’événement EvtSerCxApplyConfig indique au pilote de contrôleur série d’appliquer une liste de paramètres de configuration au matériel du contrôleur série.

Syntaxe

EVT_SERCX_APPLY_CONFIG EvtSercxApplyConfig;

NTSTATUS EvtSercxApplyConfig(
  [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.

[in] ConnectionParameters

Pointeur vers la structure des paramètres de connexion. Cette fonction doit convertir ce paramètre en 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 l’extension d’infrastructure série (SerCx) et le système d’exploitation.

Valeur retournée

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

Remarques

SerCx appelle cette fonction 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 contrôle d’E /S IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION au contrôleur.

SerCx obtient ces paramètres de configuration à partir du 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.

Lorsqu’un client envoie une demande de IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION à un port série géré par SerCx, SerCx détermine si le pilote de contrôleur série pour le port série prend en charge le rappel EvtSerCxApplyConfig et si le descripteur de ressources ACPI pour le port série fournit les paramètres de connexion par défaut. Si ce n’est pas le cas, SerCx termine la requête avec une erreur status code STATUS_NOT_SUPPORTED. Sinon, SerCx transmet les paramètres de connexion à la fonction de rappel EvtSerCxApplyConfig du pilote. Une fois ce rappel retourné, SerCx termine la requête et utilise la valeur de retour du rappel comme code status pour la demande.

Si un pilote de contrôleur série doit obtenir les paramètres de connexion par défaut à un moment autre que pendant un rappel EvtSerCxApplyConfig , le pilote peut appeler la méthode SerCxGetConnectionParameters .

Pour inscrire une fonction de rappel EvtSerCxApplyConfig , le pilote doit appeler la méthode SerCxInitialize .

Exemples

Le type de fonction pour ce rappel est déclaré dans Sercx.h, comme suit.

typedef NTSTATUS
  EVT_SERCX_APPLY_CONFIG(
    __in WDFDEVICE Device
    );

Pour définir une fonction de rappel EvtSerCxApplyConfig nommée MyEvtSerCxApplyConfig, vous devez d’abord fournir une déclaration de fonction requise par static driver verifier (SDV) et d’autres outils de vérification, comme suit.

EVT_SERCX_APPLY_CONFIG MyEvtSerCxApplyConfig;

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

NTSTATUS
  MyEvtSerCxApplyConfig(
    __in WDFDEVICE Device
    )
{ ... }

Pour plus d’informations sur les exigences SDV pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF.

L’exemple de code suivant montre une implémentation partielle d’une fonction EvtSerCxApplyConfig 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


//
// 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;

EVT_SERCX_APPLY_CONFIG UartEvtApplyConfig;

//
// Implementation of an EvtSerCxApplyConfig callback function
//
NTSTATUS
  UartEvtApplyConfig(
    __in WDFDEVICE Device,
    __in 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 configuration settings from
        // the UART descriptor.
        ...
    }

    return status;
}

Les types de pointeurs PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER et PPNP_SERIAL_BUS_DESCRIPTOR dans l’exemple de code précédent sont définis dans le fichier d’en-tête Reshub.h.

Configuration requise

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

Voir aussi

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

SerCxGetConnectionParameters

SerCxInitialize

Partager via