diff --git a/include/utl/com/spi.h b/include/utl/com/spi.h new file mode 100644 index 0000000..7ce0d19 --- /dev/null +++ b/include/utl/com/spi.h @@ -0,0 +1,331 @@ +/*! + * \file /utl/com/spi.h + * \brief An Abstract base class interface for the spi bus + * + * Copyright (C) 2018 Christos Choutouridis + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . + * + */ +#ifndef _utl_com_spi_h__ +#define _utl_com_spi_h__ + +#include +#include +#include + +namespace utl { + +/*! + * \ingroup Communication + * \brief Abstract base class for spi bus + */ +//!@{ + + namespace spi { + /*! + * SPI implementation bit order + */ + enum class bitOrder { + LSB_First =0x01, //!< Most significant first + MSB_First =0x80 //!< Less significant first + }; + /*! + * SPI implementation Clock Polarity + */ + enum class cpol { + LOW =0, //!< LOW + HIGH //!< HIGH + }; + /*! + * SPI implementation Clock Phase + */ + enum class cpha { + LOW =0, //!< LOW + HIGH //!< HIGH + }; + } + + /*! + * Template base class for SPI communication interface using CRTP + * This class force a common interface for SPI communication + * protocol implementations. + * \param impl_t The CRTP type (the derived/implementation class typename). + */ + template + class spi_i { + _CRTP_IMPL(impl_t); //! \brief Syntactic sugar to CRTP casting + + public: + using type = spi_i; //!< Export type as identity meta-function + + /*! + * \name Object lifetime + */ + //!@{ + protected: + spi_i () = default; //!< Allow constructor from derived only + ~spi_i () = default; //!< Allow destructor from derived only + spi_i (const type&) = delete; //!< No copies + spi_i& operator= (const spi_i&) = delete; + //!@} + + /*! + * \name Implementation requirements + * \note + * In order for the implementation to have the following as private members + * it also need to declare this class as friend + */ + //! @{ + private: + uint32_t _clock () const { return impl()._clock (); } //!< clock frequency of the bus [Hz] + void _clock (uint32_t c) { impl()._clock (c); } //!< set clock frequency of the bus [Hz] + byte_t _tx_data (byte_t b) { return impl()._tx_data (b); } //!< Transmit a byte on the bus and return the response + //! @} + + /*! + * \name Get/Set functions provided by the interface + */ + //!@{ + public: + uint32_t clock () const { return _clock (); } //!< \return clock frequency of the bus + void clock (uint32_t c) { _clock (c); } //!< \brief set clock frequency of the bus + //!@} + + /*! + * \name I/O functions provided by the interface + */ + //!@{ + public: + /*! + * Transmit a byte to spi bus and return the response + */ + byte_t tx_data (byte_t out) { + return _tx_data (out); + } + /*! + * \brief + * Transmit a number of bytes to the spi bus and read the response. + * \param out Pointer to data to send to the bus + * \param in Pointer to buffer to store the data from the bus + * \param n The number of bytes to transmit/receive + * \return The number of bytes. + */ + size_t tx_data (const byte_t *out, byte_t *in, size_t n); + /*! + * Receive a byte from spi bus while transmitting 0xFF + */ + byte_t rx_data () { + return _tx_data(0xFF); + } + /*! + * \brief + * Receive a number of bytes from the spi bus while transmitting 0xFFs. + * \param in Pointer to buffer to store the data + * \param n The number of bytes to read + * \return The number of received bytes. + */ + size_t rx_data (byte_t *in, size_t n); + //!@} + }; + + /*! + * \brief + * Transmit a number of bytes to the spi bus and read the response. + * \param out Pointer to data to send to the bus + * \param in Pointer to buffer to store the data from the bus + * \param n The number of bytes to transmit/receive + * \return The number of bytes. + */ + template + size_t spi_i<_I>::tx_data (const byte_t *out, byte_t *in, size_t n) { + for (size_t nn {n} ; nn ; --nn) + *in++ = _tx_data (*out++); + return n; + } + /*! + * \brief + * Receive a number of bytes from the spi bus while transmitting 0xFFs. + * \param in Pointer to buffer to store the data + * \param n The number of bytes to read + * \return The number of received bytes. + */ + template + size_t spi_i<_I>::rx_data (byte_t *in, size_t n) { + for (size_t nn {n} ; nn ; --nn) + *in++ = _tx_data (0xFF); + return n; + } + + /*! + * \brief + * A virtual base class implementation + * \param none + */ + template <> + class spi_i { + public: + using type = spi_i; //!< Export type as identity meta-function + + /*! + * \name Object lifetime + */ + //!@{ + protected: + spi_i () = default; //!< Allow constructor from derived only + spi_i (const type&) = delete; //!< No copies + type& operator= (const type&) = delete; + public: + virtual ~spi_i () = default; //!< Virtual default destructor + //!@} + + /*! + * \name Implementation requirements + */ + //! @{ + private: + virtual uint32_t _clock () const =0; //!< Read the clock frequency of the bus + virtual void _clock (uint32_t) =0; //!< Set the clock frequency of the bus + virtual byte_t _tx_data (byte_t) =0; //!< Transmit a byte on the bus and return the response + //! @} + + /*! + * \name Get/Set functions provided by the interface + */ + //!@{ + public: + uint32_t clock () const { return _clock (); } //!< \return clock frequency of the bus + void clock (uint32_t c) { _clock (c); } //!< \brief set clock frequency of the bus + //!@} + + /*! + * \name I/O functions provided by the interface + */ + //!@{ + public: + /*! + * Transmit a byte to spi bus and return the response + */ + byte_t tx_data (byte_t out) { + return _tx_data (out); + } + /*! + * \brief + * Transmit a number of bytes to the spi bus and read the response. + * \param out Pointer to data to send to the bus + * \param in Pointer to buffer to store the data from the bus + * \param n The number of bytes to transmit/receive + * \return The number of bytes. + */ + size_t tx_data (const byte_t *out, byte_t *in, size_t n); + /*! + * Receive a byte from spi bus while transmitting 0xFF + */ + byte_t rx_data () { + return _tx_data (0xFF); + } + /*! + * \brief + * Receive a number of bytes from the spi bus while transmitting 0xFFs. + * \param in Pointer to buffer to store the data + * \param n The number of bytes to read + * \return The number of received bytes. + */ + size_t rx_data (byte_t *in, size_t n); + //!@} + + }; + + /*! + * \brief + * Transmit a number of bytes to the spi bus and read the response. + * \param out Pointer to data to send to the bus + * \param in Pointer to buffer to store the data from the bus + * \param n The number of bytes to transmit/receive + * \return The number of bytes. + */ + size_t spi_i::tx_data (const byte_t *out, byte_t *in, size_t n) { + for (size_t nn {n} ; nn ; --nn) + *in++ = _tx_data (*out++); + return n; + } + /*! + * \brief + * Receive a number of bytes from the spi bus while transmitting 0xFFs. + * \param in Pointer to buffer to store the data + * \param n The number of bytes to read + * \return The number of received bytes. + */ + size_t spi_i::rx_data (byte_t *in, size_t n) { + for (size_t nn {n} ; nn ; --nn) + *in++ = _tx_data (0xFF); + return n; + } + + + +#if defined _utl_have_concepts + /*! + * i2c interface concept + */ + template + concept bool spi_c = requires (T t, const T ct, typename T::Sequence s) { + // Object type + requires not_::value>::value; + requires not_::value>::value; + // Methods + {ct.clock()} -> uint32_t; + {t.clock(0)} -> void; + {t.tx_data(1)} -> byte_t; + {t.rx_data()} -> byte_t; + }; +#else + namespace spi_i_details { + using std::declval; + + template using try_cclock_t= decltype (declval().clock()); + template using try_clock_t = decltype (declval<_Tp>().clock(declval())); + template using try_tx_t = decltype (declval<_Tp>().tx_data(declval())); + template using try_rx_t = decltype (declval<_Tp>().rx_data()); + + //! Primary template to catch any non SPI interface types + template + struct is_spi_ : false_ {}; + + //! template to catch a proper SPI interface type + template + struct is_spi_ < + _Tp, + void_t < + use_if_same_t , uint32_t>, + use_if_same_t , void>, + use_if_same_t , byte_t>, + use_if_same_t , byte_t> + > + > : true_ {}; + } + /*! + * Value meta-programming function for SPI interface checking + * \param _Tp Type to check + * \return True if _Tp is a spi interface + */ + template + constexpr bool spi_c = spi_i_details::is_spi_<_Tp>::value; + +#endif +//!@} + +} // namespace utl + +#endif /* #ifndef _utl_com_spi_h__ */ diff --git a/include/utl/com/spi_bb.h b/include/utl/com/spi_bb.h new file mode 100644 index 0000000..2b94793 --- /dev/null +++ b/include/utl/com/spi_bb.h @@ -0,0 +1,286 @@ +/*! + * \file utl/com/spi_bb.h + * \brief A bit banking implementation of spi bus inherited from + * spi_i base class. + * + * Copyright (C) 2018 Christos Choutouridis + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program. If not, see . + * + */ +#ifndef __utl_com_spi_bb_h__ +#define __utl_com_spi_bb_h__ + +#include +#include +#include +#include + + +namespace utl { + +/*! + * \ingroup Communication + * \brief A bit banking implementation of spi bus + * inherited from \ref spi_i base class. + * \sa spi_i + */ +//!@{ + + /*! + * \brief + * SPI bit banking interface template class using CRTP. + * Using the private interface we provide the interface from + * spi_i + * + * \param impl_t The CRTP type (the derived/implementation class typename). + * \param CPOL Clock polarity + * \param CPHA Clock phase + * \param BitOrder Data transfer bit order + */ + template + class spi_bb_i : public spi_i> { + _CRTP_IMPL(impl_t); //! \brief Syntactic sugar to CRTP casting + friend spi_i>; + public: + using type = spi_bb_i; //!< Export type as identity meta-function + + /*! + * \name Object lifetime + */ + //!@{ + protected: + ~spi_bb_i () = default; //!< A default destructor, allow destructor from derived only + //! \brief A default constructor + spi_bb_i (uint32_t clk =1000000) noexcept + : nsec_ {1000000000/(2*clk)} { + } + //!@} + + private: + //! \name SPI implementation specific functions + //!@{ + template constexpr bool clkHigh () { return !static_cast(C); } + template constexpr bool clkLow () { return static_cast(C); } + template constexpr + use_if_t <(B == spi::bitOrder::LSB_First), void> shift (byte_t& b) { b <<=1; } + template constexpr + use_if_t <(B == spi::bitOrder::MSB_First), void> shift (byte_t& b) { b >>=1; } + //!} + + /*! + * \name Implementation requirements + * \note + * In order for the implementation to have the following as private members + * it also need to declare this class as friend + */ + //!@{ + private: + void MOSI (bool st) { impl().MOSI(st); } //!< Implementers's MOSI pin function + bool MISO () { return impl().MISO(); } //!< Implementers's MISO pin function + void SCLK (bool st) { impl().SCLK (st); } //!< Implementers's SCLK pin function + void delay (uint32_t nsec) { impl().delay (nsec); } //!< Implementers's half period delay function + //!@} + + + /*! + * \name Implementation of base requirements + */ + //!@{ + private: + uint32_t _clock () const { return 1000000000/(2*nsec_); } + void _clock (uint32_t c) { nsec_ = 1000000000/(2*c); } + byte_t _tx_data (byte_t out) { return _tx_data_impl (out); } + + template + use_if_t <(C == spi::cpha::LOW), byte_t> _tx_data_impl (byte_t out); + template + use_if_t <(C == spi::cpha::HIGH), byte_t> _tx_data_impl (byte_t out); + + uint32_t nsec_; //!< half period of SPI bus + //!@} + }; + + /*! + * \brief + * _tx_data implementation for CPHA == LOW + * Out at preceding clock trailing edge, In at leading clock edge + * \param out The byte to send to SPI bus + * \return The byte read from the bus + */ + template + template + use_if_t <(C == spi::cpha::LOW), byte_t> + spi_bb_i::_tx_data_impl (byte_t out) { + byte_t in {}; + SCLK (clkLow()); + for (uint8_t bit {static_cast(BitOrder)} ; bit ; shift (bit)) { + MOSI (out & bit); // Out at preceding clock trailing edge + delay (nsec_); // Half cycle delay + SCLK (clkHigh()); // Leading edge + in |= (MISO ()) ? bit : 0; // In at leading clock edge + delay (nsec_); // Half cycle delay + SCLK (clkLow()); // Trailing edge + } + return in; + } + + /*! + * \brief + * _tx_data implementation CPHA == HIGH + * Out at leading clock edge, In at trailing clock edge + * \param out The byte to send to SPI bus + * \return The byte read from the bus + */ + template + template + use_if_t <(C == spi::cpha::HIGH), byte_t> + spi_bb_i::_tx_data_impl (byte_t out) { + byte_t in {}; + SCLK (clkLow()); + for (uint8_t bit {static_cast(BitOrder)} ; bit ; shift (bit)) { + delay (nsec_); // Half cycle delay + SCLK (clkHigh()); // Leading edge + MOSI (out & bit); // Out at leading clock edge + delay (nsec_); // Half cycle delay + SCLK (clkLow()); // Trailing edge + in |= (MISO ()) ? bit : 0; // In at trailing clock edge + } + return in; + } + + + /*! + * \brief + * A virtual base class interface specialization. + * Using the private virtual interface we provide the interface from + * spi_i + * \param impl_t = virtual_tag + * \param CPOL Clock polarity + * \param CPHA Clock phase + * \param BitOrder Data transfer bit order + */ + template + class spi_bb_i : public spi_i { + public: + using type = spi_bb_i; //!< Export type as identity meta-function + + /*! + * \name Object lifetime + */ + //!@{ + protected: + ~spi_bb_i () = default; //!< A default destructor, allow destructor from derived only + //! \brief A default constructor + spi_bb_i (uint32_t clk =1000000) noexcept + : nsec_ {1000000000/(2*clk)} { + } + //!@} + + private: + //! \name SPI implementation specific functions + //!@{ + template constexpr bool clkHigh () { return !static_cast(C); } + template constexpr bool clkLow () { return static_cast(C); } + template constexpr + use_if_t <(B == spi::bitOrder::LSB_First), void> shift (byte_t& b) { b <<=1; } + template constexpr + use_if_t <(B == spi::bitOrder::MSB_First), void> shift (byte_t& b) { b >>=1; } + //!} + + + //! \name Implementation requirements + //!@{ + private: + virtual void MOSI (bool) =0; //!< Implementers's MOSI pin function + virtual bool MISO () =0; //!< Implementers's MISO pin function + virtual void SCLK (bool) =0; //!< Implementers's SCLK pin function + virtual void delay (uint32_t) =0; //!< Implementers's half period delay function + //!@} + + + /*! + * \name Implementation of base requirements + */ + //!@{ + private: + uint32_t _clock () const final { return 1000000000/(2*nsec_); } + void _clock (uint32_t c) final { nsec_ = 1000000000/(2*c); } + byte_t _tx_data (byte_t out) final { return _tx_data_impl (out); } + + template + use_if_t <(C == spi::cpha::LOW), byte_t> _tx_data_impl (byte_t out); + template + use_if_t <(C == spi::cpha::HIGH), byte_t> _tx_data_impl (byte_t out); + + uint32_t nsec_; //!< half period of SPI bus + //!@} + }; + + /*! + * \brief + * _tx_data implementation CPHA == LOW + * Out at preceding clock trailing edge, In at leading clock edge + * \param out The byte to send to SPI bus + * \return The byte read from the bus + */ + template + template + use_if_t <(C == spi::cpha::LOW), byte_t> + spi_bb_i::_tx_data_impl (byte_t out) { + byte_t in {}; + SCLK (clkLow()); + for (uint8_t bit {static_cast(BitOrder)} ; bit ; shift (bit)) { + MOSI (out & bit); // Out at preceding clock trailing edge + delay (nsec_); // Half cycle delay + SCLK (clkHigh()); // Leading edge + in |= (MISO ()) ? bit : 0; // In at leading clock edge + delay (nsec_); // Half cycle delay + SCLK (clkLow()); // Trailing edge + } + return in; + } + + /*! + * \brief + * _tx_data implementation CPHA == HIGH + * Out at leading clock edge, In at trailing clock edge + * \param out The byte to send to SPI bus + * \return The byte read from the bus + */ + template + template + use_if_t <(C == spi::cpha::HIGH), byte_t> + spi_bb_i::_tx_data_impl (byte_t out) { + byte_t in {}; + SCLK (clkLow()); + for (uint8_t bit {static_cast(BitOrder)} ; bit ; shift (bit)) { + delay (nsec_); // Half cycle delay + SCLK (clkHigh()); // Leading edge + MOSI (out & bit); // Out at leading clock edge + delay (nsec_); // Half cycle delay + SCLK (clkLow()); // Trailing edge + in |= (MISO ()) ? bit : 0; // In at trailing clock edge + } + return in; + } + +} + +#endif //#ifndef __spi_bb_h__