serial.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2015-2025 Liviu Ionescu. All rights reserved.
 * Copyright (c) 2013-2014 ARM Ltd.
 *
 * Permission to use, copy, modify, and/or distribute this software
 * for any purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can
 * be obtained from https://opensource.org/licenses/mit.
 */
 
/*
 * 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>
 
// ----------------------------------------------------------------------------
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#endif
 
// ----------------------------------------------------------------------------
 
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
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
      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
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
      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
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
      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
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpadded"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wpadded"
#endif
 
    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 override;
 
      // ----------------------------------------------------------------------
 
      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 */
 
#pragma GCC diagnostic pop
 
// ----------------------------------------------------------------------------
 
#endif /* __cplusplus */
 
// ----------------------------------------------------------------------------
 
#endif /* CMSIS_PLUS_DRIVER_SERIAL_H_ */