periph.hpp

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0 */
/* Copyright 2015-2019 Peter A. Bigot */
 
#ifndef NRFCXX_PERIPH_HPP
#define NRFCXX_PERIPH_HPP
#pragma once
 
#include <nrfcxx/impl.hpp>
#include <pabigot/container.hpp>
#include <functional>
 
namespace nrfcxx {
 
namespace periph {
 
#ifndef NRFCXX_PERIPH_UART0_RXB_SIZE
 
#define NRFCXX_PERIPH_UART0_RXB_SIZE 8
#endif /* NRFCXX_PERIPH_UART0_RXB_SIZE */
 
#ifndef NRFCXX_PERIPH_UART0_TXB_SIZE
 
#define NRFCXX_PERIPH_UART0_TXB_SIZE 32
#endif /* NRFCXX_PERIPH_UART0_TXB_SIZE */
 
class UART
{
public:
  using fifo_type = pabigot::container::rr_adaptor<uint8_t>;
  using size_type = unsigned int;
  using ssize_type = int;
 
  struct statistics_type
  {
    unsigned int tx_count;
 
    unsigned int rx_count;
 
    unsigned int rx_dropped;
 
    unsigned int rx_break_errors;
 
    unsigned int rx_frame_errors;
 
    unsigned int rx_parity_errors;
 
    unsigned int rx_overrun_errors;
  };
 
  void enable (uint32_t cfg_baudrate = UART_BAUDRATE_BAUDRATE_Baud115200,
               bool hwfc = false);
 
  void disable ();
 
  bool enabled (bool live = false) const;
 
  bool autoenable (int on);
 
  ssize_type write (const uint8_t* sp, size_type count);
 
  ssize_type read (uint8_t* dp, size_type count);
 
  statistics_type statistics () const;
 
  static constexpr event_set::event_type EVT_RXAVAIL = 0x01;
 
  static constexpr event_set::event_type EVT_TXAVAIL = 0x02;
 
  static constexpr event_set::event_type EVT_TXDONE = 0x04;
 
  static constexpr event_set::event_type EVT_ERROR = 0x04;
 
  event_set& events ();
 
  static UART UART0;
 
  void irq_handler ();
 
  static UART& instance ();
 
  const nrf5::UART_Type& peripheral () const
  {
    return uart_;
  }
 
protected:
  UART (const nrf5::UART_Type& uart,
        fifo_type& rxb,
        fifo_type& txb,
        int rxd_pin,
        int txd_pin,
        int cts_pin = -1,
        int rts_pin = -1) :
    uart_{uart},
    rxb_{rxb},
    txb_{txb},
    rxd_pin_(rxd_pin), // narrowing conversion
    txd_pin_(txd_pin),
    cts_pin_(cts_pin),
    rts_pin_(rts_pin)
  { }
 
private:
  void set_enabled_bi_ (bool on,
                        bool from_autoenable);
 
  const nrf5::UART_Type& uart_;
  fifo_type& rxb_;
  fifo_type& txb_;
  statistics_type statistics_{};
  event_set events_{};
  uint8_t volatile flags_ = 0;
  int8_t const rxd_pin_;
  int8_t const txd_pin_;
  int8_t const cts_pin_;
  int8_t const rts_pin_;
};
 
class RTC
{
protected:
  constexpr RTC (const nrf5::RTC_Type& rtc) :
    rtc_{rtc}
  { }
 
public:
  constexpr static uint32_t counter_modulus = (1U << 24);
 
  constexpr static uint32_t counter_mask = (counter_modulus - 1);
 
  constexpr static unsigned int counter_delta (uint32_t a,
                                               uint32_t b)
  {
    /* This relies on standard semantics for unsigned subtraction to
     * handle the case where b < a. */
    return counter_mask & (b - a);
  }
 
  uint32_t counter () const
  {
    return rtc_->COUNTER;
  }
 
  static RTC& instance (int idx);
 
  const nrf5::RTC_Type& peripheral () const
  {
    return rtc_;
  }
 
  const unsigned int ccr_count () const
  {
    return rtc_.AUX;
  }
 
private:
  const nrf5::RTC_Type& rtc_;
};
 
class TIMER
{
protected:
  constexpr TIMER (const nrf5::TIMER_Type& timer) :
    timer_{timer},
    mask_{}
  { }
 
  void capture_ (unsigned int ccidx) const
  {
    timer_->TASKS_CAPTURE[ccidx] = 1;
  }
 
  unsigned int captured_ (unsigned int ccidx) const
  {
    return timer_->CC[ccidx];
  }
 
  unsigned int counter_ (unsigned int ccidx) const
  {
    capture_(ccidx);
    return captured_(ccidx);
  }
 
public:
  constexpr static unsigned int cc_mask = 7;
 
  constexpr static bool bitmode_supported (const nrf5::TIMER_Type& timer,
                                           unsigned int bitmode)
  {
#if (NRF51 - 0)
    /* nRF51 timers 1 and 2 do not support 24- and 32-bit modes */
    return ((TIMER_BITMODE_BITMODE_24Bit > bitmode)
            || (0 == timer.INSTANCE));
#else /* SERIES */
    /* All nRF52832 timers support all modes. */
    return true;
#endif /* SERIES */
  }
 
  int configure (unsigned int freq_Hz,
                 unsigned int bitmode = TIMER_BITMODE_BITMODE_16Bit,
                 bool use_constlat = true);
 
  void deconfigure ()
  {
    (void)configure(0);
  }
 
  unsigned int frequency_Hz () const;
 
  void start ()
  {
    timer_->TASKS_START = 1;
  }
 
  void clear ()
  {
    timer_->TASKS_CLEAR = 1;
  }
 
  void stop ()
  {
    timer_->TASKS_STOP = 1;
  }
 
  void shutdown ()
  {
    timer_->TASKS_SHUTDOWN = 1;
  }
 
  void capture (unsigned int ccidx) const
  {
    capture_(cc_mask & ccidx);
  }
 
  unsigned int captured (unsigned int ccidx) const
  {
    return captured_(cc_mask & ccidx);
  }
 
  unsigned int counter (unsigned int ccidx = 0) const
  {
    return counter_(cc_mask & ccidx);
  }
 
  unsigned int delta (unsigned int a,
                      unsigned int b) const
  {
    return mask_ & (b - a);
  }
 
  class timestamp_type
  {
  protected:
    const TIMER& timer_;
    unsigned int ccidx_;
    unsigned int capture_;
 
    friend class TIMER;
 
    timestamp_type (const TIMER& timer,
                    unsigned int ccidx) :
      timer_{timer},
      ccidx_{cc_mask & ccidx},
      capture_{timer.counter(ccidx_)}
    { }
 
  public:
    unsigned int captured () const
    {
      return capture_;
    }
 
    void reset ()
    {
      capture_ = timer_.counter(ccidx_);
    }
 
    unsigned int delta () const
    {
      auto now = timer_.counter_(ccidx_);
      return timer_.delta(capture_, now);
    }
 
    unsigned int delta (unsigned int counter) const
    {
      return timer_.delta(capture_, counter);
    }
 
    unsigned int delta_reset ()
    {
      auto now = timer_.counter_(ccidx_);
      auto rv = timer_.delta(capture_, now);
      capture_ = now;
      return rv;
    }
  };
 
  timestamp_type timestamp (unsigned int ccidx = 0) const
  {
    return timestamp_type{*this, ccidx};
  }
 
  static TIMER& instance (int idx);
 
  const nrf5::TIMER_Type& peripheral () const
  {
    return timer_;
  }
 
  const unsigned int ccr_count () const
  {
    return timer_.AUX;
  }
 
private:
  const nrf5::TIMER_Type& timer_;
 
  /* A bit mask isolating a count to the bits of the configured BITMODE */
  unsigned int mask_;
};
 
#ifndef NRFCXX_PERIPH_RNG_BUFFER_SIZE
 
#define NRFCXX_PERIPH_RNG_BUFFER_SIZE 8
#endif /* NRFCXX_PERIPH_RNG_BUFFER_SIZE */
 
class RNG
{
public:
  static void* fill (void* dest,
                     size_t count);
 
  template <typename T,
            typename = std::enable_if<std::is_integral<T>::value>>
  static T generate ()
  {
    union {
      T v;
      uint8_t u8[sizeof(T)];
    } u;
    fill(u.u8, sizeof(u.u8));
    return u.v;
  }
};
 
class GPIOTE
{
  /* Record which instances are in use.  An 8-bit map is sufficient
   * for nRF51 and nrf52832/840. */
  using registry_type = uint8_t;
 
public:
  using event_reference_type = __O uint32_t &;
 
  using task_reference_type = __IO uint32_t &;
 
  constexpr static size_t CHANNEL_COUNT = nrf5::GPIOTE.AUX;
 
  const uint8_t channel;
 
  using event_callback_bi = std::function<void(GPIOTE& instance)>;
 
  struct sense_status_type
  {
    int8_t psel;
 
    uint8_t counter_state;
 
    unsigned int aggregate_state (unsigned int previous = 0) const
    {
      return counter_state + (previous & ~1U);
    }
  };
 
  using sense_callback_bi = std::function<void(const sense_status_type* sp)>;
 
  /* You can't copy, assign, move, or otherwise change the set of
   * GPIOTE instances that the system provides to you. */
  GPIOTE () = delete;
  GPIOTE (const GPIOTE&) = delete;
  GPIOTE& operator= (const GPIOTE&) = delete;
  GPIOTE (const GPIOTE&&) = delete;
  GPIOTE& operator= (GPIOTE&&) = delete;
 
  using mutex_type = mutex_irq<GPIOTE_IRQn>;
 
  static void synchronize_sense ();
 
  class event_listener
  {
  public:
    using mutex_type = GPIOTE::mutex_type;
 
    event_listener (event_callback_bi callback_bi) :
      callback_bi{callback_bi},
      instance_{}
    { }
 
    ~event_listener ()
    {
      disable();
    }
 
    void enable (GPIOTE& instance);
 
    void disable ()
    {
      mutex_type mutex;
      disable_bi_();
    }
 
    /* You can't copy, assign, move, or otherwise muck with event
     * listeners, since they participate in a reference maintained by
     * the @link GPIOTE@endlink module. */
    event_listener (const event_listener&) = delete;
    event_listener& operator= (const event_listener&) = delete;
    event_listener (const event_listener&&) = delete;
    event_listener& operator= (event_listener&&) = delete;
    event_callback_bi const callback_bi;
 
  private:
    friend GPIOTE;
 
    /* Dissociate this listener from its GPIOTE instance, if any. */
    void disable_bi_ ()
    {
      if (instance_) {
        instance_->listener_ = nullptr;
      }
      instance_ = nullptr;
    }
 
    GPIOTE* instance_;
  };
 
  class sense_listener
  {
    struct ref_next
    {
      using pointer_type = sense_listener *;
      pointer_type& operator() (sense_listener& sl) noexcept
      {
        return sl.next_;
      }
    };
 
  public:
    using chain_type = pabigot::container::forward_chain<sense_listener, ref_next>;
 
    using mutex_type = GPIOTE::mutex_type;
 
    sense_listener (sense_callback_bi callback_bi) :
      callback_bi{callback_bi},
      next_{}
    { }
 
    ~sense_listener ()
    {
      disable();
    }
 
    /* You can't copy, assign, move, or otherwise muck with sense
     * listeners, since they participate in a linked list maintained
     * by the @link GPIOTE@endlink module. */
    sense_listener (const sense_listener&) = delete;
    sense_listener& operator= (const sense_listener&) = delete;
    sense_listener (const sense_listener&&) = delete;
    sense_listener& operator= (sense_listener&&) = delete;
    void enable ();
 
    void disable ();
 
    sense_callback_bi const callback_bi;
 
  protected:
    friend GPIOTE;
 
    chain_type::pointer_type next_ = chain_type::unlinked_ptr();
  };
 
  static GPIOTE* allocate ();
 
  void release ();
 
  void config_event (unsigned int psel,
                     unsigned int polarity = GPIOTE_CONFIG_POLARITY_Toggle)
  {
    nrf5::GPIOTE->CONFIG[channel] = (GPIOTE_CONFIG_MODE_Event << GPIOTE_CONFIG_MODE_Pos)
      | (GPIOTE_CONFIG_PSEL_Msk & (psel << GPIOTE_CONFIG_PSEL_Pos))
      | (GPIOTE_CONFIG_POLARITY_Msk & (polarity << GPIOTE_CONFIG_POLARITY_Pos));
  }
 
  void config_task (unsigned int psel,
                    unsigned int polarity = GPIOTE_CONFIG_POLARITY_Toggle)
  {
    nrf5::GPIOTE->CONFIG[channel] = (GPIOTE_CONFIG_MODE_Task << GPIOTE_CONFIG_MODE_Pos)
      | (GPIOTE_CONFIG_PSEL_Msk & (psel << GPIOTE_CONFIG_PSEL_Pos))
      | (GPIOTE_CONFIG_POLARITY_Msk & (polarity << GPIOTE_CONFIG_POLARITY_Pos));
  }
 
  void config_disabled ()
  {
    nrf5::GPIOTE->CONFIG[channel] = 0;
  }
 
  void enable_event ()
  {
    nrf5::GPIOTE->EVENTS_IN[channel] = 0;
    nrf5::GPIOTE->INTENSET = (GPIOTE_INTENSET_IN0_Enabled << (GPIOTE_INTENSET_IN0_Pos + channel));
  }
 
  void disable_event ()
  {
    nrf5::GPIOTE->INTENCLR = (GPIOTE_INTENCLR_IN0_Clear << (GPIOTE_INTENCLR_IN0_Pos + channel));
  }
 
  event_reference_type EVENTS_IN ();
 
  task_reference_type TASKS_OUT ();
 
#if !(NRF51 - 0)
 
  task_reference_type TASKS_SET ();
 
  task_reference_type TASKS_CLR ();
#endif /* !NRF51 */
 
  static void enable_sense ();
 
  static void disable_sense ()
  {
    nrf5::GPIOTE->INTENCLR = (GPIOTE_INTENCLR_PORT_Clear << GPIOTE_INTENCLR_PORT_Pos);
  }
 
  static void irq_handler (void);
 
private:
  /* The constructor is only invoked through the static initializer
   * for instances_. */
  constexpr GPIOTE (uint8_t channel_) :
    channel{channel_},
    listener_{}
  { }
 
  void config_disabled_bi_ ()
  {
    auto listener = listener_;
    if (listener) {
      listener->disable_bi_();
    }
  }
 
  event_listener * volatile listener_;
 
  static sense_listener::chain_type sense_chain_;
  static GPIOTE instances_[CHANNEL_COUNT];
  static registry_type in_use_;
}; // class GPIOTE
 
class PPI
{
public:
  using event_reference_type = __O uint32_t &;
 
  using task_reference_type = __IO uint32_t &;
 
  static int request ();
 
  static int release (int ppi);
 
  static int group_request ();
 
  static int group_release (int ppi);
 
  static uint32_t configure (int ppidx,
                             event_reference_type eep,
                             task_reference_type tep)
  {
    return configure_(ppidx, eep, tep);
  }
 
  static uint32_t CHENSET (uint32_t v)
  {
    return CHENSET_(v);
  }
 
  static uint32_t CHENCLR (uint32_t v)
  {
    return CHENCLR_(v);
  }
 
  static uint32_t CHEN ()
  {
    return CHEN_();
  }
 
protected:
  static uint32_t CHENSET_ (uint32_t v)
  {
    nrf5::PPI->CHENSET = v;
    return 0;
  }
 
  static uint32_t CHENCLR_ (uint32_t v)
  {
    nrf5::PPI->CHENCLR = v;
    return 0;
  }
 
  static uint32_t CHEN_ ()
  {
    return nrf5::PPI->CHEN;
  }
 
  static uint32_t configure_ (int ppidx,
                              event_reference_type eep,
                              task_reference_type tep)
  {
    nrf5::PPI->CH[ppidx].EEP = reinterpret_cast<uintptr_t>(&eep);
    nrf5::PPI->CH[ppidx].TEP = reinterpret_cast<uintptr_t>(&tep);
    return 0;
  }
};
 
class instr_psel_gpiote
{
public:
 
  instr_psel_gpiote (unsigned int psel,
                     PPI::event_reference_type eep,
                     bool enable = true) :
    gpiote_{GPIOTE::allocate()},
    eep_{eep},
    psel_(psel),
    ppi_idx_(PPI::request())
  {
    if (gpiote_ && (0 > ppi_idx_)) {
      gpiote_->release();
      gpiote_ = nullptr;
    } else if ((!gpiote_) && (0 <= ppi_idx_)) {
      PPI::release(ppi_idx_);
      ppi_idx_ = -1;
    } else if (enable) {
      this->enable();
    }
  }
 
  instr_psel_gpiote () = delete;
  instr_psel_gpiote (const instr_psel_gpiote&) = delete;
  instr_psel_gpiote& operator= (const instr_psel_gpiote&) = delete;
  instr_psel_gpiote (instr_psel_gpiote&&) = delete;
  instr_psel_gpiote& operator= (instr_psel_gpiote&&) = delete;
 
  ~instr_psel_gpiote ()
  {
    if (0 <= ppi_idx_) {
      PPI::CHENCLR(1U << ppi_idx_);
      PPI::release(ppi_idx_);
      gpiote_->release();
    }
  }
 
  operator bool () const
  {
    return gpiote_;
  }
 
  void enable ()
  {
    if (gpiote_) {
      gpiote_->config_task(psel_);
      PPI::configure(ppi_idx_, eep_, gpiote_->TASKS_OUT());
      PPI::CHENSET(1U << ppi_idx_);
    }
  }
 
  void disable ()
  {
    if (gpiote_) {
      PPI::CHENCLR(1U << ppi_idx_);
      gpiote_->config_disabled();
    }
  }
 
private:
  GPIOTE* gpiote_;
  PPI::event_reference_type eep_;
  uint16_t psel_;
  int8_t ppi_idx_;
};
 
namespace details {
 
class comm_error_support
{
public:
 
  using size_type = unsigned int;
 
  using ssize_type = int;
 
  using error_type = unsigned int;
 
  constexpr static unsigned int ERR_OVERRUN = 0x001;
 
  constexpr static unsigned int ERR_ANACK = 0x002;
 
  constexpr static unsigned int ERR_DNACK = 0x004;
 
  constexpr static unsigned int ERR_TIMEOUT = 0x100;
 
  constexpr static unsigned int ERR_CLEAR = 0x200;
 
  constexpr static unsigned int ERR_INVALID = 0x400;
 
  constexpr static unsigned int ERR_CHECKSUM = 0x800;
 
  constexpr static unsigned int ERR_UNKNOWN = 0x1000;
 
  constexpr static error_type
  error_decoded (ssize_type rc)
  {
    return (0 <= rc) ? 0 : (static_cast<unsigned int>(-rc) - 1);
  }
 
  constexpr static ssize_type
  error_encoded (error_type ec)
  {
    return ec ? -(1 + ec) : 0;
  }
};
 
template <typename PERIPH>
class scoped_enabler
{
  using ssize_type = typename PERIPH::ssize_type;
 
  scoped_enabler (const scoped_enabler&) = delete;
  scoped_enabler& operator= (const scoped_enabler&) = delete;
  scoped_enabler (scoped_enabler&&) = delete;
  scoped_enabler& operator= (scoped_enabler&&) = delete;
 
public:
  ~scoped_enabler () noexcept
  {
    if (0 < result_) {
      periph.disable();
    }
  }
 
  operator bool() const
  {
    return (0 <= result_);
  }
 
  ssize_type result () const
  {
    return result_;
  }
 
private:
  friend PERIPH;
 
  scoped_enabler (PERIPH& periph) :
    periph{periph}
  {
    if (!periph.enabled()) {
      result_ = periph.enable();
      if (0 <= result_) {
        result_ = 1;
      }
    }
  }
 
  PERIPH& periph;
  ssize_type result_ = 0;
};
 
} // ns details
 
class TWI : public details::comm_error_support
{
public:
  constexpr static unsigned int minimum_timeout_us = 100;
 
  const nrf5::TWI_Type& peripheral() const
  {
    return twi_;
  }
 
  bool enabled () const
  {
    return ((TWI_ENABLE_ENABLE_Enabled << TWI_ENABLE_ENABLE_Pos)
            == (TWI_ENABLE_ENABLE_Msk & twi_->ENABLE));
  }
 
  using scoped_enabler = details::scoped_enabler<TWI>;
 
  scoped_enabler scoped_enable () noexcept
  {
    return {*this};
  }
 
  ssize_type bus_configure (int psel_scl,
                            int psel_sda,
                            uint32_t frequency,
                            unsigned int timeout_us);
 
  ssize_type enable ()
  {
    return error_encoded(set_enabled_(true));
  }
 
  void disable ()
  {
    set_enabled_(false);
  }
 
  ssize_type read (unsigned int addr,
                   uint8_t* buf,
                   size_type count);
 
  ssize_type write (unsigned int addr,
                    const uint8_t* buf,
                    size_type count);
 
  ssize_type write_read (unsigned int addr,
                         const uint8_t* sbuf,
                         size_type scount,
                         uint8_t* dbuf,
                         size_type dcount)
  {
    int rv = 0;
    if (0 < scount) {
      rv = write(addr, sbuf, scount);
    }
    if (0 <= rv) {
      rv = read(addr, dbuf, dcount);
    }
    return rv;
  }
 
  static TWI& instance (int idx);
 
protected:
 
  constexpr TWI (const nrf5::TWI_Type& twi) :
    twi_{twi},
    configuration_{}
  { }
 
  struct configuration_type
  {
    unsigned int timeout = 0;
 
    uint32_t frequency = 0;
 
    int8_t psel_scl = -1;
 
    int8_t psel_sda = -1;
 
    int8_t ppidx = -1;
  };
 
  error_type set_enabled_ (bool enabled);
 
  error_type clear_bus_ ();
 
  error_type clear_error_ ();
 
  error_type reset_periph_ ();
 
  const nrf5::TWI_Type& twi_;
  configuration_type configuration_;
};
 
class SPI : public details::comm_error_support
{
public:
 
  using size_type = unsigned int;
 
  using ssize_type = int;
 
  const nrf5::SPI_Type& peripheral() const
  {
    return spi_;
  }
 
  bool enabled () const
  {
    return ((SPI_ENABLE_ENABLE_Enabled << SPI_ENABLE_ENABLE_Pos)
            == (SPI_ENABLE_ENABLE_Msk & spi_->ENABLE));
  }
 
  using scoped_enabler = details::scoped_enabler<SPI>;
 
  scoped_enabler scoped_enable () noexcept
  {
    return {*this};
  }
 
  ssize_type bus_configure (int psel_sck,
                            int psel_mosi,
                            int psel_miso,
                            uint32_t frequency,
                            uint32_t config);
 
  static constexpr uint32_t frequency_from_Hz (unsigned int freq_Hz)
  {
    unsigned int multiplier = 125000;
    uint32_t rv = SPI_FREQUENCY_FREQUENCY_K125;
    while (true) {
      multiplier *= 2;
      if ((multiplier > freq_Hz)
          || (SPI_FREQUENCY_FREQUENCY_M8 == rv)) {
        break;
      }
      rv <<= 1;
    }
    return rv;
  }
 
  static constexpr uint32_t config_from_mode (uint8_t mode,
                                              bool lsb_first = false)
  {
 
    return ((lsb_first?1:0) << SPI_CONFIG_ORDER_Pos)
      | ((mode & 3) << SPI_CONFIG_CPHA_Pos);
  }
 
  ssize_type enable ()
  {
    return set_enabled_(true);
  }
 
  void disable ()
  {
    set_enabled_(false);
  }
 
  ssize_type tx_rx (const uint8_t* tx_data,
                    size_type tx_len,
                    size_type rx_len,
                    uint8_t* rx_data,
                    uint8_t tx_dummy = 0);
 
  static SPI& instance (int idx);
 
protected:
 
  constexpr SPI (const nrf5::SPI_Type& spi) :
    spi_{spi},
    configuration_{}
  { }
 
  struct configuration_type
  {
    uint32_t frequency = 0;
    uint32_t config = 0;
    int8_t psel_sck = -1;
    int8_t psel_mosi = -1;
    int8_t psel_miso = -1;
    int8_t ppidx = -1;
  };
 
  error_type set_enabled_ (bool enabled);
 
  const nrf5::SPI_Type& spi_;
  configuration_type configuration_;
};
 
// Forward declaration
class ADCClient;
 
class ADC : protected nrf5::series::ADC_Variant
{
public:
  using peripheral = nrf5::series::ADC_Variant;
 
  static constexpr auto& INSTANCE{
#if (NRF51 - 0)
    nrf5::ADC
#elif (NRF52832 - 0) || (NRF52840 - 0)
    nrf5::SAADC
#endif
  };
 
  using peripheral::busy;
 
  enum class state_type : uint8_t
  {
    available,
 
    claimed,
 
    calibrating,
 
    starting,
 
    sampling,
 
    stopping,
  };
 
  static void irq_handler ();
 
  static uint8_t state ()
  {
    return static_cast<uint8_t>(state_);
  }
 
private:
  friend class ADCClient;
 
  /* Validate authorization to become owner and update state. */
  static int claim_bi_ (ADCClient* client);
 
  /* Validate then release ownership. */
  static int release_bi_ (ADCClient* client);
 
  /* Attempt to transition into calibrating state. */
  static int try_calibrate_bi_ (ADCClient* client,
                                const notifier_type& notify);
 
  /* Attempt to transition into sampling state. */
  static int try_sample_bi_ (ADCClient* client,
                             const notifier_type& notify);
 
  /* Notify application of completion of calibration or sampling.
   *
   * Operation callbacks are invoked for both sampling and
   * calibration, but ADCClient notification callbacks are only
   * invoked when sampling completes.
   *
   * @param calibrating `true` iff the operation that completed was
   * calibration.*/
  static void complete_notify_bi_ (bool calibrating);
 
  static ADCClient* volatile owner_;
 
  static notifier_type notify_callback_;
 
  static state_type volatile state_;
};
 
class ADCClient
{
public:
  using flags_type = unsigned int;
 
  using queued_callback_type = std::function<void(int rc)>;
 
protected:
  enum flags_e : flags_type
  {
    FL_QUEUED_SAMPLE = 0x0001,
 
    FL_QUEUED_CALIBRATE = 0x0002,
 
    FL_QUEUED_Msk = FL_QUEUED_SAMPLE | FL_QUEUED_CALIBRATE,
 
    FL_SUBCLASS_BASE = 0x0010,
  };
 
private:
  struct ref_next
  {
    using pointer_type = ADCClient*;
    pointer_type& operator() (ADCClient& cl) noexcept
    {
      return cl.next_;
    }
  };
 
  using queue_type = pabigot::container::forward_chain<ADCClient, ref_next>;
  static queue_type queue_;
 
  queue_type::pointer_type next_ = queue_type::unlinked_ptr();
  queued_callback_type queued_callback_{};
  notifier_type notify_callback_{};
 
public:
  using peripheral = ADC::peripheral;
 
  using mutex_type = peripheral::mutex_type;
 
  /* You can default construct ADCClient instances, but you cannot
   * copy, assign or move them, since they can be referenced by the
   * infrastructure. */
  ADCClient () = default;
  ADCClient (const ADCClient&) = delete;
  ADCClient (const ADCClient&&) = delete;
  ADCClient& operator= (const ADCClient&) = delete;
  ADCClient& operator= (ADCClient&&) = delete;
  virtual ~ADCClient ()
  {
    release();
  }
 
  int claim ()
  {
    mutex_type mutex;
    return ADC::claim_bi_(this);
  }
 
  int release ()
  {
    mutex_type mutex;
    return ADC::release_bi_(this);
  }
 
  int calibrate (const notifier_type& notify = {})
  {
    mutex_type mutex;
    return ADC::try_calibrate_bi_(this, notify);
  }
 
  virtual int sample_setup ()
  {
    return 0;
  }
 
  virtual void sample_teardown ()
  { }
 
  int sample (const notifier_type& notify = {})
  {
    mutex_type mutex;
    return sample_bi_(notify);
  }
 
  int queue (const notifier_type& notify,
             const queued_callback_type& qnotify = {},
             bool calibrate = false);
 
  int queue (bool calibrate = false)
  {
    return queue({}, {}, calibrate);
  }
 
protected:
  friend class ADC;
 
  flags_type flags_ = 0;
 
  int sample_bi_ (const notifier_type& notify)
  {
    return ADC::try_sample_bi_(this, notify);
  }
 
  static void process_queue_bi_ ();
  void complete_queue_bi_ ();
 
  virtual int configure_bi_ ()
  {
    return 0;
  }
 
  virtual void complete_bi_ ()
  { }
 
  virtual int nrf51_next_bi_ (size_t ci)
  {
    return -1;
  }
};
 
#if (NRF52840 - 0) || (NRFCXX_DOXYGEN - 0)
 
class QSPI
{
public:
  using mutex_type = mutex_irq<QSPI_IRQn>;
 
  using offset_type = unsigned int;
 
  using size_type = unsigned int;
 
  using ssize_type = int;
 
  static constexpr uint8_t SR_WIP = 0x01;
  static constexpr uint8_t SR_WEL = 0x02;
  static constexpr uint8_t SR_BP0 = 0x04;
  static constexpr uint8_t SR_BP1 = 0x08;
  static constexpr uint8_t SR_BP2 = 0x10;
  static constexpr uint8_t SR_BP3 = 0x20;
  static constexpr uint8_t SR_QE = 0x40;
  static constexpr uint8_t SR_SWRD = 0x80;
 
  static constexpr unsigned int convert_us_dpmdur (unsigned int dur_us)
  {
    return (16U * dur_us + 255U) / 256U;
  }
 
  struct configuration_type
  {
    uint32_t ifconfig[2] = {0, 0x40480};
 
    uint32_t addrconf = 0xB7;
 
    uint32_t xipoffset = 0;
 
    int8_t psel_io[4] = {-1, -1, -1, -1};
 
    int8_t psel_sck = -1;
 
    int8_t psel_csn = -1;
 
    uint8_t enter_dpmdur = 0xFFu;
 
    uint8_t exit_dpmdur = 0xFFu;
 
    bool drive_high = false;
  };
 
  /* You can't copy, assign, move, or otherwise change the set of
   * QSPI instances that the system provides to you. */
  QSPI () = delete;
  QSPI (const QSPI&) = delete;
  QSPI& operator= (const QSPI&) = delete;
  QSPI (const QSPI&&) = delete;
  QSPI& operator= (QSPI&&) = delete;
  QSPI (const configuration_type& configuration);
 
  const configuration_type& configuration () const
  {
    return configuration_;
  }
 
  uint8_t latest_sr () const
  {
    return (QSPI_STATUS_SREG_Msk & nrf5::QSPI->STATUS) >> QSPI_STATUS_SREG_Pos;
  }
 
  int read_sr () const;
 
  bool is_qspi_available () const
  {
    return (((QSPI_STATUS_READY_READY << QSPI_STATUS_READY_Pos)
             | (QSPI_STATUS_DPM_Disabled << QSPI_STATUS_DPM_Pos))
            == ((QSPI_STATUS_READY_Msk | QSPI_STATUS_DPM_Msk)
                & nrf5::QSPI->STATUS));
  }
 
  bool is_write_complete (int sr) const
  {
    bool rv = false;
    if (0 <= sr) {
      rv = (0 == ((periph::QSPI::SR_WIP | periph::QSPI::SR_WEL) & sr));
    }
    return rv;
  }
 
  bool is_powerdown () const
  {
    return (QSPI_STATUS_DPM_Msk & nrf5::QSPI->STATUS);
  }
 
  bool is_ready () const
  {
    return (QSPI_STATUS_READY_Msk & nrf5::QSPI->STATUS);
  }
 
  ssize_t read (offset_type addr,
                void* dest,
                size_type count);
 
  ssize_t write (offset_type addr,
                 const void* src,
                 size_type count);
 
  static constexpr auto ERASE_4_KB = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_4KB) << QSPI_ERASE_LEN_LEN_Pos;
 
  static constexpr auto ERASE_64_KB = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_64KB) << QSPI_ERASE_LEN_LEN_Pos;
 
  static constexpr auto ERASE_CHIP = static_cast<uint8_t>(QSPI_ERASE_LEN_LEN_All) << QSPI_ERASE_LEN_LEN_Pos;
 
  int erase (uint8_t type,
             offset_type addr = -1);
 
  unsigned int jedec_id () const
  {
    return jedec_id_;
  }
 
  static QSPI* owner ()
  {
    return owner_;
  }
 
  bool is_activated () const
  {
    return activated_;
  }
 
  bool is_owner () const
  {
    return this == owner_;
  }
 
  int claim ();
 
  int release ();
 
  int activate ();
 
  int deactivate ();
 
private:
  /* The QSPI instance that has control of the %QSPI peripheral. */
  static QSPI* owner_;
 
  const configuration_type& configuration_;
  unsigned int jedec_id_ = 0;
  bool activated_ = false;
};
 
#endif /* NRF52840 */
 
} // namespace periph
} // namespace nrfcxx
 
#endif /* NRFCXX_PERIPH_HPP */