basic.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 <cstddef>
#include <cstdint>
#include <new>
#include <type_traits>
 
#include "lib/stdcompat/bit.h"
#include "pw_allocator/hardening.h"
#include "pw_bytes/alignment.h"
#include "pw_result/result.h"
#include "pw_status/status.h"
 
namespace pw::allocator {
namespace internal {
 
template <typename From, typename To>
struct CopyConst {
  using type = std::conditional_t<std::is_const_v<From>,
                                  std::add_const_t<To>,
                                  std::remove_const_t<To>>;
};
 
template <typename From, typename To>
using copy_const_t = typename CopyConst<From, To>::type;
 
template <typename From, typename To>
using copy_const_ptr_t =
    std::add_pointer_t<typename CopyConst<std::remove_pointer_t<From>,
                                          std::remove_pointer_t<To>>::type>;
 
// Trivial base class for trait support.
struct BasicBase {};
 
}  // namespace internal
 
 
template <typename Derived>
class BasicBlock : public internal::BasicBase {
 public:
  static constexpr size_t kAlignment = Derived::DefaultAlignment();
  static constexpr size_t kBlockOverhead =
      AlignUp(Derived::BlockOverhead(), kAlignment);
  static constexpr size_t kMinOuterSize =
      kBlockOverhead + AlignUp(Derived::MinInnerSize(), kAlignment);
 
  ~BasicBlock() = default;
 
  // No copy or move.
  BasicBlock(const BasicBlock& other) = delete;
  BasicBlock& operator=(const BasicBlock& other) = delete;
 
  static constexpr Result<Derived*> Init(ByteSpan region);
 
  template <typename Ptr>
  static constexpr internal::copy_const_ptr_t<Ptr, Derived*> FromUsableSpace(
      Ptr usable_space);
 
  constexpr std::byte* UsableSpace();
  constexpr const std::byte* UsableSpace() const;
  constexpr std::byte* UsableSpaceUnchecked() {
    return UsableSpaceUncheckedImpl(this);
  }
  constexpr const std::byte* UsableSpaceUnchecked() const {
    return UsableSpaceUncheckedImpl(this);
  }
 
  static constexpr size_t OuterSizeFromInnerSize(size_t inner_size);
 
  static constexpr size_t InnerSizeFromOuterSize(size_t outer_size);
 
  constexpr size_t OuterSize() const;
 
  constexpr size_t InnerSize() const;
  constexpr size_t InnerSizeUnchecked() const;
 
  constexpr bool IsValid() const;
 
  constexpr bool CheckInvariants() const;
 
 protected:
  constexpr BasicBlock() = default;
 
  constexpr bool DoCheckInvariants(bool strict) const;
 
 private:
  constexpr const Derived* derived() const {
    return static_cast<const Derived*>(this);
  }
 
  template <typename Ptr>
  static constexpr internal::copy_const_ptr_t<Ptr, std::byte*>
  UsableSpaceUncheckedImpl(Ptr block);
};
 
template <typename T>
struct is_block : std::is_base_of<internal::BasicBase, T> {};
 
template <typename T>
constexpr bool is_block_v = is_block<T>::value;
 
 
namespace internal {
 
void CheckMisaligned(const void* block, bool is_aligned);
 
}  // namespace internal
 
// Template method implementations.
 
template <typename Derived>
constexpr Result<Derived*> BasicBlock<Derived>::Init(ByteSpan region) {
  region = GetAlignedSubspan(region, Derived::kAlignment);
  if (region.size() <= Derived::kBlockOverhead) {
    return Status::ResourceExhausted();
  }
  if (region.size() > Derived::MaxAddressableSize()) {
    return Status::OutOfRange();
  }
  auto* block = Derived::AsBlock(region);
  if constexpr (Hardening::kIncludesDebugChecks) {
    block->CheckInvariants();
  }
  return block;
}
 
template <typename Derived>
template <typename Ptr>
constexpr internal::copy_const_ptr_t<Ptr, Derived*>
BasicBlock<Derived>::FromUsableSpace(Ptr usable_space) {
  using BlockPtr = internal::copy_const_ptr_t<Ptr, Derived*>;
  auto addr = cpp20::bit_cast<uintptr_t>(usable_space);
  Hardening::Decrement(addr, kBlockOverhead);
  auto* block = std::launder(reinterpret_cast<BlockPtr>(addr));
  if constexpr (Hardening::kIncludesBasicChecks) {
    block->CheckInvariants();
  }
  return block;
}
 
template <typename Derived>
constexpr std::byte* BasicBlock<Derived>::UsableSpace() {
  if constexpr (Hardening::kIncludesDebugChecks) {
    CheckInvariants();
  }
  return UsableSpaceUnchecked();
}
 
template <typename Derived>
constexpr const std::byte* BasicBlock<Derived>::UsableSpace() const {
  if constexpr (Hardening::kIncludesDebugChecks) {
    CheckInvariants();
  }
  return UsableSpaceUnchecked();
}
 
template <typename Derived>
template <typename Ptr>
constexpr internal::copy_const_ptr_t<Ptr, std::byte*>
BasicBlock<Derived>::UsableSpaceUncheckedImpl(Ptr block) {
  using BytePtr = internal::copy_const_ptr_t<Derived, std::byte*>;
  auto addr = cpp20::bit_cast<uintptr_t>(block);
  Hardening::Increment(addr, kBlockOverhead);
  return cpp20::bit_cast<BytePtr>(addr);
}
 
template <typename Derived>
constexpr size_t BasicBlock<Derived>::OuterSizeFromInnerSize(
    size_t inner_size) {
  size_t outer_size = inner_size;
  Hardening::Increment(outer_size, kBlockOverhead);
  return outer_size;
}
 
template <typename Derived>
constexpr size_t BasicBlock<Derived>::InnerSizeFromOuterSize(
    size_t outer_size) {
  size_t inner_size = outer_size;
  Hardening::Decrement(inner_size, kBlockOverhead);
  return inner_size;
}
 
template <typename Derived>
constexpr size_t BasicBlock<Derived>::OuterSize() const {
  if constexpr (Hardening::kIncludesDebugChecks) {
    CheckInvariants();
  }
  return derived()->OuterSizeUnchecked();
}
 
template <typename Derived>
constexpr size_t BasicBlock<Derived>::InnerSize() const {
  if constexpr (Hardening::kIncludesDebugChecks) {
    CheckInvariants();
  }
  return InnerSizeUnchecked();
}
 
template <typename Derived>
constexpr size_t BasicBlock<Derived>::InnerSizeUnchecked() const {
  return InnerSizeFromOuterSize(derived()->OuterSizeUnchecked());
}
 
template <typename Derived>
constexpr bool BasicBlock<Derived>::IsValid() const {
  return derived()->DoCheckInvariants(/*strict=*/false);
}
 
template <typename Derived>
constexpr bool BasicBlock<Derived>::CheckInvariants() const {
  return derived()->DoCheckInvariants(/*strict=*/true);
}
 
template <typename Derived>
constexpr bool BasicBlock<Derived>::DoCheckInvariants(bool strict) const {
  bool is_aligned = (cpp20::bit_cast<uintptr_t>(this) % kAlignment) == 0;
  if constexpr (Hardening::kIncludesDebugChecks) {
    internal::CheckMisaligned(this, is_aligned || !strict);
  }
  return is_aligned;
}
 
}  // namespace pw::allocator