UsbHcd::TransferCompletion Class Reference

#include <TransferCompletion.h>

Collaboration diagram for UsbHcd::TransferCompletion:

Classes
struct	Claim

Public Types
enum class	State : size_t { Idle , Active , Captured , PublicationClaimed }
enum class	Reason { Natural , Cancelled , Teardown }
enum class	CancellationDisposition { NoMatch , Claimed , DrainPublished }
using	Callback = void(*)(uintptr_t, ssize_t)

Public Member Functions
void	arm (Callback callback, uintptr_t parameter, size_t generation)
MUST_USE_RESULT bool	captureNatural (ssize_t result)
MUST_USE_RESULT bool	claimCaptured (Claim &claim)
MUST_USE_RESULT CancellationDisposition	claimCancellation (Callback callback, uintptr_t parameter, ssize_t cancellationResult, Claim &claim)
MUST_USE_RESULT bool	claimForTeardown (ssize_t cancellationResult, Claim &claim)
State	state () const
size_t	generation () const

Private Member Functions
bool	matches (Callback callback, uintptr_t parameter) const
bool	transition (State from, State to)
void	fillClaim (Claim &claim, Reason reason, ssize_t result) const
	TransferCompletion (const TransferCompletion &)=delete
TransferCompletion &	operator= (const TransferCompletion &)=delete

Private Attributes
Atomic< size_t >	m_State
Callback	m_Callback
uintptr_t	m_Parameter
size_t	m_Generation
ssize_t	m_Result

Detailed Description

Owns the exactly-once callback obligation for one accepted transfer.

Every transition and callback publication must occur under the HCD's completion lock. Capturing a hardware result does not itself transfer callback ownership: normal reclamation, cancellation, and teardown still race for the one publication claim. The winner must establish that DMA has stopped and publish its callback record before releasing that lock.

Definition at line 26 of file TransferCompletion.h.

Member Typedef Documentation

Callback

using UsbHcd::TransferCompletion::Callback = void (*)(uintptr_t, ssize_t)

Definition at line 28 of file TransferCompletion.h.

Member Enumeration Documentation

CancellationDisposition

enum class UsbHcd::TransferCompletion::CancellationDisposition

strong

Definition at line 43 of file TransferCompletion.h.

Reason

enum class UsbHcd::TransferCompletion::Reason

strong

Definition at line 37 of file TransferCompletion.h.

State

enum class UsbHcd::TransferCompletion::State : size_t

strong

Definition at line 30 of file TransferCompletion.h.

Constructor & Destructor Documentation

TransferCompletion()

UsbHcd::TransferCompletion::TransferCompletion ( )

inline

Definition at line 59 of file TransferCompletion.h.

Member Function Documentation

arm()

void UsbHcd::TransferCompletion::arm ( Callback  callback, uintptr_t  parameter, size_t  generation  )

inline

Arms the obligation as the final step before hardware publication.

Definition at line 67 of file TransferCompletion.h.

Referenced by Ehci::doAsync(), and Ohci::doAsync().

Here is the caller graph for this function:

captureNatural()

MUST_USE_RESULT bool UsbHcd::TransferCompletion::captureNatural ( ssize_t  result )

inline

Captures a hardware result without yet owning callback publication.

Definition at line 77 of file TransferCompletion.h.

Referenced by Ehci::irq(), Ohci::irq(), and Uhci::irq().

Here is the caller graph for this function:

claimCancellation()

MUST_USE_RESULT CancellationDisposition UsbHcd::TransferCompletion::claimCancellation ( Callback  callback, uintptr_t  parameter, ssize_t  cancellationResult, Claim &  claim  )

inline

Claims cancellation or identifies the exact record already published.

Cancellation preserves a hardware result which won first. A PublicationClaimed result is safe to drain because the caller must hold the same completion lock used by the publisher.

Definition at line 98 of file TransferCompletion.h.

References claimCaptured().

Referenced by Ehci::cancelAsyncAndDrain(), Ohci::cancelAsyncAndDrain(), and Uhci::cancelAsyncAndDrain().

Here is the caller graph for this function:

claimCaptured()

MUST_USE_RESULT bool UsbHcd::TransferCompletion::claimCaptured ( Claim &  claim )

inline

Transfers a captured result to the ordinary reclamation path.

Definition at line 83 of file TransferCompletion.h.

Referenced by claimCancellation(), claimForTeardown(), Ohci::irq(), and Uhci::irq().

Here is the caller graph for this function:

claimForTeardown()

MUST_USE_RESULT bool UsbHcd::TransferCompletion::claimForTeardown ( ssize_t  cancellationResult, Claim &  claim  )

inline

Claims an accepted transfer after the controller is quiescent.

An active transfer is failed because hardware produced no result. A captured transfer retains its hardware result. A claimed transfer already has a publisher and is never duplicated.

Definition at line 133 of file TransferCompletion.h.

References claimCaptured().

Referenced by Ohci::terminalizeEDForTeardown().

Here is the caller graph for this function:

fillClaim()

void UsbHcd::TransferCompletion::fillClaim ( Claim &  claim, Reason  reason, ssize_t  result  ) const

inlineprivate

Definition at line 166 of file TransferCompletion.h.

generation()

size_t UsbHcd::TransferCompletion::generation ( ) const

inline

Definition at line 153 of file TransferCompletion.h.

matches()

bool UsbHcd::TransferCompletion::matches ( Callback  callback, uintptr_t  parameter  ) const

inlineprivate

Definition at line 158 of file TransferCompletion.h.

state()

State UsbHcd::TransferCompletion::state ( ) const

inline

Definition at line 149 of file TransferCompletion.h.

transition()

bool UsbHcd::TransferCompletion::transition ( State  from, State  to  )

inlineprivate

Definition at line 162 of file TransferCompletion.h.

Member Data Documentation

m_Callback

Callback UsbHcd::TransferCompletion::m_Callback

private

Definition at line 175 of file TransferCompletion.h.

m_Generation

size_t UsbHcd::TransferCompletion::m_Generation

private

Definition at line 177 of file TransferCompletion.h.

m_Parameter

uintptr_t UsbHcd::TransferCompletion::m_Parameter

private

Definition at line 176 of file TransferCompletion.h.

m_Result

ssize_t UsbHcd::TransferCompletion::m_Result

private

Definition at line 178 of file TransferCompletion.h.

m_State

Atomic<size_t> UsbHcd::TransferCompletion::m_State

private

Definition at line 174 of file TransferCompletion.h.

---

The documentation for this class was generated from the following file:

• TransferCompletion.h