µOS++ IIIe Reference  v6.3.15
“Perfekt ist nicht gut genug”
The third edition of µOS++, a POSIX inspired open source system, written in C++.
os-decls.h
Go to the documentation of this file.
1 /*
2  * This file is part of the µOS++ distribution.
3  * (https://github.com/micro-os-plus)
4  * Copyright (c) 2016 Liviu Ionescu.
5  *
6  * Permission is hereby granted, free of charge, to any person
7  * obtaining a copy of this software and associated documentation
8  * files (the "Software"), to deal in the Software without
9  * restriction, including without limitation the rights to use,
10  * copy, modify, merge, publish, distribute, sublicense, and/or
11  * sell copies of the Software, and to permit persons to whom
12  * the Software is furnished to do so, subject to the following
13  * conditions:
14  *
15  * The above copyright notice and this permission notice shall be
16  * included in all copies or substantial portions of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
20  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
22  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  * OTHER DEALINGS IN THE SOFTWARE.
26  */
27 
28 #ifndef CMSIS_PLUS_RTOS_OS_DECLS_H_
29 #define CMSIS_PLUS_RTOS_OS_DECLS_H_
30 
31 // ----------------------------------------------------------------------------
32 
33 #include <cmsis-plus/os-versions.h>
34 
35 // Include the application specific definitions.
36 #include <cmsis-plus/os-app-config.h>
37 // Include the non-portable portable types, enums and constants declarations.
38 #include <cmsis-plus/rtos/port/os-decls.h>
39 
40 #include <cmsis-plus/diag/trace.h>
41 
42 // ----------------------------------------------------------------------------
43 
44 #if defined(__cplusplus)
45 
46 #include <cstdint>
47 #include <cstddef>
48 #include <cerrno>
49 #include <cstring>
50 
54 namespace os
55 {
59  namespace rtos
60  {
61  // ========================================================================
62 
63  // Forward references.
64  class clock;
65  class clock_rtc;
66  class clock_systick;
67 
68  class condition_variable;
69  class event_flags;
70  class memory_pool;
71  class message_queue;
72  class mutex;
73  class semaphore;
74  class thread;
75  class timer;
76 
77  // ------------------------------------------------------------------------
78 
79  namespace memory
80  {
81  template<typename T>
83  } /* namespace memory */
84 
85  // ------------------------------------------------------------------------
86 
96  using result_t = uint32_t;
97 
160  namespace result
161  {
175  enum
176  : result_t
177  {
181  ok = 0,
182 
183  };
184  } /* namespace result */
185 
186  // ------------------------------------------------------------------------
187 
192  namespace scheduler
193  {
203 
204  } /* namespace scheduler */
205 
206  // ------------------------------------------------------------------------
207 
212  namespace statistics
213  {
217  using counter_t = uint64_t;
218 
222  using duration_t = uint64_t;
223 
224  } /* namespace statistics */
225 
226  // ------------------------------------------------------------------------
227 
232  namespace interrupts
233  {
244 
245  } /* namespace interrupts */
246 
247  // ------------------------------------------------------------------------
248 
255  namespace flags
256  {
265  using mask_t = uint32_t;
266 
275  using mode_t = uint32_t;
276 
282  namespace mode
283  {
287  enum
288  : mode_t
289  {
293  all = 1,
294 
298  any = 2,
299 
303  clear = 4
304  };
305  } /* namespace mode */
306 
310  enum
311  : mask_t
312  {
316  any = 0,
317 
321  all = 0xFFFFFFFF,
322  };
323 
324  } /* namespace flags */
325 
326  // ------------------------------------------------------------------------
327 
332  namespace this_thread
333  {
334  }
335 
336  // ------------------------------------------------------------------------
337 
341  namespace internal
342  {
343 
344  // ======================================================================
345 
351  {
352  public:
353 
362  object_named ();
363 
369  object_named (const char* name);
370 
374  object_named (const object_named&) = default;
375  object_named (object_named&&) = default;
376  object_named&
377  operator= (const object_named&) = default;
378  object_named&
379  operator= (object_named&&) = default;
387  ~object_named () = default;
388 
393  public:
394 
406  const char*
407  name (void) const;
408 
413  protected:
414 
427  const char* const name_ = "-";
428 
436  };
437 
438  // ======================================================================
439 
445  {
446  public:
447 
457 
463  object_named_system (const char* name);
464 
468  object_named_system (const object_named_system&) = default;
471  operator= (const object_named_system&) = default;
473  operator= (object_named_system&&) = default;
481  ~object_named_system () = default;
482 
498  static void*
499  operator new (std::size_t bytes);
500 
507  static void*
508  operator new[] (std::size_t bytes);
509 
516  static void*
517  operator new (std::size_t bytes, void* ptr);
518 
525  static void*
526  operator new[] (std::size_t bytes, void* ptr);
527 
536  static void
537  operator delete (void* ptr, std::size_t bytes);
538 
547  static void
548  operator delete[] (void* ptr, std::size_t bytes);
549 
554  };
555 
556  // ======================================================================
557 
563  {
564  public:
565 
576  constexpr
578 
582  attributes_clocked (const attributes_clocked&) = default;
583  attributes_clocked (attributes_clocked&&) = default;
584  attributes_clocked&
585  operator= (const attributes_clocked&) = default;
586  attributes_clocked&
587  operator= (attributes_clocked&&) = default;
595  ~attributes_clocked () = default;
596 
615  rtos::clock* clock = nullptr;
616 
621  protected:
622 
631  };
632  } /* namespace internal */
633 
634  // ========================================================================
635 
644  {
645  public:
646 
658  constexpr
659  null_locker ();
660 
665  null_locker (const null_locker&) = delete;
666  null_locker (null_locker&&) = delete;
667  null_locker&
668  operator= (const null_locker&) = delete;
669  null_locker&
670  operator= (null_locker&&) = delete;
671 
679  ~null_locker ();
680 
685  public:
686 
699  void
700  lock (void);
701 
709  void
710  unlock (void);
711 
716  };
717 
718  // ==========================================================================
719  } /* namespace rtos */
720 } /* namespace os */
721 
722 // ===== Inline & template implementations ====================================
723 
724 namespace os
725 {
726  namespace rtos
727  {
728  // ========================================================================
729 
730  inline
732  {
733  ;
734  }
735 
736  inline void
738  {
739  ; // Does nothing.
740  }
741 
742  inline void
744  {
745  ; // Does nothing.
746  }
747 
748  namespace internal
749  {
750  // ======================================================================
751 
759  inline const char*
760  object_named::name (void) const
761  {
762  return name_;
763  }
764 
765  // ======================================================================
766 
767  inline
768  object_named_system::object_named_system ()
769  {
770  ;
771  }
772 
773  inline
774  object_named_system::object_named_system (const char* name) :
775  object_named (name)
776  {
777  ;
778  }
779 
780  // ======================================================================
781 
787  constexpr
789  {
790  ;
791  }
792 
793  // ========================================================================
794  } /* namespace internal */
795  } /* namespace rtos */
796 } /* namespace os */
797 
798 // ===== Port related definitions =============================================
799 
800 namespace os
801 {
802  namespace rtos
803  {
804  namespace port
805  {
806  class thread;
807  class timer;
808  class mutex;
809 
810  class condition_variable;
811  class semaphore;
812  class memory_pool;
813  class message_queue;
814  class event_flags;
815 
816  // ======================================================================
817 
818  namespace clock
819  {
826  using duration_t = uint32_t;
827 
834  using timestamp_t = uint64_t;
835 
836  using offset_t = int64_t;
837  } /* namespace clock */
838 
839  // ----------------------------------------------------------------------
840 
841  namespace interrupts
842  {
843 
844  bool
845  in_handler_mode (void);
846 
847  // ====================================================================
848 
850  {
851  public:
852 
853  critical_section () = delete;
854 
855  // Enter an IRQ critical section
857  enter (void);
858 
859  // Exit an IRQ critical section
860  static void
862 
863  };
864 
865  // ====================================================================
866 
868  {
869  public:
870 
871  uncritical_section () = delete;
872 
873  // Enter an IRQ uncritical section
875  enter (void);
876 
877  // Exit an IRQ uncritical section
878  static void
880 
881  };
882 
883  } /* namespace interrupts */
884 
885  // ----------------------------------------------------------------------
886 
887  namespace scheduler
888  {
889 
890  void
891  greeting (void);
892 
893  result_t
894  initialize (void);
895 
896  [[noreturn]] void
897  start (void);
898 
900  lock (void);
901 
903  unlock (void);
904 
907 
908  bool
909  locked (void);
910 
911  void
912  reschedule (void);
913 
914  stack::element_t*
915  switch_stacks (stack::element_t* sp);
916 
917  void
918  _wait_for_interrupt (void);
919 
920  bool
921  preemptive (void);
922 
923  bool
924  preemptive (bool);
925 
926  } /* namespace scheduler */
927 
928  // ----------------------------------------------------------------------
929 
930  namespace this_thread
931  {
932 
933  void
934  prepare_suspend (void);
935 
936  void
937  yield (void);
938 
939  } /* namespace this_thread */
940 
941  // ====================================================================
942 
943  class context
944  {
945  public:
946 
947  context () = delete;
948 
949  // Used to avoid a complex casts below,
950  // that might confuse the Eclipse formatter.
951  typedef void
952  (*func_t) (void);
953 
954  static void
955  create (void* context, void* func, void* args);
956 
957  };
958  /* class context */
959 
960  // ======================================================================
961  class thread
962  {
963  public:
964 
965  thread () = delete;
966 
967 #if defined(OS_USE_RTOS_PORT_SCHEDULER)
968 
969  static void
970  create (rtos::thread* obj);
971 
972  [[noreturn]]
973  static void
974  destroy_this (rtos::thread* obj);
975 
976  static void
977  destroy_other (rtos::thread* obj);
978 
979  static void
980  resume (rtos::thread* obj);
981 
982  // TODO: move it to port
983  using priority_t = uint8_t;
984 
985  static priority_t
986  priority (rtos::thread* obj);
987 
988  static result_t
989  priority (rtos::thread* obj, priority_t prio);
990 
991  static result_t
992  detach (rtos::thread* obj);
993 
994 #endif
995 
996  };
997  /* class thread */
998 
999  // ======================================================================
1001  {
1002  public:
1003 
1004  clock_systick () = delete;
1005 
1006  static void
1007  start (void);
1008 
1009  static result_t
1010  wait_for (clock::duration_t ticks);
1011 
1018  static void
1019  internal_interrupt_service_routine (void);
1020 
1021  };
1022 
1023  // ======================================================================
1024 
1026  {
1027  public:
1028 
1029  clock_rtc () = delete;
1030 
1037  static void
1038  internal_interrupt_service_routine (void);
1039 
1040  };
1041 
1042  // ======================================================================
1043 
1045  {
1046  public:
1047 
1048  clock_highres () = delete;
1049 
1050  static void
1051  start (void);
1052 
1053  static uint32_t
1054  cycles_per_tick (void);
1055 
1056  static uint32_t
1057  cycles_since_tick (void);
1058 
1059  static uint32_t
1060  input_clock_frequency_hz (void);
1061  };
1062 
1063  // ========================================================================
1064 
1065  } /* namespace port */
1066  } /* namespace rtos */
1067 } /* namespace os */
1068 
1069 // ----------------------------------------------------------------------------
1070 
1071 // Must be included after the declarations
1073 
1074 // ----------------------------------------------------------------------------
1075 
1076 extern "C"
1077 {
1078 
1083  int
1084  os_main (int argc, char* argv[]);
1085 
1090 }
1091 
1092 // ----------------------------------------------------------------------------
1093 
1094 #include <cmsis-plus/rtos/os-types.h>
1095 
1096 // ----------------------------------------------------------------------------
1097 
1098 // Required by os_assert_throw()
1100 
1108 #ifdef NDEBUG /* ANSI standard */
1109 #define os_assert_err(__e, __er) \
1110  do { if (!(__e)) return __er; } while (false)
1111 #else
1112 #define os_assert_err(__e, __er) assert(__e)
1113 #endif
1114 
1123 #ifdef NDEBUG /* ANSI standard */
1124 #define os_assert_throw(__e, __er) \
1125  do { if (!(__e)) os::estd::__throw_system_error(__er, #__e); } while (false)
1126 #else
1127 #define os_assert_throw(__e, __er) assert(__e)
1128 #endif
1129 
1130 #endif /* __cplusplus */
1131 
1132 // ----------------------------------------------------------------------------
1133 
1134 // Default definitions for various configuration macros.
1135 // Redefine them in `<os-app-config.h>` to the actual values.
1136 
1137 #if !defined(OS_INTEGER_SYSTICK_FREQUENCY_HZ)
1138 #define OS_INTEGER_SYSTICK_FREQUENCY_HZ (1000)
1139 #endif
1140 
1141 // ----------------------------------------------------------------------------
1142 
1143 #if !defined(OS_INTEGER_RTOS_MAIN_STACK_SIZE_BYTES)
1144 #define OS_INTEGER_RTOS_MAIN_STACK_SIZE_BYTES (os::rtos::port::stack::default_size_bytes)
1145 #endif
1146 
1147 #if !defined(OS_INTEGER_RTOS_IDLE_STACK_SIZE_BYTES)
1148 #define OS_INTEGER_RTOS_IDLE_STACK_SIZE_BYTES (os::rtos::port::stack::default_size_bytes)
1149 #endif
1150 
1151 #if !defined(OS_BOOL_RTOS_SCHEDULER_PREEMPTIVE)
1152 #define OS_BOOL_RTOS_SCHEDULER_PREEMPTIVE (true)
1153 #endif
1154 
1155 // ----------------------------------------------------------------------------
1156 
1157 #endif /* CMSIS_PLUS_RTOS_OS_DECLS_H_ */
void yield(void)
Yield the CPU to the next ready thread.
port::scheduler::state_t unlock(void)
Unlock the scheduler.
Definition: os-sched.h:882
bool in_handler_mode(void)
Check if the CPU is in handler mode.
Definition: os-sched.h:1091
void exit(int code)
Definition: exit.c:78
port::scheduler::state_t lock(void)
Lock the scheduler.
Definition: os-sched.h:869
uint64_t timestamp_t
Type of variables holding time stamps.
Definition: os-decls.h:834
void start(void)
Start the RTOS scheduler.
Definition: os-core.cpp:186
POSIX compliant semaphore.
Definition: os-semaphore.h:53
POSIX compliant mutex.
Definition: os-mutex.h:53
Ask for flags to be cleared after read.
Definition: os-decls.h:303
Base class for attributes.
Definition: os-decls.h:562
System namespace.
void lock(void)
Pretend to lock scheduler.
Definition: os-decls.h:737
~null_locker()
Destruct the null lockable object instance.
Definition: os-decls.h:731
User single-shot or periodic timer.
Definition: os-timer.h:53
stack::element_t * switch_stacks(stack::element_t *sp)
port::interrupts::state_t state_t
Type of variables holding interrupts statu codes.
Definition: os-decls.h:243
Standard thread.
bool locked(void)
Check if the scheduler is locked.
Definition: os-sched.h:856
Base class for named system objects.
Definition: os-decls.h:444
A namespace for functions applying to the current thread.
POSIX compliant thread, using the default RTOS allocator.
Definition: os-thread.h:230
result_t initialize(void)
Initialise the RTOS scheduler.
Definition: trace.cpp:50
POSIX compliant condition variable.
Definition: os-condvar.h:51
Special mask to represent any flag.
Definition: os-decls.h:316
port::scheduler::state_t state_t
Type of variables holding scheduler state codes.
Definition: os-decls.h:202
Base class for named objects.
Definition: os-decls.h:350
Synchronised memory pool, using the default RTOS allocator.
Definition: os-mempool.h:58
Function completed; no errors or events occurred.
Definition: os-decls.h:181
void unlock(void)
Pretend to unlock the scheduler.
Definition: os-decls.h:743
Synchronised event flags.
Definition: os-evflags.h:55
clock_t clock(void)
uint64_t counter_t
Type of variables holding context switches counters.
Definition: os-decls.h:217
Generic clock.
Definition: os-clocks.h:54
thread & thread(void)
Get the current running thread.
Definition: os-thread.cpp:1543
uint32_t mask_t
Type of variables holding flags masks.
Definition: os-decls.h:265
uint32_t duration_t
Type of variables holding timer durations.
Definition: os-decls.h:826
uint32_t mode_t
Type of variables holding flags modes.
Definition: os-decls.h:275
uint32_t result_t
Type of values returned by RTOS functions.
Definition: os-decls.h:96
Null locker.
Definition: os-decls.h:643
bool preemptive(bool)
Set the scheduler preemptive mode.
Definition: os-core.cpp:226
Standard allocator based on the RTOS system default memory manager.
Definition: os-decls.h:82
constexpr attributes_clocked()
Construct a named object instance.
Definition: os-decls.h:788
int os_main(int argc, char *argv[])
Application entry point, running on the main thread context.
POSIX compliant message queue, using the default RTOS allocator.
Definition: os-mqueue.h:58
uint64_t duration_t
Type of variables holding durations in CPU cycles.
Definition: os-decls.h:222