EVT_SERCX2_APPLY_CONFIG コールバック関数 (sercx.h)

  • [アーティクル]

EvtSerCx2ApplyConfig イベント コールバック関数は、シリアル フレームワーク拡張機能 (SerCx2) のバージョン 2 によって呼び出され、シリアル コントローラー のハードウェアに適用するデバイス固有の構成設定の一覧をシリアル コントローラー ドライバーに提供します。

構文

EVT_SERCX2_APPLY_CONFIG EvtSercx2ApplyConfig;

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

パラメーター

[in] Device

シリアル コントローラーを表すフレームワーク デバイス オブジェクトへの WDFDEVICE ハンドル。 シリアル コントローラー ドライバーは、EvtDriverDeviceAdd コールバック関数でこのオブジェクトを作成しました。 詳細については、「SerCx2InitializeDevice」を参照してください。

[in] ConnectionParameters

接続パラメーター構造体へのポインター。 この関数では、ポインターを適切なポインター型にキャストし、データ構造を解析して構成設定を取得し、これらの設定をシリアル コントローラー ハードウェアに適用する必要があります。 接続パラメーターの構造は、ハードウェア プラットフォーム ベンダーによって定義され、SerCx2 とオペレーティング システムの両方に対して不透明です。 詳細については、「解説」を参照してください。

戻り値

EvtSerCx2ApplyConfig 関数は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合は、適切なエラー状態コードが返されます。

備考

シリアル コントローラー ドライバーでは、この関数を実装する必要があります。 ドライバーは、シリアル コント ローラーのフレームワーク デバイス オブジェクトの初期化を完了する SerCx2InitializeDevice メソッドの呼び出しで関数を登録します。

SerCx2 は、シリアル コントローラーの初期化中に EvtSerCx2ApplyConfig 関数を呼び出して、ハードウェアが有効な初期状態であることを確認します。 さらに、この関数は、クライアントがシリアル コントローラーに IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 要求を送信するたびに呼び出されます。

SerCx2 は、シリアル コントローラー デバイスの ACPI リソース記述子のベンダー定義データ フィールドから構成パラメーターを取得します。 ACPI ファームウェアがこれらの構成設定を格納するために使用するデータ形式は、シリアル コントローラー ドライバーで想定されているのと同じデータ形式にする必要があります。 詳細については、ACPI 5.0 仕様の UART シリアル バス接続記述子 の説明を参照してください。

クライアントが SerCx2 によって管理されているシリアル ポートに IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 要求を送信すると、SerCx2 は EvtSerCx2ApplyConfig 関数を呼び出して、構成パラメーターをシリアル コントローラー ドライバーに渡します。 このコールバックが戻った後、SerCx2 は要求を完了し、コールバックからの戻り値を要求の状態コードとして使用します。

例

EvtSerCx2ApplyConfig コールバック関数 を定義するには、まず、定義するコールバック関数の型を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、ドライバーのコード分析、静的ドライバー検証ツール (SDV)、およびその他の検証ツールを すると、エラーが検出され、Windows オペレーティング システムのドライバーを記述するための要件になります。

たとえば、MyApplyConfigという名前の EvtSerCx2ApplyConfig コールバック関数を定義するには、次のコード例に示すように、EVT_SERCX2_APPLY_CONFIG 関数型を使用します。

EVT_SERCX2_APPLY_CONFIG  MyApplyConfig;

次に、次のようにコールバック関数を実装します。

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

EVT_SERCX2_APPLY_CONFIG 関数の種類は、Sercx.h ヘッダー ファイルで定義されています。 コード分析ツールの実行時にエラーをより正確に識別するには、Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations 注釈により、ヘッダー ファイル内の EVT_SERCX2_APPLY_CONFIG 関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「KMDF ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。 Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。

次のコード例は、UART の EvtSerCx2ApplyConfig 関数の部分的な実装を示しています。

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

前のコード例の pshpack1.h ヘッダー ファイルと poppack.h ヘッダー ファイルは、コンパイラによって使用される構造体配置モードを制御します。 PRH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFERおよびPPNP_SERIAL_BUS_DESCRIPTORポインター型は、RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER および PNP_SERIAL_BUS_DESCRIPTOR 構造体へのポインターです。 PNP_UART_SERIAL_BUS_DESCRIPTOR 構造体のメンバーの詳細については、ACPI 5.0 仕様の表 6-193 を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows 8.1以降で使用できます。
ターゲット プラットフォーム の デスクトップ
ヘッダー sercx.h
IRQL PASSIVE_LEVELで呼び出されます。

関連項目

IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION

PNP_SERIAL_BUS_DESCRIPTOR

RH_QUERY_CONNECTION_PROPERTIES_OUTPUT_BUFFER

SerCx2InitializeDevice の