serial.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ distribution.
 *   (https://github.com/micro-os-plus)
 * Copyright (c) 2015 Liviu Ionescu.
 * Copyright (c) 2013-2014 ARM Ltd.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom
 * the Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 */

/*
 * The code is inspired by ARM CMSIS Driver_USART.h file, v2.02,
 * and tries to remain functionally close to the CMSIS specifications.
 */

#ifndef CMSIS_PLUS_DRIVER_SERIAL_H_
#define CMSIS_PLUS_DRIVER_SERIAL_H_

// ----------------------------------------------------------------------------

#ifdef __cplusplus

#include <cmsis-plus/driver/common.h>

#include <cstdint>
#include <cstddef>

namespace os
{
  namespace driver
  {
    // ----------------------------------------------------------------------

    namespace serial
    {
      using bit_number_t = uint32_t;
      using config_t = uint32_t;
      using config_arg_t = uint32_t;
      using control_t = uint32_t;
      using control_arg_t = uint32_t;

      // ****** Serial Control Codes *****

      constexpr bit_number_t CONFIG_Pos = 0;
      constexpr config_t CONFIG_Msk (0xFFUL << CONFIG_Pos);

      // ----- Serial Control Codes: Mode -----
      constexpr config_t MODE_ASYNCHRONOUS = (0x01UL << CONFIG_Pos);

      constexpr config_t MODE_SYNCHRONOUS_MASTER = (0x02UL << CONFIG_Pos);

      constexpr config_t MODE_SYNCHRONOUS_SLAVE = (0x03UL << CONFIG_Pos);

      constexpr config_t MODE_SINGLE_WIRE = (0x04UL << CONFIG_Pos);

      constexpr config_t MODE_IRDA = (0x05UL << CONFIG_Pos);

      constexpr config_t MODE_SMART_CARD = (0x06UL << CONFIG_Pos);

      // ----- Serial Control Codes: Mode Parameters: Data Bits -----
      constexpr bit_number_t DATA_BITS_Pos = 8;
      constexpr config_t DATA_BITS_Msk = (7UL << DATA_BITS_Pos);

      constexpr config_t DATA_BITS_5 = (5UL << DATA_BITS_Pos);

      constexpr config_t DATA_BITS_6 = (6UL << DATA_BITS_Pos);

      constexpr config_t DATA_BITS_7 = (7UL << DATA_BITS_Pos);

      constexpr config_t DATA_BITS_8 = (0UL << DATA_BITS_Pos);

      constexpr config_t DATA_BITS_9 = (1UL << DATA_BITS_Pos);

      // ----- Serial Control Codes: Mode Parameters: Parity -----
      constexpr bit_number_t PARITY_Pos = 12;
      constexpr config_t PARITY_Msk = (3UL << PARITY_Pos);

      constexpr config_t PARITY_NONE = (0UL << PARITY_Pos);

      constexpr config_t PARITY_EVEN = (1UL << PARITY_Pos);

      constexpr config_t PARITY_ODD = (2UL << PARITY_Pos);

      // ----- Serial Control Codes: Mode Parameters: Stop Bits -----
      constexpr bit_number_t STOP_BITS_Pos = 14;
      constexpr config_t STOP_BITS_Msk = (3UL << STOP_BITS_Pos);

      constexpr config_t STOP_BITS_1 = (0UL << STOP_BITS_Pos);

      constexpr config_t STOP_BITS_2 = (1UL << STOP_BITS_Pos);

      constexpr config_t STOP_BITS_1_5 = (2UL << STOP_BITS_Pos);

      constexpr config_t STOP_BITS_0_5 = (3UL << STOP_BITS_Pos);

      // ----- Serial Control Codes: Mode Parameters: Flow Control -----
      constexpr bit_number_t FLOW_CONFIG_Pos = 16;
      constexpr config_t FLOW_CONTROL_Msk = (3UL << FLOW_CONFIG_Pos);

      constexpr config_t FLOW_CONTROL_NONE = (0UL << FLOW_CONFIG_Pos);

      constexpr config_t FLOW_CONTROL_RTS = (1UL << FLOW_CONFIG_Pos);

      constexpr config_t FLOW_CONTROL_CTS = (2UL << FLOW_CONFIG_Pos);

      constexpr config_t FLOW_CONTROL_RTS_CTS = (3UL << FLOW_CONFIG_Pos);

      // ----- Serial Control Codes: Mode Parameters: Clock Polarity = (Synchronous mode); -----
      constexpr bit_number_t CPOL_Pos = 18;
      constexpr config_t CPOL_Msk = (1UL << CPOL_Pos);

      constexpr config_t CPOL0 = (0UL << CPOL_Pos);

      constexpr config_t CPOL1 = (1UL << CPOL_Pos);

      // ----- Serial Control Codes: Mode Parameters: Clock Phase = (Synchronous mode); -----
      constexpr bit_number_t CPHA_Pos = 19;
      constexpr config_t CPHA_Msk = (1UL << CPHA_Pos);

      constexpr config_t CPHA0 = (0UL << CPHA_Pos);

      constexpr config_t CPHA1 = (1UL << CPHA_Pos);

      // ----- Serial Control Codes: Miscellaneous Controls  -----

      constexpr config_t DEFAULT_TX_VALUE = (0x10UL << CONFIG_Pos);

      constexpr config_t IRDA_PULSE = (0x11UL << CONFIG_Pos);

      constexpr config_t SMART_CARD_GUARD_TIME = (0x12UL << CONFIG_Pos);

      constexpr config_t SMART_CARD_CLOCK = (0x13UL << CONFIG_Pos);

      constexpr config_t SMART_CARD_NACK = (0x14UL << CONFIG_Pos);

      // --------------------------------------------------------------------
      // ----- Commands -----

      enum Control
        : control_t
          {
            //
        enable_tx = (0x15UL << CONFIG_Pos),

        enable_rx = (0x16UL << CONFIG_Pos),

        enable_break = (0x17UL << CONFIG_Pos),

        abort_send = (0x18UL << CONFIG_Pos),

        abort_receive = (0x19UL << CONFIG_Pos),

        abort_transfer = (0x1AUL << CONFIG_Pos),

        disable_tx = (0x25UL << CONFIG_Pos),

        disable_rx = (0x26UL << CONFIG_Pos),

        disable_break = (0x27UL << CONFIG_Pos)
      };

      // --------------------------------------------------------------------
      // ****** Serial specific error codes *****

      constexpr return_t ERROR_MODE = ERROR_SPECIFIC - 1;

      constexpr return_t ERROR_BAUDRATE = ERROR_SPECIFIC - 2;

      constexpr return_t ERROR_DATA_BITS = ERROR_SPECIFIC - 3;

      constexpr return_t ERROR_PARITY = ERROR_SPECIFIC - 4;

      constexpr return_t ERROR_STOP_BITS = ERROR_SPECIFIC - 5;

      constexpr return_t ERROR_FLOW_CONTROL = ERROR_SPECIFIC - 6;

      constexpr return_t ERROR_CPOL = ERROR_SPECIFIC - 7;

      constexpr return_t ERROR_CPHA = ERROR_SPECIFIC - 8;

      // ====================================================================
      // ***** Serial Status *****

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wpadded"

      class Status
      {
      public:

        bool
        is_tx_busy (void);

        bool
        is_rx_busy (void);

        bool
        is_tx_underflow (void);

        bool
        is_rx_overflow (void);

        bool
        is_rx_break (void);

        bool
        is_rx_framing_error (void);

        bool
        is_rx_parity_error (void);

        // ------------------------------------------------------------------

      public:

        // For compatibility with ARM CMSIS, these bits should be
        // exactly in this order.

        bool tx_busy :1;

        bool rx_busy :1;

        bool tx_underflow :1;

        bool rx_overflow :1;

        bool rx_break :1;

        bool rx_framing_error :1;

        bool rx_parity_error :1;
      };

#pragma GCC diagnostic pop

      // ====================================================================
      // ***** Serial Modem Control *****

      using modem_config_t = uint32_t;

      enum class Modem_control
        : modem_config_t
          {
            //

        clear_rts,

        set_rts,

        clear_dtr,

        set_dtr
      };

      // ====================================================================

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wpadded"

      class Modem_status
      {
      public:

        bool
        is_cts_active (void);

        bool
        is_dsr_active (void);

        bool
        is_dcd_active (void);

        bool
        is_ri_active (void);

        // ------------------------------------------------------------------
      public:

        // For compatibility with ARM CMSIS, these bits should be
        // exactly in this order.

        bool cts :1;

        bool dsr :1;

        bool dcd :1;

        bool ri :1;
      };

#pragma GCC diagnostic pop

      // ====================================================================
      // ****** Serial Events *****

      enum Event
        : event_t
          {
            //

        send_complete = (1UL << 0),

        receive_complete = (1UL << 1),

        transfer_complete = (1UL << 2),

        tx_complete = (1UL << 3),

        tx_underflow = (1UL << 4),

        rx_overflow = (1UL << 5),

        rx_timeout = (1UL << 6),

        rx_break = (1UL << 7),

        rx_framing_error = (1UL << 8),

        rx_parity_error = (1UL << 9),

        cts = (1UL << 10),

        dsr = (1UL << 11),

        dcd = (1UL << 12),

        ri = (1UL << 13),
      };

      // ====================================================================

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wpadded"

      class Capabilities
      {
      public:

        // For compatibility with ARM CMSIS, these bits should be
        // exactly in this order.

        bool asynchronous :1;

        bool synchronous_master :1;

        bool synchronous_slave :1;

        bool single_wire :1;

        bool irda :1;

        bool smart_card :1;

        bool smart_card_clock :1;

        bool flow_control_rts :1;

        bool flow_control_cts :1;

        bool event_tx_complete :1;

        bool event_rx_timeout :1;

        bool rts :1;

        bool cts :1;

        bool dtr :1;

        bool dsr :1;

        bool dcd :1;

        bool ri :1;

        bool event_cts :1;

        bool event_dsr :1;

        bool event_dcd :1;

        bool event_ri :1;
      };

#pragma GCC diagnostic pop

    } /* namespace serial */

    // ======================================================================

#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wpadded"

    class Serial : public Base
    {

    public:

      // --------------------------------------------------------------------

      Serial () noexcept;

      Serial (const Serial&) = delete;

      Serial (Serial&&) = delete;

      Serial&
      operator= (const Serial&) = delete;

      Serial&
      operator= (Serial&&) = delete;

      virtual
      ~Serial () noexcept;

      // --------------------------------------------------------------------

      void
      register_callback (signal_event_t cb_func,
                         const void* cb_object = nullptr) noexcept;

      // --------------------------------------------------------------------

      const serial::Capabilities&
      get_capabilities (void) noexcept;

      return_t
      send (const void* data, std::size_t num) noexcept;

      return_t
      receive (void* data, std::size_t num) noexcept;

      return_t
      transfer (const void* data_out, void* data_in, std::size_t num) noexcept;

      std::size_t
      get_tx_count (void) noexcept;

      std::size_t
      get_rx_count (void) noexcept;

      return_t
      configure (serial::config_t cfg, serial::config_arg_t arg) noexcept;

      return_t
      control (serial::control_t ctrl) noexcept;

      serial::Status&
      get_status (void) noexcept;

      return_t
      control_modem_line (serial::Modem_control ctrl) noexcept;

      serial::Modem_status&
      get_modem_status (void) noexcept;

      void
      signal_event (event_t event) noexcept;

      void
      clean (void) noexcept;

    protected:

      // ----- To be implemented by derived classes -----

      virtual const serial::Capabilities&
      do_get_capabilities (void) noexcept = 0;

      virtual return_t
      do_send (const void* data, std::size_t num) noexcept = 0;

      virtual return_t
      do_receive (void* data, std::size_t num) noexcept = 0;

      virtual return_t
      do_transfer (const void* data_out, void* data_in, std::size_t num)
          noexcept = 0;

      virtual std::size_t
      do_get_tx_count (void) noexcept = 0;

      virtual std::size_t
      do_get_rx_count (void) noexcept = 0;

      virtual return_t
      do_configure (serial::config_t cfg, serial::config_arg_t arg)
          noexcept = 0;

      virtual return_t
      do_control (serial::control_t ctrl) noexcept = 0;

      virtual serial::Status&
      do_get_status (void) noexcept = 0;

      virtual return_t
      do_control_modem_line (serial::Modem_control ctrl) noexcept = 0;

      virtual serial::Modem_status&
      do_get_modem_status (void) noexcept = 0;

    protected:

      signal_event_t cb_func_;

      const void* cb_object_;

      serial::Status status_;
      serial::Modem_status modem_status_;

    };

#pragma GCC diagnostic pop

    // ----------------------------------------------------------------------
    // ----- Definitions -----

    namespace serial
    {
      // --------------------------------------------------------------------

      inline bool
      Status::is_tx_busy (void)
      {
        return tx_busy;
      }

      inline bool
      Status::is_rx_busy (void)
      {
        return rx_busy;
      }

      inline bool
      Status::is_tx_underflow (void)
      {
        return tx_underflow;
      }

      inline bool
      Status::is_rx_overflow (void)
      {
        return rx_overflow;
      }

      inline bool
      Status::is_rx_break (void)
      {
        return rx_break;
      }

      inline bool
      Status::is_rx_framing_error (void)
      {
        return rx_framing_error;
      }

      inline bool
      Status::is_rx_parity_error (void)
      {
        return rx_parity_error;
      }

      // --------------------------------------------------------------------

      inline bool
      Modem_status::is_cts_active (void)
      {
        return cts;
      }

      inline bool
      Modem_status::is_dsr_active (void)
      {
        return dsr;
      }

      inline bool
      Modem_status::is_dcd_active (void)
      {
        return dcd;
      }

      inline bool
      Modem_status::is_ri_active (void)
      {
        return ri;
      }
    } /* namespace serial */

    // ----------------------------------------------------------------------

    inline const serial::Capabilities&
    Serial::get_capabilities (void) noexcept
    {
      return do_get_capabilities ();
    }

    inline std::size_t
    Serial::get_tx_count (void) noexcept
    {
      return do_get_tx_count ();
    }

    inline std::size_t
    Serial::get_rx_count (void) noexcept
    {
      return do_get_rx_count ();
    }

    inline return_t
    Serial::configure (serial::config_t cfg, serial::config_arg_t arg) noexcept
    {
      return do_configure (cfg, arg);
    }

    inline return_t
    Serial::control (serial::control_t ctrl) noexcept
    {
      return do_control (ctrl);
    }

    inline serial::Status&
    Serial::get_status (void) noexcept
    {
      return do_get_status ();
    }

    inline return_t
    Serial::control_modem_line (serial::Modem_control ctrl) noexcept
    {
      return do_control_modem_line (ctrl);
    }

    inline serial::Modem_status&
    Serial::get_modem_status (void) noexcept
    {
      return do_get_modem_status ();
    }

    inline void /* __attribute__((always_inline)) */
    Serial::signal_event (event_t event) noexcept
    {
      if (cb_func_ != nullptr)
        {
          // Forward event to registered callback.
          cb_func_ (cb_object_, event);
        }
    }

  } /* namespace driver */
} /* namespace os */

#endif /* __cplusplus */

// ----------------------------------------------------------------------------

#endif /* CMSIS_PLUS_DRIVER_SERIAL_H_ */