APIs#

pw_clock_tree: Clock tree management for embedded devices

ClockTree#

class ClockTree#

Clock tree class that manages the state of clock tree elements.

The ClockTree provides the Acquire and Release methods to acquire a reference to ElementNonBlockingCannotFail, ElementNonBlockingMightFail, or ElementBlocking elements or to the generic Element element. These functions will acquire the proper lock to ensure that clock updates are synchronized.

The SetDividerValue method allows to change the divider value for ClockDividerNonBlockingCannotFail, ClockDividerNonBlockingMightFail or ClockDividerBlocking elements, or to the generic ClockDivider element.

Public Functions

inline void Acquire(ElementNonBlockingCannotFail &element)#: Acquire a reference to a non-blocking clock tree element. Acquiring the clock tree element will succeed.

inline Status Acquire(ElementNonBlockingMightFail &element)#: Acquire a reference to a non-blocking clock tree element. Acquiring the clock tree element might fail.

inline Status Acquire(ElementBlocking &element)#: Acquire a reference to a blocking clock tree element. Acquiring the clock tree element might fail.

inline Status Acquire(Element &element)#

Acquire a reference to a clock tree element. Acquiring the clock tree element might fail.

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

inline Status AcquireWith(Element &element, Element &element_with)#

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

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

inline void Release(ElementNonBlockingCannotFail &element)#: Release a reference to a non-blocking clock tree element. Releasing the clock tree element will succeed.

inline Status Release(ElementNonBlockingMightFail &element)#: Release a reference to a non-blocking clock tree element. Releasing the clock tree element might fail.

inline Status Release(ElementBlocking &element)#: Release a reference to a blocking clock tree element. Releasing the clock tree element might fail.

inline Status Release(Element &element)#

Release a reference to a clock tree element. Releasing the clock tree element might fail.

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

inline void SetDividerValue(ClockDividerNonBlockingCannotFail &clock_divider, uint32_t divider_value)#: Set divider value for a non-blocking clock divider element. Setting the clock divider value will succeed.

inline Status SetDividerValue(ClockDividerNonBlockingMightFail &clock_divider, uint32_t divider_value)#: Set divider value for a non-blocking clock divider element. Setting the clock divider value might fail.

inline Status SetDividerValue(ClockDividerBlocking &clock_divider, uint32_t divider_value)#: Set divider value for a blocking clock divider element. Setting the clock divider value might fail.

inline Status SetDividerValue(ClockDivider &clock_divider, uint32_t divider_value)#

Set divider value for a clock divider element. Setting the clock divider value might fail.

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

Element#

class Element#

Abstract base class for a clock tree element of a clock tree.

Class implementations of Element must implement Acquire and Release functions. For clock tree elements that only get enabled / configured, it is sufficient to only override the DoEnable function, otherwise it is required to override the DoDisable function to disable the respective clock tree element.

Note: Clock tree element classes shouldn’t be directly derived from the Element class, but from the ElementBlocking, ElementNonBlockingCannotFail or ElementNonBlockingMightFail class.

Subclassed by pw::clock_tree::ElementBlocking, pw::clock_tree::ElementNonBlockingCannotFail, pw::clock_tree::ElementNonBlockingMightFail

Public Functions

inline uint32_t ref_count() const#: Get reference count for this clock tree element.

inline bool may_block() const#: Check whether acquiring or releasing the element may block.

Protected Functions

virtual Status Acquire() = 0#

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.

virtual Status Release() = 0#

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.

inline uint32_t IncRef()#: Increment reference count and return incremented value.

inline uint32_t DecRef()#: Decrement reference count and return decremented value.

virtual Status DoEnable() = 0#: Function called when the clock tree element needs to get enabled.

inline virtual Status DoDisable()#

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.

ElementBlocking#

class ElementBlocking : public pw::clock_tree::Element #: Abstract class of a clock tree element that might need to block to perform element updates.

ElementNonBlockingCannotFail#

class ElementNonBlockingCannotFail : public pw::clock_tree::Element #

Abstract class of a clock tree element that will not block to perform element updates and will not fail when performing clock updates.

Subclassed by pw::clock_tree::ClockSource< ElementNonBlockingCannotFail >

ElementNonBlockingMightFail#

class ElementNonBlockingMightFail : public pw::clock_tree::Element #: Abstract class of a clock tree element that will not block to perform element updates and might fail when performing clock updates.

ClockSource#

template<typename ElementType> class ClockSource : public ElementType #

Abstract class template of a clock tree element that provides a clock source.

A ClockSource clock tree element does not depend on any other clock tree element, but provides a clock to the system that is not derived from another clock.

Class implementations of ClockSource must implement Acquire and Release functions. For clock sources that only get enabled / configured, it is sufficient to only override the DoEnable function, otherwise it is required to override the DoDisable function to disable the clock source.

Template argument ElementType can be of class ElementBlocking, ElementNonBlockingCannotFail or ElementNonBlockingMightFail.

ClockSourceNoOp#

class ClockSourceNoOp : public pw::clock_tree::ClockSource<ElementNonBlockingCannotFail>#: Class that represents a no-op clock source clock tree element that can be used to satisfy the dependent source clock tree element dependency for clock source classes that expect a source clock tree element.

DependentElement#

template<typename ElementType> class DependentElement : public ElementType #

Abstract class template of a clock tree element that depends on another clock tree element.

A DependentElement clock tree element depends on another clock tree element.

Class implementations of DependentElement must override the DoEnable function, the DoDisable function can be overridden to disable the dependent clock tree element to save power.

Template argument ElementType can be of class ElementBlocking, ElementNonBlockingCannotFail or ElementNonBlockingMightFail.

Subclassed by pw::clock_tree::ClockDividerElement< ElementType >, pw::clock_tree::ClockMcuxpressoAudioPll< ElementType >, pw::clock_tree::ClockMcuxpressoClkIn< ElementType >, pw::clock_tree::ClockMcuxpressoFrg< ElementType >, pw::clock_tree::ClockMcuxpressoMclk< ElementType >, pw::clock_tree::ClockMcuxpressoRtc< ElementType >, pw::clock_tree::ClockMcuxpressoSelector< ElementType >

Public Functions

inline constexpr DependentElement(ElementType &source)#: Create a dependent clock tree element that depends on source.

Protected Functions

inline Status UpdateSource(ElementType &new_source, bool permit_change_if_in_use)#

Update source dependency.

It is the responsibility of the derived class to ensure that the source dependency can only be changed when permitted, i.e. only if reference count is zero. If the update is permitted while the reference count is greater than zero, the caller of this function must make sure that the DoEnable method has access to the updated configuration matching the new source dependency. Only if the UpdateSource call succeeds, the new source has been configured as the source_ element for this element, otherwise the old source element is still configured as source_ element for this element. If the DoEnable call of the new source fails, the current element will be disabled, since the previous source got already released, and the old source remains configured as the dependent element.

ClockDivider#

class ClockDivider#

Abstract class of the clock divider specific interface.

The clock divider interface allows APIs to accept a ClockDivider element, if they want to use the ClockTree’s SetDividerValue method. They can use the element method to call the ClockTree’s Acquire and Release methods.

Subclassed by pw::clock_tree::ClockDividerElement< ElementType >

Public Functions

virtual Status Set(uint32_t divider) = 0#

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.

inline Element &element() const#: Return the element implementing this interface.

ClockDividerElement#

template<typename ElementType> class ClockDividerElement : public pw::clock_tree::DependentElement<ElementType>, public pw::clock_tree::ClockDivider #

Abstract class template of a clock divider element.

A ClockDivider clock tree element depends on another clock tree element and has a divider value that gets configured when the clock divider gets enabled.

Class implementations of ClockDivider must override the DoEnable function.

Template argument ElementType can be of class ElementBlocking, ElementNonBlockingCannotFail or ElementNonBlockingMightFail.

Subclassed by pw::clock_tree::ClockMcuxpressoDivider< ElementType >

Public Functions

inline constexpr ClockDividerElement(ElementType &source, uint32_t divider)#: Create a clock divider element that depends on source and gets configured with divider value when enabled.

inline virtual Status Set(uint32_t divider) override#

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.

Protected Functions

inline uint32_t divider() const#: Get current divider value.

ElementController#

class ElementController#

Helper class that allows drivers to accept optional clock tree information and streamline clock tree operations.

Public Functions

inline constexpr ElementController(ClockTree *clock_tree = nullptr, Element *element = nullptr)#: Create an element controller that accepts optional clock tree and element information.

inline Status Acquire()#

Acquire a reference to the optional clock tree element.

If not both optional clock_tree and element pointers are non-null, the function just returns pw::OkStatus().

inline Status Release()#

Release a reference to the optional clock tree element.

If not both optional clock_tree and element pointers are non-null, the function just returns pw::OkStatus().

Public Members

ClockTree *clock_tree_ = nullptr#: Pointer to optional ClockTree object.

Element *element_ = nullptr#: Pointer to optional Element object.