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 <atomic>
#include <cstdint>
#include <memory>
#include <mutex>
#include <optional>
 
#include "pw_assert/assert.h"
#include "pw_clock_tree/internal/deferred_init.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) : 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;
 
  Status Acquire() { return DoAcquire(); }
 
  Status Release() { return DoRelease(); }
 
  Status AcquireWith(Element& element_with) {
    PW_TRY(element_with.Acquire());
    Status status = Acquire();
    // Ignore any error on release because it should not fail if the acquire
    // succeeded, and there's no reasonable alternative.
    element_with.Release().IgnoreError();
    return status;
  }
 
 protected:
  virtual Status DoAcquireLocked() = 0;
 
  virtual Status DoReleaseLocked() = 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_;
 
  virtual Status DoAcquire() = 0;
 
  virtual Status DoRelease() = 0;
};
 
class ElementBlocking : public Element {
 public:
  static constexpr bool kMayBlock = true;
  static constexpr bool kMayFail = true;
  constexpr ElementBlocking() : Element(kMayBlock) {}
 
 protected:
  sync::Mutex& lock() { return *mutex_; }
 
 private:
  // sync::Mutex is not constexpr-constructible so use DeferredInit so we can
  // keep our constexpr constructor.
  internal::DeferredInit<sync::Mutex> mutex_;
 
  Status DoAcquire() final {
    std::lock_guard lock(this->lock());
    return DoAcquireLocked();
  }
  Status DoRelease() final {
    std::lock_guard lock(this->lock());
    return DoReleaseLocked();
  }
};
 
class ElementNonBlockingMightFail : public Element {
 public:
  static constexpr bool kMayBlock = false;
  static constexpr bool kMayFail = true;
  constexpr ElementNonBlockingMightFail() : Element(kMayBlock) {}
 
 protected:
  sync::InterruptSpinLock& lock() { return spin_lock_; }
 
 private:
  sync::InterruptSpinLock spin_lock_;
 
  Status DoAcquire() final {
    std::lock_guard lock(this->lock());
    return DoAcquireLocked();
  }
  Status DoRelease() final {
    std::lock_guard lock(this->lock());
    return DoReleaseLocked();
  }
};
 
class ElementNonBlockingCannotFail : public ElementNonBlockingMightFail {
 public:
  static constexpr bool kMayFail = false;
 
  void Acquire() { PW_DASSERT(ElementNonBlockingMightFail::Acquire().ok()); }
 
  void Release() { PW_DASSERT(ElementNonBlockingMightFail::Release().ok()); }
};
 
template <typename ElementType>
class ClockSource : public ElementType {
 private:
  Status DoAcquireLocked() 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 DoReleaseLocked() 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) {}
 
 private:
  Status DoAcquireLocked() 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 DoReleaseLocked() 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();
  }
 
 private:
  // NOTE: This is an Element* not ElementType* to allow the Acquire() and
  // Release() calls above to consistently use a Status return type.
  // We still use ElementType& in the constructor to ensure a nonblocking clock
  // element cannot depend on a blocking one.
  // TODO: https://pwbug.dev/434801926 - Change this this to ElementType and
  // use something like:
  //   if constexpr (std::remove_pointer_t<decltype(source_)>::kMayFail)
  // to handle the optional Status return value.
  Element* source_;
};
 
class ClockDivider {
 public:
  constexpr ClockDivider(Element& element) : element_(element) {}
 
  virtual ~ClockDivider() = default;
 
  Status SetDivider(uint32_t divider) { return DoSetDivider(divider); }
 
  // TODO: https://pwbug.dev/434801926 - Remove this compat shim
  [[deprecated("Use SetDivider()")]]
  Status Set(uint32_t divider) {
    return SetDivider(divider);
  }
 
  Element& element() const { return element_; }
 
 private:
  Element& element_;
 
  virtual Status DoSetDivider(uint32_t divider) = 0;
};
 
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) {}
 
  template <typename T = ElementType>
  typename std::enable_if_t<T::kMayFail, pw::Status> SetDivider(
      uint32_t divider) {
    return ClockDivider::SetDivider(divider);
  }
 
  template <typename T = ElementType>
  typename std::enable_if_t<!T::kMayFail, void> SetDivider(uint32_t divider) {
    PW_ASSERT_OK(ClockDivider::SetDivider(divider));
  }
 
 protected:
  uint32_t divider() const { return divider_; }
 
 private:
  uint32_t divider_;
 
  Status DoSetDivider(uint32_t divider) final {
    std::lock_guard lock(this->lock());
    return DoSetDividerLocked(divider);
  }
 
  Status DoSetDividerLocked(uint32_t divider) {
    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;
  }
};
 
using ClockDividerBlocking = ClockDividerElement<ElementBlocking>;
 
using ClockDividerNonBlockingCannotFail =
    ClockDividerElement<ElementNonBlockingCannotFail>;
 
using ClockDividerNonBlockingMightFail =
    ClockDividerElement<ElementNonBlockingMightFail>;
 
class OptionalElement {
 public:
  explicit constexpr OptionalElement(Element* element = nullptr)
      : element_(element) {}
 
  explicit constexpr OptionalElement(Element& element)
      : OptionalElement(&element) {}
 
  Status Acquire() {
    if (element_ != nullptr) {
      return element_->Acquire();
    }
    return OkStatus();
  }
 
  Status Release() {
    if (element_ != nullptr) {
      return element_->Release();
    }
    return OkStatus();
  }
 
 private:
  Element* element_ = nullptr;
};
 
}  // namespace pw::clock_tree