core.hpp

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0 */
/* Copyright 2015-2019 Peter A. Bigot */
 
#ifndef NRFCXX_CORE_HPP
#define NRFCXX_CORE_HPP
#pragma once
 
#include <cstddef>
#include <cstdint>
#include <functional>
 
#include <pabigot/container.hpp>
 
#include <nrfcxx/version.hpp>
 
extern "C" {
extern char __HeapBase;       
extern char __HeapLimit;      
extern char __StackLimit;     
extern char __StackTop;       
}
#ifndef NRFCXX_FAKED
 
#define NRFCXX_FAKED 0
#endif /* NRFCXX_FAKED */
 
#if (NRF51 - 0) || (NRFCXX_DOXYGEN - 0) || (NRFCXX_FAKED - 0)
 
#define NRF_SERIES 51
#elif (NRF52832 - 0) || (NRF52840 - 0)
#define NRF_SERIES 52
#elif (NRF52810 - 0)
/* NRF52810 has a different set of peripherals.  Add that when
 * we have hardware that needs it. */
#error NRF52810 not currently supported
#else /* NRF device */
#error Unrecognized NRF5 device
#endif /* NRF device */
 
namespace nrfcxx {
 
namespace board {
 
int initialize (bool enable_hfxt = false); // weak implemented in src/core.cc
 
} // ns board
 
namespace nrf5 {
 
namespace series {
 
#if (NRFCXX_DOXYGEN - 0)
 
#define ADCSeriesVariant_IRQHandler [SA]ADC_IRQHandler
#endif /* NRFCXX_DOXYGEN */
 
} // ns series
 
template <typename S>
struct peripheral {
  using Type = S;
 
  static constexpr int8_t NO_IRQ = -128;
 
  static constexpr uint8_t NO_INSTANCE = 255;
 
  constexpr explicit peripheral (uintptr_t base,
                                 int8_t irqn = NO_IRQ,
                                 uint8_t instance = NO_INSTANCE,
                                 uint8_t aux = 0) :
    BASE{base},
    IRQn{irqn},
    INSTANCE{instance},
    AUX{aux}
  { }
 
  Type* instance() const
  {
    return reinterpret_cast<Type*>(BASE);
  }
 
  Type* operator->() const
  {
    return instance();
  }
 
  const uintptr_t BASE;
 
  const int8_t IRQn;
 
  const uint8_t INSTANCE;
 
  const uint8_t AUX;
};
 
template <int I>
struct GPIO_Instance
{ };
 
} // nrf5
} // nrfcxx
 
#ifndef NRFCXX_CROSS_COMPILING
 
#define NRFCXX_CROSS_COMPILING 1
#endif /* NRFCXX_CROSS_COMPILING */
 
#if (NRFCXX_CROSS_COMPILING - 0)
#if (51 == NRF_SERIES)
#include <nrfcxx/nrf51/core.hpp>
#elif (52 == NRF_SERIES)
#include <nrfcxx/nrf52/core.hpp>
#endif // NRF_SERIES
#elif (NRFCXX_FAKED - 0)
#include <nrfcxx/faked/core.hpp>
#else
using IRQn_Type = int;
#endif /* NRFCXX_CROSS_COMPILING */
 
namespace nrfcxx {
 
inline void __attribute__((__gnu_inline__,__always_inline__))
delay_us (unsigned int number_of_us)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  if (number_of_us) {
    nrf5::series::delay_cycles(nrf5::series::CLOCK_MHz * number_of_us - nrf5::series::DELAY_US_OVERHEAD_cyc);
  }
#endif /* NRFCXX_CROSS_COMPILING */
}
 
void sleep_ms (unsigned int dur_ms);
 
class null_mutex
{
public:
  null_mutex ()
  { }
 
  null_mutex (const null_mutex&) = delete;
  null_mutex& operator= (const null_mutex&) = delete;
  null_mutex (null_mutex&& ) = delete;
  null_mutex& operator= (null_mutex&) = delete;
};
 
class primask
{
public:
  primask () :
    in_mask_{}
  {
#if (NRFCXX_CROSS_COMPILING - 0)
    __ASM volatile ("mrs\t%0, primask\n\t"
                    "cpsid\ti"
                    : "=r" (in_mask_)
                    :
                    : "memory");
#endif /* NRFCXX_CROSS_COMPILING */
  }
 
  ~primask ()
  {
#if (NRFCXX_CROSS_COMPILING - 0)
    __ASM volatile ("msr\tprimask, %0"
                    :
                    : "r" (in_mask_)
                    : "memory");
#endif /* NRFCXX_CROSS_COMPILING */
  }
 
  primask (const primask&) = delete;
  primask& operator= (const primask&) = delete;
  primask (primask&& ) = delete;
  primask& operator= (primask&) = delete;
 
private:
  uint32_t in_mask_;
};
 
static inline void nvic_EnableIRQ (int irqn)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_EnableIRQ(static_cast<IRQn_Type>(irqn));
#endif /* NRFCXX_CROSS_COMPILING */
}
 
static inline void nvic_DisableIRQ (int irqn)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_DisableIRQ(static_cast<IRQn_Type>(irqn));
#endif /* NRFCXX_CROSS_COMPILING */
}
 
static inline void nvic_GetPendingIRQ (int irqn)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_GetPendingIRQ(static_cast<IRQn_Type>(irqn));
#endif /* NRFCXX_CROSS_COMPILING */
}
 
static inline void nvic_SetPendingIRQ (int irqn)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_SetPendingIRQ(static_cast<IRQn_Type>(irqn));
#endif /* NRFCXX_CROSS_COMPILING */
}
 
static inline void nvic_ClearPendingIRQ (int irqn)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_ClearPendingIRQ(static_cast<IRQn_Type>(irqn));
#endif /* NRFCXX_CROSS_COMPILING */
}
 
static inline void nvic_SetPriority (int irqn, uint32_t priority)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_SetPriority(static_cast<IRQn_Type>(irqn), priority);
#endif /* NRFCXX_CROSS_COMPILING */
}
 
static inline void nvic_GetPriority (int irqn)
{
#if (NRFCXX_CROSS_COMPILING - 0)
  NVIC_GetPriority(static_cast<IRQn_Type>(irqn));
#endif /* NRFCXX_CROSS_COMPILING */
}
 
class nvic_BlockIRQ
{
public:
  explicit nvic_BlockIRQ (IRQn_Type irqn) :
    in_mask_{}
  {
#if (NRFCXX_CROSS_COMPILING - 0)
    uint32_t mask = 1U << (0x1F & (unsigned int)irqn);
    in_mask_ = mask & NVIC->ISER[0];
    NVIC->ICER[0] = mask;
#endif /* NRFCXX_CROSS_COMPILING */
  }
 
#if (NRFCXX_CROSS_COMPILING - 0)
 
  explicit nvic_BlockIRQ (int irqn) :
    nvic_BlockIRQ{static_cast<IRQn_Type>(irqn)}
  { }
#endif /* NRFCXX_CROSS_COMPILING */
 
  ~nvic_BlockIRQ ()
  {
#if (NRFCXX_CROSS_COMPILING - 0)
    NVIC->ISER[0] = in_mask_;
#endif /* NRFCXX_CROSS_COMPILING */
  }
 
  nvic_BlockIRQ (const nvic_BlockIRQ&) = delete;
  nvic_BlockIRQ& operator= (const nvic_BlockIRQ&) = delete;
  nvic_BlockIRQ (nvic_BlockIRQ&& ) = delete;
  nvic_BlockIRQ& operator= (nvic_BlockIRQ&) = delete;
 
private:
  uint32_t in_mask_;
};
 
template <IRQn_Type IRQn>
class mutex_irq : public nvic_BlockIRQ
{
public:
  mutex_irq () :
    nvic_BlockIRQ(IRQn)
  { }
};
 
using notifier_type = std::function<void()>;
 
/* Forward declaration */
class event_set_copy;
 
class event_set
{
public:
  using event_type = unsigned int;
 
  constexpr explicit event_set (event_type events = 0U) :
    events_{events}
  { }
 
  operator bool() const
  {
    return events_;
  }
 
  event_type fetch () const
  {
    return events_;
  }
 
  static void cev ()
  {
#if (NRFCXX_CROSS_COMPILING - 0)
    __SEV();
    __WFE();
#endif /* NRFCXX_CROSS_COMPILING */
  }
 
  event_type fetch_and_clear ()
  {
    primask mutex;
    event_type rv = events_;
    events_ = {};
    return rv;
  }
 
  event_set_copy copy_and_clear ();
 
  void set (event_type events)
  {
    primask mutex;
    events_ |= events;
#if (NRFCXX_CROSS_COMPILING - 0)
    __SEV();
#endif /* NRFCXX_CROSS_COMPILING */
  }
 
  void reset (event_type events = 0U)
  {
    primask mutex;
    events_ = events;
  }
 
  notifier_type make_setter (event_type events)
  {
    return [this,events]
      {
        this->set(events);
      };
  }
 
private:
  volatile event_type events_;
};
 
class event_set_copy
{
public:
  using event_type = event_set::event_type;
 
  event_set_copy (event_set& events) :
    events_{events.fetch_and_clear()}
  { }
 
  event_set_copy () = default;
 
  operator bool() const
  {
    return events_;
  }
 
  bool empty () const
  {
    return !events_;
  }
 
  event_type events () const
  {
    return events_;
  }
 
  void set (event_type events)
  {
    events_ |= events;
  }
 
  bool test_and_clear (event_type evt)
  {
    bool rv = (events_ & evt);
    events_ &= ~evt;
    return rv;
  }
 
private:
  event_type events_ = {};
};
 
inline
event_set_copy
event_set::copy_and_clear ()
{
  return event_set_copy(*this);
}
 
enum class FailSafeCode : unsigned int
{
  SYSTEM_BASE = 0xbad00000,
 
  NO_SUCH_PERIPHERAL = SYSTEM_BASE + 1,
 
  MEMORY_POOL = SYSTEM_BASE + 2,
 
  HEAP_OVERRUN = SYSTEM_BASE + 3,
 
  STACK_OVERFLOW = SYSTEM_BASE + 4,
 
  PERSIST_VIOLATION = SYSTEM_BASE + 5,
 
  INTERNAL_ERROR = SYSTEM_BASE + 6,
 
  INCOMPLETE_SETUP = SYSTEM_BASE + 7,
 
  RESOURCE_VIOLATION = SYSTEM_BASE + 8,
 
  API_VIOLATION = SYSTEM_BASE + 9,
 
  BOARD_INIT_FAILURE = SYSTEM_BASE + 10,
 
  EVENT_LOOP_TERMINATED = SYSTEM_BASE + 11,
 
  APPLICATION_BASE = 0xbad10000,
};
static inline
FailSafeCode operator+ (const FailSafeCode& lhs,
                        unsigned int incr)
{
  return static_cast<FailSafeCode>(static_cast<unsigned int>(lhs) + incr);
}
 
[[noreturn]]
inline __attribute__((__always_inline__))
void failsafe (FailSafeCode code);
 
[[noreturn]]
inline __attribute__((__always_inline__))
void failsafe (unsigned int code);
 
class systemState
{
  using om_type = uint8_t;
 
public:
  enum om_enum : om_type {
    OM_SLEEP = 0x01,
 
    OM_HFCLK = 0x02,
 
    OM_RADIO = 0x04,
 
    NUM_OPERATIONAL_MODES = (OM_RADIO << 1),
  };
 
  static unsigned int updateOperationalMode (unsigned int om_clear = 0,
                                             unsigned int om_set = 0);
 
  static const char* const operationalModeText[NUM_OPERATIONAL_MODES];
 
  class scoped_sleeper
  {
    scoped_sleeper (const scoped_sleeper&) = delete;
    scoped_sleeper& operator= (const scoped_sleeper&) = delete;
    scoped_sleeper (scoped_sleeper&&) = delete;
    scoped_sleeper& operator= (scoped_sleeper&&) = delete;
 
  public:
    ~scoped_sleeper () noexcept
    {
      ++systemState::wfe_count_;
      if (track_om) {
        updateOperationalMode(OM_SLEEP, 0);
      }
    }
 
    const bool track_om;
 
  private:
    friend systemState;
 
    scoped_sleeper (bool track_om) :
      track_om{track_om}
    {
      if (track_om) {
        updateOperationalMode(0, OM_SLEEP);
      }
    }
  };
 
  static scoped_sleeper make_scoped_sleeper () noexcept
  {
    return {statep_};
  }
 
  static void WFE ();
 
  struct state_type {
    static constexpr uint32_t DECL_MAGIC = 0x20181013U;
 
    uint32_t magic;
 
    unsigned int om_updated;
 
    uint64_t om_total[NUM_OPERATIONAL_MODES];
 
    uint64_t last_uptime;
 
    uint64_t total_uptime;
 
    uint32_t last_pc;
 
    unsigned int code;
 
    unsigned int sdfault_id;
 
    /* Cache for data to be copied to code during initialization when
     * #RESET_REAS_PROGRAMMATIC, #RESET_REAS_FAILSAFE, or
     * #RESET_REAS_SDFAULT is set in #reset_reas_.
     *
     * This is cleared after initialization completes. */
    unsigned int code_;
    uint16_t reset_count;
 
    using reset_reas_type = uint16_t;
 
    enum reset_reas_enum : reset_reas_type
    {
      RESET_REAS_RESETPIN = 0x0001,
 
      RESET_REAS_DOG = 0x0002,
 
      RESET_REAS_SREQ = 0x004,
 
      RESET_REAS_LOCKUP = 0x0008,
 
      RESET_REAS_OFF = 0x0010,
 
      RESET_REAS_LPCOMP = 0x0020,
 
      RESET_REAS_DIF = 0x0040,
 
      RESET_REAS_NFC = 0x0080,
 
      RESET_REAS_VBUS = 0x0100,
 
      RESET_REAS_HARDWARE_Msk = 0x01FF,
 
      /* Bits below are synthesized; bits above are from nRF5 MCUs.
       * The following bits are available: 9 @ 0x0200. */
 
      RESET_REAS_INTERNAL = 0x0400,
 
      RESET_REAS_PROGRAMMATIC = 0x0800,
 
      RESET_REAS_FAILSAFE = 0x1000,
 
      RESET_REAS_WDTBARKED = 0x2000,
 
      RESET_REAS_SDFAULT = 0x4000,
 
      RESET_REAS_CONTROLLED = 0x8000,
    };
 
    reset_reas_type reset_reas;
 
    uint16_t reset_reas_;
    uint8_t wdt_status;
 
    uint8_t om_value;
  };
 
  using app_handler_type = void (*) (const state_type& ss,
                                     bool is_reset,
                                     bool was_retained);
 
  systemState (state_type& state,
               uint32_t magic,
               app_handler_type app_handler = nullptr);
 
  const state_type& state () const
  {
    return state_;
  }
 
  static constexpr unsigned int WATCHDOG_Hz = 32768U;
 
  static constexpr auto WATCHDOG_MASK_EXTENDED = (1U << 8);
 
  int watchdogInit (unsigned int delay_32KiHz,
                    unsigned int channel_mask = 1,
                    bool run_in_sleep = true,
                    bool run_in_debug = false) const;
 
  bool watchdogActive () const;
 
  void watchdogFeed (unsigned int channel) const;
 
  void watchdogFeedMulti (unsigned int channel_mask) const;
 
  bool watchdogCheckExtended ();
 
  [[noreturn]]
  __attribute__((__always_inline__))
  void reset (unsigned int code,
              bool bypass_watchdog = false)
  {
    reset_(current_pc(), code, bypass_watchdog);
  }
 
  unsigned int stack_reserved () const;
 
  unsigned int stack_used () const;
 
  unsigned int heap_reserved() const;
 
  unsigned int heap_used () const;
 
  uint64_t operationalModeBreakdown (uint64_t &sleep_utt,
                                     uint64_t &radio_utt) const;
 
  static void sd_fault_handler (uint32_t id,
                                uint32_t pc,
                                uint32_t info);
 
  static uint32_t current_pc ();
 
  static uint64_t total_now ();
 
  static unsigned int wfe_count ()
  {
    return wfe_count_;
  }
 
  static void wdt_irqhandler (void* sp);
  [[noreturn]]
  static void systemOff (unsigned int preserve,
                         int button_psel = -1);
 
protected:
 
  /* Implement the reset operation. */
  [[noreturn]]
  static void reset_ (uint32_t pc,
                      unsigned int code,
                      bool bypass_watchdog = false);
 
  friend void failsafe (unsigned int code);
  friend void failsafe (FailSafeCode code);
 
  static void controlledResetPrep_ (unsigned int preserve);
 
  /* Implement the failsafe operation. */
  [[noreturn]]
  static void failsafe_ (uint32_t pc,
                         unsigned int code);
 
  /* Force or wait out the reset. */
  [[noreturn]]
  static void controlledReset_ (unsigned int preserve,
                                bool bypass_watchdog);
  static state_type* statep_;
 
  static app_handler_type app_handler_;
 
private:
  state_type& state_;
  const uint32_t magic_;
  static unsigned int wfe_count_;
};
 
class watchdog_extended_channel
{
  struct ref_next {
    using pointer_type = watchdog_extended_channel *;
    pointer_type& operator() (watchdog_extended_channel& wec) noexcept
    {
      return wec.next_;
    }
  };
 
  using chain_type = pabigot::container::forward_chain<watchdog_extended_channel, ref_next>;
 
public:
  static constexpr uint8_t WATCHDOG_CHANNEL_COMMON = 7;
 
  watchdog_extended_channel (unsigned int interval_utt);
 
  // On destruction the channel will be removed from the chain.
  ~watchdog_extended_channel ();
 
  void feed ();
 
  watchdog_extended_channel (const watchdog_extended_channel&) = delete;
  watchdog_extended_channel& operator= (const watchdog_extended_channel&) = delete;
  watchdog_extended_channel (watchdog_extended_channel&& ) = delete;
  watchdog_extended_channel& operator= (watchdog_extended_channel&) = delete;
 
private:
  friend class systemState;
 
  bool check (unsigned int now) const
  {
    return interval_utt > (now - last_fed_);
  }
 
  static chain_type chain_;
  static bool failed_;
 
  chain_type::pointer_type next_ = chain_type::unlinked_ptr();
  unsigned int last_fed_;
  unsigned int const interval_utt;
};
 
void failsafe (FailSafeCode code)
{
  systemState::failsafe_(systemState::current_pc(), static_cast<unsigned int>(code));
}
 
void failsafe (unsigned int code)
{
  systemState::failsafe_(systemState::current_pc(), code);
}
 
inline int __attribute__((__gnu_inline__,__always_inline__))
stack_space_remaining ()
{
  return (int32_t)(__get_MSP() - static_cast<uint32_t>(reinterpret_cast<uintptr_t>(&__StackLimit)));
}
 
inline void __attribute__((__gnu_inline__,__always_inline__))
validate_stack_pointer ()
{
  if (0 > stack_space_remaining()) {
    failsafe(FailSafeCode::STACK_OVERFLOW);
  }
}
 
unsigned int
stack_fill_unused (unsigned int marker);
 
unsigned int
stack_infer_highwater (unsigned int marker);
 
uint32_t application_crc32 (bool exclude_data = false);
 
namespace sensor {
} // ns sensor
 
namespace misc {
} // ns misc
 
} // ns nrfcxx
 
#endif /* NRFCXX_CORE_HPP */