EVT_SERCX_APPLY_CONFIG fonction de rappel (sercx.h)

Article
12/15/2024

La fonction de rappel d’événement EvtSerCxApplyConfig indique au pilote du 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

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 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 de framework série (SerCx) et le système d’exploitation.

Valeur de retour

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

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 ressource 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 format de données que celui attendu par le pilote du 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 du contrôleur série pour le port série prend en charge le EvtSerCxApplyConfig rappel, et si le descripteur de ressource 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 demande avec le code d’état d’erreur 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 d’état pour la requête.

Si un pilote de contrôleur série doit obtenir les paramètres de connexion par défaut à la fois autres que pendant un EvtSerCxApplyConfig rappel, 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 de 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 qui Static Driver Verificationr (SDV) et d’autres outils de vérification nécessitent, 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 pointeur 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.