hc.h

Go to the documentation of this file.

/*
 * PROJECT:     ReactOS xHCI Host Controller Driver
 * LICENSE:     MIT (https://spdx.org/licenses/MIT)
 * PURPOSE:     Controller object, errata, recovery and the UCX controller callbacks
 * COPYRIGHT:   Copyright 2026 Justin Miller <justin.miller@reactos.org>
 */
 
#pragma once
 
enum class XhciRecovery : ULONG
{
    Ignore,
    ResetHost,
    Disable,
    Gone,
    HoldStopped,
    InternalReset
};
 
#define XHCI_FIRMWARE_UNKNOWN           0xFFFFFFFFFFFFFFFFULL
 
struct XhciIdentity
{
    UCX_CONTROLLER_PARENT_BUS_TYPE ParentBus;
    ULONG PciVendorId;
    ULONG PciDeviceId;
    UCHAR PciRevisionId;
    USHORT PciSubsystemVendorId;
    USHORT PciSubsystemId;
    ULONG PciBus;
    ULONG PciDevice;
    ULONG PciFunction;
    CHAR AcpiVendorId[MAX_VENDOR_ID_STRING_LENGTH];
    CHAR AcpiDeviceId[MAX_DEVICE_ID_STRING_LENGTH];
    CHAR AcpiRevisionId[MAX_REVISION_ID_STRING_LENGTH];
 
    ULONG64 FirmwareVersion;
 
    BUS_INTERFACE_STANDARD PciInterface;
};
 
class XhciController
{
public:
    static XhciController*
    FromDevice(
        _In_ WDFDEVICE Device);
    static XhciController*
    FromUcx(
        _In_ UCXCONTROLLER UcxController);
 
    BOOLEAN
    HasErrata(
        _In_ XhciErrata Bit) const
    {
        ULONG Position = static_cast<ULONG>(Bit);
 
        if (Position >= 64)
            return (m_ErrataWord2 & (1ULL << (Position - 64))) != 0;
 
        return (m_Errata & XhciErrataBit(Bit)) != 0;
    }
 
    VOID
    SetErrata(
        _In_ XhciErrata Bit);
 
    BOOLEAN IsAccessible() const;
    VOID MarkGone();
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID
    RaiseControllerFault(
        _In_ XhciRecovery Action,
        _In_ ULONG Reason);
 
    WDFDEVICE m_Device;
    PDEVICE_OBJECT m_WdmDevice;
    UCXCONTROLLER m_Ucx;
    ULONG64 m_Errata;
    ULONG64 m_ErrataWord2;
 
    XhciRegisters m_Registers;
    XhciCommonBuffer m_Buffers;
    XhciSlotTable m_Slots;
    XhciInterrupters m_Interrupters;
    XhciCommandRing m_Commands;
    XhciRootHub m_RootHub;
 
 
    XhciIdentity m_Identity;
 
    _Enum_is_bitflag_ enum : ULONG64
    {
        FixFrescoShadow = 0x01,
        FixFrescoControl = 0x02,
        FixEtronSet = 0x04,
        FixEtronClear = 0x08,
        FixAsmediaResetDelay = 0x10
    };
    ULONG64 m_InternalFlags;
 
    BOOLEAN m_ReservedIoArmed;
 
    WDF_POWER_DEVICE_STATE m_PowerState;
 
    enum class SystemAction : ULONG
    {
        Boot = 0,
        ResumeFromSleep = 1,
        ResumeFromHibernate = 2,
        Sleep = 3,
        HybridSleep = 4,
        Hibernate = 5,
        Shutdown = 6,
        None = 7
    };
    SystemAction m_SystemAction;
 
    XhciDmaBuffer* m_SplitPadBuffer;
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    ULONG
    GetFrameNumber(
        _In_ ULONG Increment);
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID
    VerifierCheck(
        _In_ ULONG Flag);
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID OnRootHubD0Entry();
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID
    NotifyPortConnectState(
        _In_ BOOLEAN AnyConnected);
 
    /* Event handlers; the KMDF and UCX callbacks in hc.cpp forward here */
    NTSTATUS
    Initialize(
        _In_ WDFDEVICE Device,
        _In_ UCXCONTROLLER Ucx,
        _In_ const XhciIdentity* Identity);
    NTSTATUS
    PrepareHardware(
        _In_ WDFCMRESLIST Raw,
        _In_ WDFCMRESLIST Translated);
    VOID ReleaseHardware();
    NTSTATUS
    D0Entry(
        _In_ WDF_POWER_DEVICE_STATE PreviousState);
    NTSTATUS
    D0EntryPostInterruptsEnabled(
        _In_ WDF_POWER_DEVICE_STATE PreviousState);
    VOID D0ExitPreInterruptsDisabled();
    VOID
    D0Exit(
        _In_ WDF_POWER_DEVICE_STATE TargetState);
    VOID SelfManagedIoInit();
    VOID SelfManagedIoCleanup();
    VOID
    UsageNotification(
        _In_ WDF_SPECIAL_FILE_TYPE Type,
        _In_ BOOLEAN InPath);
    VOID
    SetPortWake(
        _In_ BOOLEAN Arm);
    VOID
    TrackSystemPowerIrp(
        _In_ PIO_STACK_LOCATION Stack);
    VOID WatchdogTick();
    VOID RecoveryWorker();
    VOID IdleTimeoutWorker();
    VOID UcxReset();
    NTSTATUS
    QueryUsbCapability(
        _In_ const GUID* Capability,
        _In_ ULONG OutputBufferLength,
        _Out_writes_bytes_opt_(OutputBufferLength) PVOID OutputBuffer,
        _Out_ PULONG ResultLength);
    VOID FdoCleanup();
 
    BOOLEAN m_WaitWakeQueued;
    BOOLEAN m_TestMode;
 
private:
    enum class IdleStatus : ULONG
    {
        NotConfigured,
        NoS0Wake,
        Configured
    };
 
    NTSTATUS CreateWdfObjects();
    VOID PopulateErrata();
    VOID
    QueryErrataDatabase(
        _In_ BOOLEAN AtAddDevice);
    VOID ReadRegistryErrata();
    VOID SetInternalFlags();
    VOID ReadVerifierFlags();
    VOID ConfigureS0Idle();
    VOID
    SetIdleTimeout(
        _In_ ULONG Milliseconds);
    VOID
    EvaluateDsm(
        _In_ ULONG Function);
    VOID EvaluatePrmi();
    VOID UpdateRegistryCounters();
    VOID RunFirmwareCommands();
 
    NTSTATUS StartController();
    NTSTATUS
    RunD0Pass(
        _In_ BOOLEAN Restore);
    VOID InitFrameSnapshot();
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID
    QueueRecovery(
        _In_ ULONG Actions,
        _In_ ULONG Reason);
    VOID
    BootRecovery(
        _In_ ULONG Actions);
    VOID
    RunRecovery(
        _In_ ULONG Actions);
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID
    SetGone(
        _In_ BOOLEAN ReportToPnp);
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID DisableController();
    VOID InternalReset();
 
    ULONG64
    NowMs() const;
 
    ULONG m_VerifierFlags;
    BOOLEAN m_Gone;
    BOOLEAN m_SaveFailed;
    BOOLEAN m_FrameSnapshotReady;
    LONG64 m_FrameSnapshot;
    ULONG m_TimeIncrement;
    ULONG m_SpecialFiles;
    ULONG m_RestoreFailures;
    ULONG m_RecoveryCount;
    LONG m_ResetCount;
    LONG m_ResetInterval;
    LONG m_ResetLock;
    IdleStatus m_IdleStatus;
    ULONG m_LastIdleTimeout;
 
    WDFTIMER m_Watchdog;
    WDFWORKITEM m_RecoveryItem;
    WDFWORKITEM m_IdleItem;
 
    /* Recovery state */
    KSPIN_LOCK m_RecoveryLock;
    ULONG m_RecoveryActions;
    KMUTEX m_RecoveryMutex;
    BOOLEAN m_GoneHandled;
    BOOLEAN m_PnpToldRemoved;
};
 
struct XhciDriverData
{
    PDRIVER_OBJECT DriverObject;
    PVOID QueryDeviceFlags;
    BOOLEAN TestMode;
};
 
extern XhciDriverData XhciDriver;