xferring.h

Go to the documentation of this file.

/*
 * PROJECT:     ReactOS xHCI Host Controller Driver
 * LICENSE:     MIT (https://spdx.org/licenses/MIT)
 * PURPOSE:     Transfer ring object shared by the control, bulk and isoch transfer types
 * COPYRIGHT:   Copyright 2026 Justin Miller <justin.miller@reactos.org>
 */
 
#pragma once
 
class XhciController;
class XhciUsbDevice;
class XhciEndpoint;
 
#define XHCI_URB_NO_PROCESSOR   MAXULONG
 
enum class XhciMapState : LONG
{
    Halted = 0,
    Halting = 1,
    PausedFill = 2,
    Filling = 3,
    AwaitingStarve = 4       
};
 
class XhciTransferRing
{
public:
    static NTSTATUS
    Create(
        _In_ XhciEndpoint* Endpoint,
        _In_ WDFOBJECT Parent,
        _In_ ULONG StreamId,
        _Out_ XhciTransferRing** Ring);
 
    static XhciTransferRing*
    FromQueue(
        _In_ WDFQUEUE Queue);
 
    WDFQUEUE Queue() const;
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    NTSTATUS Enable();
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID
    Disable(
        _In_ BOOLEAN FreeResources);
 
    _IRQL_requires_(PASSIVE_LEVEL)
    NTSTATUS
    EnableForwardProgress(
        _In_ ULONG MaxTransferSize);
 
    VOID InitializeRing();
 
    ULONG64 SegmentBase() const;
    ULONG64 EnqueuePointer() const;
 
    ULONG64 DequeuePointerValue() const;
 
    /* Endpoint machine actions fanned out by the endpoint */
    VOID ResumeRingFill();
    VOID SuspendRingFill();
    VOID OnPipeHalted();
    VOID OnClientPipeReset();
    VOID StoppedEventReceived();
    VOID AllowReclaimOnCancel();
    VOID ConsumePendingEvents();
    VOID RecoverTransfers();
    BOOLEAN DoorbellRungSinceFill() const;
    BOOLEAN HasQueuedWork() const;
 
    BOOLEAN
    OnTransferEvent(
        _In_ const XHCI_TRB* Event);
 
    static BOOLEAN
    OnUntargetedTransferEvent(
        _In_ XhciController* Controller,
        _In_ const XHCI_TRB* Event);
 
    BOOLEAN
    IsLikelyDuplicate(
        _In_ const XHCI_TRB* Event) const;
 
    /* Helpers for the control and bulk type modules */
 
    NTSTATUS
    EnsureFreeSegments(
        _In_ ULONG Count,
        _In_ BOOLEAN Async);
 
    NTSTATUS
    TakeSegments(
        _In_ ULONG Count,
        _Inout_ PLIST_ENTRY List);
 
    VOID
    ReturnSegments(
        _Inout_ PLIST_ENTRY List,
        _In_ BOOLEAN ToHead);
 
    XhciDmaBuffer* BorrowBounceBuffer();
    VOID
    ReturnBounceBuffer(
        _In_ XhciDmaBuffer* Buffer);
 
    XhciMapState
    ChangeMapState(
        _In_ BOOLEAN FromAny,
        _In_ XhciMapState From,
        _In_ XhciMapState To);
 
    VOID
    BuildLinkTrb(
        _Out_ PXHCI_TRB Trb,
        _In_ BOOLEAN FirstOfTd,
        _In_ BOOLEAN InDataStage) const;
 
    ULONG
    PacketCount(
        _In_ ULONG Bytes) const;
 
    ULONG
    TdSize(
        _In_ ULONG PacketCount,
        _In_ ULONG BytesMappedSoFar,
        _In_ BOOLEAN LastTrbOfTd) const;
 
    VOID UpdateInterrupterTarget();
 
    VOID
    UpdateInterrupterTarget(
        _In_ ULONG ProcessorIndex);
 
    static ULONG
    UrbProcessorIndex(
        _In_ PURB Urb);
 
    VOID RingDoorbell();
 
    static USBD_STATUS
    UsbdStatusFromCompletionCode(
        _In_ ULONG CompletionCode);
    static NTSTATUS
    NtStatusFromUsbdStatus(
        _In_ USBD_STATUS UsbdStatus);
 
    /* Common ring state; the type modules read and write it under the rules of each field */
    XhciController* m_Controller;
    XhciUsbDevice* m_Device;
    XhciEndpoint* m_Endpoint;
    ULONG m_StreamId;
    ULONG m_TransferType;           
    WDFQUEUE m_Queue;
    WDFDPC m_CompletionDpc;
    KSPIN_LOCK m_Lock;              
    volatile LONG m_MapState;       
    ULONG m_InterrupterTarget;
    BOOLEAN m_DoorbellRung;         
    PMDL m_ReservedMdl;
 
    ULONG m_SegmentSize;
    ULONG m_DoubleBufferSize;
    ULONG m_MaxStageSize;
    ULONG m_MapRegisterCount;
 
    XhciDmaBuffer* m_Segment;       
    PXHCI_TRB m_Trbs;
    ULONG m_EnqueueIndex;
    ULONG m_LastIndex;              
    ULONG m_Cycle;                  
    LIST_ENTRY m_FreeSegments;
    LIST_ENTRY m_DoubleBuffers;
 
    union
    {
        XhciControlRing Control;
        XhciBulkRing Bulk;
        XhciIsochRing Isoch;
    } m_Type;
 
    /* Implementation state of the common ring; the type modules do not touch these */
    VOID Cleanup();
    _IRQL_requires_(PASSIVE_LEVEL)
    VOID GrowSegments();
 
    BOOLEAN IsControl() const;
    BOOLEAN IsBulkOrInterrupt() const;
    BOOLEAN IsIsoch() const;
 
    _IRQL_requires_max_(DISPATCH_LEVEL)
    VOID WaitForMappingIdle();
 
    VOID MakeLive();
    VOID RetireLive();
 
    static XhciTransferRing*
    ReferenceLiveRing(
        _In_ XhciController* Controller,
        _In_ const XhciUsbDevice* Device,
        _In_ ULONG Dci);
    VOID DereferenceLive();
 
    LIST_ENTRY m_LiveLink;
    volatile LONG m_EventUsers;
    BOOLEAN m_Live;
    BOOLEAN m_TypeReady;
    BOOLEAN m_GrowthQueued;
    BOOLEAN m_ForwardProgressQueue;
    ULONG m_GrowthWanted;
    WDFWORKITEM m_GrowthItem;
};