pw_clock_tree

Oveview

Clock tree management for embedded devices. Main docs: https://pigweed.dev/pw_clock_tree.

Classes
class	pw::clock_tree::Element
class	pw::clock_tree::ElementBlocking
class	pw::clock_tree::ElementNonBlockingMightFail
class	pw::clock_tree::ElementNonBlockingCannotFail
class	pw::clock_tree::ClockSource< ElementType >
class	pw::clock_tree::ClockSourceNoOp
class	pw::clock_tree::DependentElement< ElementType >
class	pw::clock_tree::ClockDivider
class	pw::clock_tree::ClockDividerElement< ElementType >
class	pw::clock_tree::OptionalElement

Typedefs
using	pw::clock_tree::ClockDividerBlocking = ClockDividerElement< ElementBlocking >
	Alias for a blocking clock divider tree element.
using	pw::clock_tree::ClockDividerNonBlockingCannotFail = ClockDividerElement< ElementNonBlockingCannotFail >
using	pw::clock_tree::ClockDividerNonBlockingMightFail = ClockDividerElement< ElementNonBlockingMightFail >

Functions
constexpr	pw::clock_tree::Element::Element (bool may_block)
uint32_t	pw::clock_tree::Element::ref_count () const
	Get reference count for this clock tree element.
bool	pw::clock_tree::Element::may_block () const
	Check whether acquiring or releasing the element may block.
	pw::clock_tree::Element::Element (const Element &)=delete
	pw::clock_tree::Element::Element (const Element &&)=delete
Element &	pw::clock_tree::Element::operator= (const Element &)=delete
Element &	pw::clock_tree::Element::operator= (const Element &&)=delete
Status	pw::clock_tree::Element::Acquire ()
Status	pw::clock_tree::Element::Release ()
Status	pw::clock_tree::Element::AcquireWith (Element &element_with)
virtual Status	pw::clock_tree::Element::DoAcquireLocked ()=0
virtual Status	pw::clock_tree::Element::DoReleaseLocked ()=0
uint32_t	pw::clock_tree::Element::IncRef ()
	Increment reference count and return incremented value.
uint32_t	pw::clock_tree::Element::DecRef ()
	Decrement reference count and return decremented value.
virtual Status	pw::clock_tree::Element::DoEnable ()=0
	Function called when the clock tree element needs to get enabled.
virtual Status	pw::clock_tree::Element::DoDisable ()
virtual Status	pw::clock_tree::Element::DoAcquire ()=0
	Handle Acquire(), deferring locking the child class.
virtual Status	pw::clock_tree::Element::DoRelease ()=0
	Handle Release(), deferring locking the child class.
sync::Mutex &	pw::clock_tree::ElementBlocking::lock ()
Status	pw::clock_tree::ElementBlocking::DoAcquire () final
	Handle Acquire(), deferring locking the child class.
Status	pw::clock_tree::ElementBlocking::DoRelease () final
	Handle Release(), deferring locking the child class.
sync::InterruptSpinLock &	pw::clock_tree::ElementNonBlockingMightFail::lock ()
Status	pw::clock_tree::ElementNonBlockingMightFail::DoAcquire () final
	Handle Acquire(), deferring locking the child class.
Status	pw::clock_tree::ElementNonBlockingMightFail::DoRelease () final
	Handle Release(), deferring locking the child class.
void	pw::clock_tree::ElementNonBlockingCannotFail::Acquire ()
	Acquire a reference to this clock tree element.
void	pw::clock_tree::ElementNonBlockingCannotFail::Release ()
	Release a reference to this clock tree element.
Status	pw::clock_tree::ClockSource< ElementType >::DoAcquireLocked () final
Status	pw::clock_tree::ClockSource< ElementType >::DoReleaseLocked () final
pw::Status	pw::clock_tree::ClockSourceNoOp::DoEnable () final
	Function called when the clock tree element needs to get enabled.
pw::Status	pw::clock_tree::ClockSourceNoOp::DoDisable () final
constexpr	pw::clock_tree::DependentElement< ElementType >::DependentElement (ElementType &source)
	Create a dependent clock tree element that depends on source.
Status	pw::clock_tree::DependentElement< ElementType >::DoAcquireLocked () final
Status	pw::clock_tree::DependentElement< ElementType >::DoReleaseLocked () final
constexpr	pw::clock_tree::ClockDivider::ClockDivider (Element &element)
Status	pw::clock_tree::ClockDivider::SetDivider (uint32_t divider)
Status	pw::clock_tree::ClockDivider::Set (uint32_t divider)
Element &	pw::clock_tree::ClockDivider::element () const
	Return the element implementing this interface.
constexpr	pw::clock_tree::ClockDividerElement< ElementType >::ClockDividerElement (ElementType &source, uint32_t divider)
template<typename T = ElementType>
std::enable_if_t< T::kMayFail, pw::Status >	pw::clock_tree::ClockDividerElement< ElementType >::SetDivider (uint32_t divider)
uint32_t	pw::clock_tree::ClockDividerElement< ElementType >::divider () const
	Get current divider value.
constexpr	pw::clock_tree::OptionalElement::OptionalElement (Element *element=nullptr)
constexpr	pw::clock_tree::OptionalElement::OptionalElement (Element &element)
Status	pw::clock_tree::OptionalElement::Acquire ()
Status	pw::clock_tree::OptionalElement::Release ()

Variables
static constexpr bool	pw::clock_tree::ElementBlocking::kMayBlock = true
static constexpr bool	pw::clock_tree::ElementBlocking::kMayFail = true
static constexpr bool	pw::clock_tree::ElementNonBlockingMightFail::kMayBlock = false
static constexpr bool	pw::clock_tree::ElementNonBlockingMightFail::kMayFail = true
static constexpr bool	pw::clock_tree::ElementNonBlockingCannotFail::kMayFail = false

Typedef Documentation

ClockDividerNonBlockingCannotFail

using pw::clock_tree::ClockDividerNonBlockingCannotFail = typedef ClockDividerElement<ElementNonBlockingCannotFail>

Alias for a non-blocking clock divider tree element where updates cannot fail.

ClockDividerNonBlockingMightFail

using pw::clock_tree::ClockDividerNonBlockingMightFail = typedef ClockDividerElement<ElementNonBlockingMightFail>

Alias for a non-blocking clock divider tree element where updates might fail.

Function Documentation

Acquire() [1/2]

Status pw::clock_tree::Element::Acquire ( )

inline

Acquire a reference to this clock tree element.

Note: Calling this method called from interrupt context or with interrupts disabled is only permitted on an ElementNonBlockingMightFail or ElementNonBlockingCannotFail instance, and not on a ElementBlocking or generic Element instance.

Acquire() [2/2]

Status pw::clock_tree::OptionalElement::Acquire ( )

inline

Acquire a reference to the optional clock tree element.

If the optional element pointer is null, the function just returns pw::OkStatus().

AcquireWith()

Status pw::clock_tree::Element::AcquireWith ( Element &  element_with )

inline

Acquire a reference to this clock tree element while element_with clock tree is enabled. Acquiring the clock tree element might fail.

This is useful when dealing with synchronized clock muxes where, in order to switch to a new clock source, both the old and new clock must be running. This ensures that the old clock source (element_with) is running before attempting to activate the new clock source (element).

Note: May not be called from inside an interrupt context or with interrupts disabled.

ClockDividerElement()

template<typename ElementType >

constexpr pw::clock_tree::ClockDividerElement< ElementType >::ClockDividerElement ( ElementType &  source, uint32_t  divider  )

inlineconstexpr

Create a clock divider element that depends on source and gets configured with divider value when enabled.

DoAcquire() [1/3]

Status pw::clock_tree::ElementBlocking::DoAcquire ( )

inlinefinalprivatevirtual

Handle Acquire(), deferring locking the child class.

Implements pw::clock_tree::Element.

DoAcquire() [2/3]

Status pw::clock_tree::ElementNonBlockingMightFail::DoAcquire ( )

inlinefinalprivatevirtual

Handle Acquire(), deferring locking the child class.

Implements pw::clock_tree::Element.

DoAcquire() [3/3]

virtual Status pw::clock_tree::Element::DoAcquire ( )

privatepure virtual

Handle Acquire(), deferring locking the child class.

Implemented in pw::clock_tree::ElementBlocking, and pw::clock_tree::ElementNonBlockingMightFail.

DoAcquireLocked() [1/3]

template<typename ElementType >

Status pw::clock_tree::ClockSource< ElementType >::DoAcquireLocked ( )

inlinefinalprivate

Acquire a reference to the clock source.

When the first reference gets acquired, the clock source gets enabled.

DoAcquireLocked() [2/3]

template<typename ElementType >

Status pw::clock_tree::DependentElement< ElementType >::DoAcquireLocked ( )

inlinefinalprivate

Acquire a reference to the dependent clock tree element.

When the first reference gets acquired, a reference to the source element gets acquired, before the dependent clock tree element gets enabled.

DoAcquireLocked() [3/3]

virtual Status pw::clock_tree::Element::DoAcquireLocked ( )

protectedpure virtual

Acquire a reference to the clock tree element.

Acquiring a reference to a clock tree element ensures that the clock tree element is configured and enabled.

If the clock tree element depends on another clock tree element, a reference to the dependent clock tree element will get acquired when the first reference to this clock tree element gets acquired. This ensures that all dependent clock tree elements have been enabled before this clock tree element gets configured and enabled.

Implemented in pw::clock_tree::ClockSource< ElementNonBlockingCannotFail >.

DoDisable() [1/2]

virtual Status pw::clock_tree::Element::DoDisable ( )

inlineprotectedvirtual

Function called when the clock tree element can get disabled.

Can be overridden by child class in case the clock tree element can be disabled to save power.

Reimplemented in pw::clock_tree::ClockSourceNoOp, pw::clock_tree::ClockMcuxpressoFro, and pw::clock_tree::ClockMcuxpressoLpOsc.

DoDisable() [2/2]

pw::Status pw::clock_tree::ClockSourceNoOp::DoDisable ( )

inlinefinalprivatevirtual

Function called when the clock tree element can get disabled.

Can be overridden by child class in case the clock tree element can be disabled to save power.

Reimplemented from pw::clock_tree::Element.

DoEnable() [1/2]

pw::Status pw::clock_tree::ClockSourceNoOp::DoEnable ( )

inlinefinalprivatevirtual

Function called when the clock tree element needs to get enabled.

Implements pw::clock_tree::Element.

DoEnable() [2/2]

virtual Status pw::clock_tree::Element::DoEnable ( )

protectedpure virtual

Function called when the clock tree element needs to get enabled.

Implemented in pw::clock_tree::ClockSourceNoOp, pw::clock_tree::ClockMcuxpressoFro, and pw::clock_tree::ClockMcuxpressoLpOsc.

DoRelease() [1/3]

Status pw::clock_tree::ElementBlocking::DoRelease ( )

inlinefinalprivatevirtual

Handle Release(), deferring locking the child class.

Implements pw::clock_tree::Element.

DoRelease() [2/3]

Status pw::clock_tree::ElementNonBlockingMightFail::DoRelease ( )

inlinefinalprivatevirtual

Handle Release(), deferring locking the child class.

Implements pw::clock_tree::Element.

DoRelease() [3/3]

virtual Status pw::clock_tree::Element::DoRelease ( )

privatepure virtual

Handle Release(), deferring locking the child class.

Implemented in pw::clock_tree::ElementBlocking, and pw::clock_tree::ElementNonBlockingMightFail.

DoReleaseLocked() [1/3]

template<typename ElementType >

Status pw::clock_tree::ClockSource< ElementType >::DoReleaseLocked ( )

inlinefinalprivate

Release a reference to the clock source.

When the last reference gets released, the clock source gets disabled.

DoReleaseLocked() [2/3]

template<typename ElementType >

Status pw::clock_tree::DependentElement< ElementType >::DoReleaseLocked ( )

inlinefinalprivate

Release a reference to the dependent clock tree element.

When the last reference gets released, the dependent clock tree element gets disabled (if implemented), before the reference to the source element gets released.

DoReleaseLocked() [3/3]

virtual Status pw::clock_tree::Element::DoReleaseLocked ( )

protectedpure virtual

Release a reference to the clock tree element.

Releasing the last reference to the clock tree element will disable the clock tree element.

When the last reference to the clock tree element gets released, the clock tree element gets disabled if the DoDisable function is overridden.

If the clock tree element depends on another clock tree element, a reference to the dependent clock tree element will get released once the last reference to this clock tree element has been released and the clock tree element has been disabled. This ensures that the clock tree element gets disabled before all dependent clock tree elements have been disabled.

Implemented in pw::clock_tree::ClockSource< ElementNonBlockingCannotFail >.

DoSetDivider()

template<typename ElementType >

Status pw::clock_tree::ClockDividerElement< ElementType >::DoSetDivider ( uint32_t  divider )

inlinefinalprivatevirtual

Implements pw::clock_tree::ClockDivider.

Release() [1/2]

Status pw::clock_tree::Element::Release ( )

inline

Release a reference to this clock tree element.

Note: Calling this method called from interrupt context or with interrupts disabled is only permitted on an ElementNonBlockingMightFail or ElementNonBlockingCannotFail instance, and not on a ElementBlocking or generic Element instance.

Release() [2/2]

Status pw::clock_tree::OptionalElement::Release ( )

inline

Release a reference to the optional clock tree element.

If the optional element pointer is null, the function just returns pw::OkStatus().

SetDivider() [1/2]

Status pw::clock_tree::ClockDivider::SetDivider ( uint32_t  divider )

inline

Set divider value.

The divider value will get updated as part of this method if the clock divider is currently active, otherwise the new divider value will be configured when the clock divider gets enabled next.

SetDivider() [2/2]

template<typename ElementType >

template<typename T = ElementType>

std::enable_if_t< T::kMayFail, pw::Status > pw::clock_tree::ClockDividerElement< ElementType >::SetDivider ( uint32_t  divider )

inline

Set divider value.

The divider value will get updated as part of this method if the clock divider is currently active, otherwise the new divider value will be configured when the clock divider gets enabled next.