os-decls.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2016-2025 Liviu Ionescu. All rights reserved.
 *
 * 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.
 */
 
#ifndef CMSIS_PLUS_RTOS_OS_DECLS_H_
#define CMSIS_PLUS_RTOS_OS_DECLS_H_
 
// ----------------------------------------------------------------------------
 
#include <cmsis-plus/os-versions.h>
 
// Include the application specific definitions.
#if defined(OS_USE_OS_APP_CONFIG_H)
#include <cmsis-plus/os-app-config.h>
#endif
// Include the non-portable portable types, enums and constants declarations.
#include <cmsis-plus/rtos/port/os-decls.h>
 
#include <cmsis-plus/diag/trace.h>
 
// ----------------------------------------------------------------------------
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#include <cstdint>
#include <cstddef>
#include <cerrno>
#include <cstring>
 
// ----------------------------------------------------------------------------
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
#endif
 
// ----------------------------------------------------------------------------
 
namespace os
{
  namespace rtos
  {
    // ========================================================================
 
    // Forward references.
    class clock;
    class clock_rtc;
    class clock_systick;
 
    class condition_variable;
    class event_flags;
    class memory_pool;
    class message_queue;
    class mutex;
    class semaphore;
    class thread;
    class timer;
 
    // ------------------------------------------------------------------------
 
    namespace memory
    {
      template <typename T>
      class allocator_stateless_default_resource;
    } /* namespace memory */
 
    // ------------------------------------------------------------------------
 
    using result_t = uint32_t;
 
    namespace result
    {
      enum : result_t
      {
        ok = 0
 
      };
    } /* namespace result */
 
    // ------------------------------------------------------------------------
 
    namespace scheduler
    {
      using state_t = port::scheduler::state_t;
 
    } /* namespace scheduler */
 
    // ------------------------------------------------------------------------
 
    namespace statistics
    {
      using counter_t = uint64_t;
 
      using duration_t = uint64_t;
 
    } /* namespace statistics */
 
    // ------------------------------------------------------------------------
 
    namespace interrupts
    {
      using state_t = port::interrupts::state_t;
 
    } /* namespace interrupts */
 
    // ------------------------------------------------------------------------
 
    namespace flags
    {
      using mask_t = uint32_t;
 
      using mode_t = uint32_t;
 
      namespace mode
      {
        enum : mode_t
        {
          all = 1,
 
          any = 2,
 
          clear = 4
        };
      } /* namespace mode */
 
      enum : mask_t
      {
        any = 0,
 
        all = 0xFFFFFFFF
      };
 
    } /* namespace flags */
 
    // ------------------------------------------------------------------------
 
    namespace this_thread
    {
    }
 
    // ------------------------------------------------------------------------
 
    namespace internal
    {
 
      // ======================================================================
 
      class object_named
      {
      public:
        object_named ();
 
        object_named (const char* name);
 
        object_named (const object_named&) = default;
        object_named (object_named&&) = default;
        // object_named&
        // operator= (const object_named&) = default;
        // object_named&
        // operator= (object_named&&) = default;
        ~object_named () = default;
 
      public:
        const char*
        name (void) const;
 
      protected:
        const char* const name_ = "-";
 
      };
 
      // ======================================================================
 
      class object_named_system : public object_named
      {
      public:
        object_named_system ();
 
        object_named_system (const char* name);
 
        object_named_system (const object_named_system&) = default;
        object_named_system (object_named_system&&) = default;
        // object_named_system&
        // operator= (const object_named_system&) = default;
        // object_named_system&
        // operator= (object_named_system&&) = default;
        ~object_named_system () = default;
 
        static void*
        operator new (std::size_t bytes);
 
        static void*
        operator new[] (std::size_t bytes);
 
        static void*
        operator new (std::size_t bytes, void* ptr);
 
        static void*
        operator new[] (std::size_t bytes, void* ptr);
 
        static void
        operator delete (void* ptr, std::size_t bytes);
 
        static void
        operator delete[] (void* ptr, std::size_t bytes);
 
      };
 
      // ======================================================================
 
      class attributes_clocked
      {
      public:
        constexpr attributes_clocked ();
 
        attributes_clocked (const attributes_clocked&) = default;
        attributes_clocked (attributes_clocked&&) = default;
        attributes_clocked&
        operator= (const attributes_clocked&)
            = default;
        attributes_clocked&
        operator= (attributes_clocked&&)
            = default;
        ~attributes_clocked () = default;
 
        rtos::clock* clock = nullptr;
 
      protected:
      };
    } /* namespace internal */
 
    // ========================================================================
 
    class null_locker
    {
    public:
      constexpr null_locker ();
 
      null_locker (const null_locker&) = delete;
      null_locker (null_locker&&) = delete;
      null_locker&
      operator= (const null_locker&)
          = delete;
      null_locker&
      operator= (null_locker&&)
          = delete;
 
      ~null_locker ();
 
    public:
      void
      lock (void);
 
      void
      unlock (void);
 
    };
 
    // ========================================================================
  } /* namespace rtos */
} /* namespace os */
 
// ===== Inline & template implementations ====================================
 
namespace os
{
  namespace rtos
  {
    // ========================================================================
 
    inline null_locker::~null_locker ()
    {
    }
 
    inline void
    null_locker::lock (void)
    {
      // Does nothing.
    }
 
    inline void
    null_locker::unlock (void)
    {
      // Does nothing.
    }
 
    namespace internal
    {
      // ======================================================================
 
      inline const char*
      object_named::name (void) const
      {
        return name_;
      }
 
      // ======================================================================
 
      inline object_named_system::object_named_system ()
      {
      }
 
      inline object_named_system::object_named_system (const char* name)
          : object_named (name)
      {
      }
 
      // ======================================================================
 
      constexpr attributes_clocked::attributes_clocked ()
      {
      }
 
      // ======================================================================
    } /* namespace internal */
  } /* namespace rtos */
} /* namespace os */
 
// ===== Port related definitions =============================================
 
namespace os
{
  namespace rtos
  {
    namespace port
    {
      class thread;
      class timer;
      class mutex;
 
      class condition_variable;
      class semaphore;
      class memory_pool;
      class message_queue;
      class event_flags;
 
      // ======================================================================
 
      namespace clock
      {
        using duration_t = uint32_t;
 
        using timestamp_t = uint64_t;
 
        using offset_t = int64_t;
      } /* namespace clock */
 
      // ----------------------------------------------------------------------
 
      namespace interrupts
      {
 
        bool
        in_handler_mode (void);
 
        // ====================================================================
 
        class critical_section
        {
        public:
          critical_section () = delete;
 
          // Enter an IRQ critical section
          static rtos::interrupts::state_t
          enter (void);
 
          // Exit an IRQ critical section
          static void
          exit (rtos::interrupts::state_t state);
        };
 
        // ====================================================================
 
        class uncritical_section
        {
        public:
          uncritical_section () = delete;
 
          // Enter an IRQ uncritical section
          static rtos::interrupts::state_t
          enter (void);
 
          // Exit an IRQ uncritical section
          static void
          exit (rtos::interrupts::state_t state);
        };
 
      } /* namespace interrupts */
 
      // ----------------------------------------------------------------------
 
      namespace scheduler
      {
 
        void
        greeting (void);
 
        result_t
        initialize (void);
 
        [[noreturn]] void
        start (void);
 
        port::scheduler::state_t
        lock (void);
 
        port::scheduler::state_t
        unlock (void);
 
        port::scheduler::state_t
        locked (port::scheduler::state_t state);
 
        bool
        locked (void);
 
        void
        reschedule (void);
 
        stack::element_t*
        switch_stacks (stack::element_t* sp);
 
        void
        _wait_for_interrupt (void);
 
        bool
        preemptive (void);
 
        bool
        preemptive (bool);
 
      } /* namespace scheduler */
 
      // ----------------------------------------------------------------------
 
      namespace this_thread
      {
 
        void
        prepare_suspend (void);
 
        void
        yield (void);
 
      } /* namespace this_thread */
 
      // ======================================================================
 
      class context
      {
      public:
        context () = delete;
 
        // Used to avoid a complex casts below,
        // that might confuse the Eclipse formatter.
        typedef void (*func_t) (void);
 
        static void
        create (void* context, void* func, void* args);
      };
      /* class context */
 
      // ======================================================================
      class thread
      {
      public:
        thread () = delete;
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
 
        static void
        create (rtos::thread* obj);
 
        [[noreturn]]
        static void
        destroy_this (rtos::thread* obj);
 
        static void
        destroy_other (rtos::thread* obj);
 
        static void
        resume (rtos::thread* obj);
 
        // TODO: move it to port
        using priority_t = uint8_t;
 
        static priority_t
        priority (rtos::thread* obj);
 
        static result_t
        priority (rtos::thread* obj, priority_t prio);
 
        static result_t
        detach (rtos::thread* obj);
 
#endif
      };
      /* class thread */
 
      // ======================================================================
      class clock_systick
      {
      public:
        clock_systick () = delete;
 
        static void
        start (void);
 
        static result_t
        wait_for (clock::duration_t ticks);
 
        static void
        internal_interrupt_service_routine (void);
      };
 
      // ======================================================================
 
      class clock_rtc
      {
      public:
        clock_rtc () = delete;
 
        static void
        internal_interrupt_service_routine (void);
      };
 
      // ======================================================================
 
      class clock_highres
      {
      public:
        clock_highres () = delete;
 
        static void
        start (void);
 
        static uint32_t
        cycles_per_tick (void);
 
        static uint32_t
        cycles_since_tick (void);
 
        static uint32_t
        input_clock_frequency_hz (void);
      };
 
      // ======================================================================
 
    } /* namespace port */
  } /* namespace rtos */
} /* namespace os */
 
#pragma GCC diagnostic pop
 
// ----------------------------------------------------------------------------
 
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Waggregate-return"
#endif
// Must be included after the declarations
#include <cmsis-plus/rtos/internal/os-lists.h>
#pragma GCC diagnostic pop
 
// ----------------------------------------------------------------------------
 
extern "C"
{
 
  // os-c-api.h
  // int
  // os_main (int argc, char* argv[]);
 
}
 
// ----------------------------------------------------------------------------
 
#include <cmsis-plus/rtos/os-types.h>
 
// ----------------------------------------------------------------------------
 
// Required by os_assert_throw()
#include <cmsis-plus/estd/system_error>
 
#ifdef NDEBUG /* ANSI standard */
#define os_assert_err(__e, __er) \
  do \
    { \
      if (!(__e)) \
        return __er; \
    } \
  while (false)
#else
#define os_assert_err(__e, __er) assert (__e)
#endif
 
#ifdef NDEBUG /* ANSI standard */
#define os_assert_throw(__e, __er) \
  do \
    { \
      if (!(__e)) \
        os::estd::__throw_system_error (__er, #__e); \
    } \
  while (false)
#else
#define os_assert_throw(__e, __er) assert (__e)
#endif
 
#endif /* __cplusplus */
 
// ----------------------------------------------------------------------------
 
// Default definitions for various configuration macros.
// Redefine them in `<os-app-config.h>` to the actual values.
 
#if !defined(OS_INTEGER_SYSTICK_FREQUENCY_HZ)
#define OS_INTEGER_SYSTICK_FREQUENCY_HZ (1000)
#endif
 
// ----------------------------------------------------------------------------
 
#if !defined(OS_INTEGER_RTOS_MAIN_STACK_SIZE_BYTES)
#define OS_INTEGER_RTOS_MAIN_STACK_SIZE_BYTES \
  (os::rtos::port::stack::default_size_bytes)
#endif
 
#if !defined(OS_INTEGER_RTOS_IDLE_STACK_SIZE_BYTES)
#define OS_INTEGER_RTOS_IDLE_STACK_SIZE_BYTES \
  (os::rtos::port::stack::default_size_bytes)
#endif
 
#if !defined(OS_BOOL_RTOS_SCHEDULER_PREEMPTIVE)
#define OS_BOOL_RTOS_SCHEDULER_PREEMPTIVE (true)
#endif
 
#if !defined(OS_INTEGER_RTOS_REUSE_MAGIC)
#define OS_INTEGER_RTOS_REUSE_MAGIC (0xA55AAA55)
#endif
 
// ----------------------------------------------------------------------------
 
#endif /* CMSIS_PLUS_RTOS_OS_DECLS_H_ */