clock_tree.h

// Copyright 2024 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
 
#include <cstdint>
#include <memory>
#include <mutex>
 
#include "pw_assert/assert.h"
#include "pw_status/status.h"
#include "pw_status/try.h"
#include "pw_sync/interrupt_spin_lock.h"
#include "pw_sync/mutex.h"
 
namespace pw::clock_tree {
 
class Element {
 public:
  constexpr Element(bool may_block = false) : may_block_(may_block) {}
  virtual ~Element() = default;
 
  uint32_t ref_count() const { return ref_count_; }
 
  bool may_block() const { return may_block_; }
 
  // Not copyable or movable
  Element(const Element&) = delete;
  Element(const Element&&) = delete;
  Element& operator=(const Element&) = delete;
  Element& operator=(const Element&&) = delete;
 
 protected:
  virtual Status Acquire() = 0;
 
  virtual Status Release() = 0;
 
  uint32_t IncRef() { return ++ref_count_; }
 
  uint32_t DecRef() { return --ref_count_; }
 
  virtual Status DoEnable() = 0;
 
  virtual Status DoDisable() { return OkStatus(); }
 
 private:
  uint32_t ref_count_ = 0;
 
  const bool may_block_;
 
  friend class ClockTree;
  template <typename ElementType>
  friend class DependentElement;
  friend class ClockDivider;
};
 
class ElementBlocking : public Element {
 public:
  constexpr ElementBlocking() : Element(/*may_block=*/true) {}
};
 
class ElementNonBlockingCannotFail : public Element {};
 
class ElementNonBlockingMightFail : public Element {};
 
template <typename ElementType>
class ClockSource : public ElementType {
 private:
  Status Acquire() final {
    if (this->IncRef() > 1) {
      // This clock tree element is already enabled.
      return OkStatus();
    }
 
    // Enable clock source.
    Status status = this->DoEnable();
    if (!status.ok()) {
      this->DecRef();
    }
    return status;
  }
 
  Status Release() final {
    if (this->DecRef() > 0) {
      // The clock tree element remains enabled.
      return OkStatus();
    }
 
    // Disable the clock source.
    Status status = this->DoDisable();
    if (!status.ok()) {
      this->IncRef();
    }
    return status;
  }
};
 
class ClockSourceNoOp : public ClockSource<ElementNonBlockingCannotFail> {
 private:
  pw::Status DoEnable() final { return pw::OkStatus(); }
 
  pw::Status DoDisable() final { return pw::OkStatus(); }
};
 
template <typename ElementType>
class DependentElement : public ElementType {
 public:
  constexpr DependentElement(ElementType& source) : source_(&source) {}
 
 protected:
  Status UpdateSource(ElementType& new_source, bool permit_change_if_in_use) {
    // If the element is not enabled, we can update the `source_` directly.
    if (this->ref_count() == 0) {
      source_ = &new_source;
      return OkStatus();
    }
 
    // The element is active, check whether we are allowed to change the source.
    if (!permit_change_if_in_use) {
      return Status::FailedPrecondition();
    }
 
    ElementType* old_source = source_;
 
    // Acquire the dependent sources for the new_source element.
    PW_TRY(new_source.Acquire());
 
    // Disable this current element configuration.
    if (Status status = this->DoDisable(); !status.ok()) {
      new_source.Release().IgnoreError();
      return status;
    }
 
    // Enable the new source element configuration.
    Status status = this->DoEnable();
 
    // Release the reference to the old dependent source regardless whether
    // we have enabled the new source, since we have successfully disabled it.
    old_source->Release().IgnoreError();
 
    // Check whether the `DoEnable` method succeeded for the new source.
    if (!status.ok()) {
      new_source.Release().IgnoreError();
      this->DecRef();
      return status;
    }
 
    // Everything has succeeded, change the source_ element.
    source_ = &new_source;
    return OkStatus();
  }
 
 private:
  Status Acquire() final {
    if (this->IncRef() > 1) {
      // This clock tree element is already enabled.
      return OkStatus();
    }
 
    // Acquire a reference to the dependent clock tree element before
    // enabling this clock tree element.
    if (Status status = source_->Acquire(); !status.ok()) {
      this->DecRef();
      return status;
    }
 
    Status status = this->DoEnable();
    if (!status.ok()) {
      source_->Release().IgnoreError();
      this->DecRef();
    }
    return status;
  }
 
  Status Release() final {
    if (this->DecRef() > 0) {
      // The clock tree element remains enabled.
      return OkStatus();
    }
 
    // Disable the clock tree element.
    if (Status status = this->DoDisable(); !status.ok()) {
      this->IncRef();
      return status;
    }
    // Even if releasing the dependent source references fails,
    // we won't re-enable the clock source, and instead just return
    // the error code to the caller.
    return source_->Release();
  }
 
  ElementType* source_;
};
 
class ClockDivider {
 public:
  constexpr ClockDivider(Element& element) : element_(element) {}
 
  virtual ~ClockDivider() = default;
 
  virtual Status Set(uint32_t divider) = 0;
 
  Element& element() const { return element_; }
 
 private:
  Element& element_;
};
 
template <typename ElementType>
class ClockDividerElement : public DependentElement<ElementType>,
                            public ClockDivider {
 public:
  constexpr ClockDividerElement(ElementType& source, uint32_t divider)
      : DependentElement<ElementType>(source),
        ClockDivider(static_cast<Element&>(*this)),
        divider_(divider) {}
 
  Status Set(uint32_t divider) override {
    uint32_t old_divider = divider_;
    divider_ = divider;
    if (this->ref_count() == 0) {
      return OkStatus();
    }
 
    Status status = this->DoEnable();
    if (!status.ok()) {
      // Restore old divider value.
      divider_ = old_divider;
    }
    return status;
  }
 
 protected:
  uint32_t divider() const { return divider_; }
 
 private:
  uint32_t divider_;
};
 
using ClockDividerBlocking = ClockDividerElement<ElementBlocking>;
 
using ClockDividerNonBlockingCannotFail =
    ClockDividerElement<ElementNonBlockingCannotFail>;
 
using ClockDividerNonBlockingMightFail =
    ClockDividerElement<ElementNonBlockingMightFail>;
 
class ClockTree {
 public:
  void Acquire(ElementNonBlockingCannotFail& element) {
    std::lock_guard lock(interrupt_spin_lock_);
    Status status = element.Acquire();
    PW_DASSERT(status.ok());
  }
 
  Status Acquire(ElementNonBlockingMightFail& element) {
    std::lock_guard lock(interrupt_spin_lock_);
    return element.Acquire();
  }
 
  Status Acquire(ElementBlocking& element) {
    std::lock_guard lock(mutex_);
    return element.Acquire();
  }
 
  Status Acquire(Element& element) {
    if (element.may_block()) {
      std::lock_guard lock(mutex_);
      return element.Acquire();
    }
    std::lock_guard lock(interrupt_spin_lock_);
    return element.Acquire();
  }
 
  Status AcquireWith(Element& element, Element& element_with) {
    PW_TRY(Acquire(element_with));
    Status status = Acquire(element);
    Release(element_with).IgnoreError();
    return status;
  }
 
  void Release(ElementNonBlockingCannotFail& element) {
    std::lock_guard lock(interrupt_spin_lock_);
    Status status = element.Release();
    PW_DASSERT(status.ok());
  }
 
  Status Release(ElementNonBlockingMightFail& element) {
    std::lock_guard lock(interrupt_spin_lock_);
    return element.Release();
  }
 
  Status Release(ElementBlocking& element) {
    std::lock_guard lock(mutex_);
    return element.Release();
  }
 
  Status Release(Element& element) {
    if (element.may_block()) {
      std::lock_guard lock(mutex_);
      return element.Release();
    }
    std::lock_guard lock(interrupt_spin_lock_);
    return element.Release();
  }
 
  void SetDividerValue(ClockDividerNonBlockingCannotFail& clock_divider,
                       uint32_t divider_value) {
    std::lock_guard lock(interrupt_spin_lock_);
    Status status = clock_divider.Set(divider_value);
    PW_DASSERT(status.ok());
  }
 
  Status SetDividerValue(ClockDividerNonBlockingMightFail& clock_divider,
                         uint32_t divider_value) {
    std::lock_guard lock(interrupt_spin_lock_);
    return clock_divider.Set(divider_value);
  }
 
  Status SetDividerValue(ClockDividerBlocking& clock_divider,
                         uint32_t divider_value) {
    std::lock_guard lock(mutex_);
    return clock_divider.Set(divider_value);
  }
 
  Status SetDividerValue(ClockDivider& clock_divider, uint32_t divider_value) {
    if (clock_divider.element().may_block()) {
      std::lock_guard lock(mutex_);
      return clock_divider.Set(divider_value);
    }
    std::lock_guard lock(interrupt_spin_lock_);
    return clock_divider.Set(divider_value);
  }
 
 protected:
  sync::Mutex mutex_;
 
  sync::InterruptSpinLock interrupt_spin_lock_;
};
 
class ElementController {
 public:
  constexpr ElementController(ClockTree* clock_tree = nullptr,
                              Element* element = nullptr)
      : clock_tree_(clock_tree), element_(element) {}
 
  Status Acquire() {
    if (clock_tree_ != nullptr && element_ != nullptr) {
      return clock_tree_->Acquire(*element_);
    }
    return OkStatus();
  }
 
  Status Release() {
    if (clock_tree_ != nullptr && element_ != nullptr) {
      return clock_tree_->Release(*element_);
    }
    return OkStatus();
  }
 
  ClockTree* clock_tree_ = nullptr;
 
  Element* element_ = nullptr;
};
}  // namespace pw::clock_tree