EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY funzione di callback (ucxcontroller.h)

Articolo
03/05/2024

Implementazione del driver client per determinare se il controller supporta una funzionalità specifica.

Sintassi

EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY EvtUcxControllerQueryUsbCapability;

NTSTATUS EvtUcxControllerQueryUsbCapability(
  [in]            UCXCONTROLLER UcxController,
  [in]            PGUID CapabilityType,
  [in]            ULONG OutputBufferLength,
  [out, optional] PVOID OutputBuffer,
  [out]           PULONG ResultLength
)
{...}

Parametri

[in] UcxController

Handle per il controller UCX ricevuto dal driver client in una chiamata precedente al metodo UcxControllerCreate .

[in] CapabilityType

Puntatore a un GUID che specifica la funzionalità richiesta. I possibili valori PGUID sono i seguenti:

GUID_USB_CAPABILITY_CHAINED_MDLS
GUID_USB_CAPABILITY_STATIC_STREAMS
GUID_USB_CAPABILITY_SELECTIVE_SUSPEND
GUID_USB_CAPABILITY_FUNCTION_SUSPEND
GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE
GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE
GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL
- Per i controller host tipici, la query deve avere esito negativo (STATUS_NOT_SUPPORTED). Se il controller ha esito positivo, richiede un buffer Clear TT quando si annullano trasferimenti asincroni a bassa velocità/velocità completa (bulk o controllo) inviati a un hub TT.

Per altre informazioni, vedere la sezione Osservazioni di USBD_QueryUsbCapability .

[in] OutputBufferLength

Lunghezza, in byte, del buffer di output della richiesta, se è disponibile un buffer di output.

[out, optional] OutputBuffer

Puntatore a una posizione che riceve l'indirizzo del buffer. Alcune funzionalità potrebbero dover fornire informazioni aggiuntive a UCX in questo buffer.

[out] ResultLength

Posizione che, in caso di restituzione, contiene le dimensioni, in byte, delle informazioni archiviate nella funzione di callback archiviata in OutputBuffer.

Valore restituito

Se l'operazione ha esito positivo, la funzione di callback deve restituire STATUS_SUCCESS o un altro valore di stato per cui NT_SUCCESS(status) è TRUE. In caso contrario, deve restituire un valore di stato per il quale NT_SUCCESS(status) è uguale a FALSE.

Codice restituito	Descrizione
STATUS_SUCCESS	La funzionalità USB richiesta è supportata.
STATUS_NOT_IMPLEMENTED	La funzionalità USB richiesta è sconosciuta e non supportata.
STATUS_NOT_SUPPORTED	Il controller non supporta la funzionalità USB richiesta. Per GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL, il controller non ha richiesto un buffer Clear TT durante l'annullamento dei trasferimenti asincroni a bassa velocità/velocità massima (bulk o controllo) inviati a un hub TT.

Commenti

Il driver client UCX registra l'implementazione EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY con l'estensione del controller host USB (UCX) chiamando il metodo UcxControllerCreate .

Esempio

NTSTATUS
Controller_EvtControllerQueryUsbCapability(
    UCXCONTROLLER   UcxController,
    PGUID           CapabilityType,
    ULONG           OutputBufferLength,
    PVOID           OutputBuffer,
    PULONG          ResultLength
)

{
    NTSTATUS status;

    UNREFERENCED_PARAMETER(UcxController);
    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(OutputBuffer);

    *ResultLength = 0;

    if (RtlCompareMemory(CapabilityType,
                         &GUID_USB_CAPABILITY_CHAINED_MDLS,
                         sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_CHAINED_MDLS supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_CHAINED_MDLS not supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_STATIC_STREAMS,
                              sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_STATIC_STREAMS supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_STATIC_STREAMS supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_FUNCTION_SUSPEND,
                              sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_FUNCTION_SUSPEND supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_FUNCTION_SUSPEND not supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_SELECTIVE_SUSPEND,
                              sizeof(GUID)) == sizeof(GUID)) {

        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_SELECTIVE_SUSPEND supported");
        status = STATUS_SUCCESS;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL,
                              sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL not supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else {
        DbgTrace(TL_INFO, Controller, "Unhandled USB capability");
        status = STATUS_NOT_IMPLEMENTED;
    }

    return status;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Windows
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	ucxcontroller.h (include Ucxclass.h)
IRQL	PASSIVE_LEVEL

Vedi anche

UcxControllerCreate

Condividi tramite