Merge pull request #473 from ckormanyos/docs_and_comments

Update various docs and comments

examples/chapter02_02/cstdint

@@ -1,48 +1,85 @@
 ///////////////////////////////////////////////////////////////////////////////
-//  Copyright Christopher Kormanyos 2007 - 2021.
+//  Copyright Christopher Kormanyos 2007 - 2024.
 //  Distributed under the Boost Software License,
 //  Version 1.0. (See accompanying file LICENSE_1_0.txt
 //  or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
-#ifndef _CSTDINT_2010_02_23_H_
-  #define _CSTDINT_2010_02_23_H_
+#ifndef CSTDINT_2010_02_23_
+  #define CSTDINT_2010_02_23_
 
   #include <stdint.h>
 
-  // Implement some of <cstdint> for compilers that do not yet support it.
+  // Implement some C macros that belong in <stdint.h> if they are not present.
+
+  #if !defined(INT8_C)
+  #define INT8_C(x) ((int8_t) (x))
+  #endif
+  #if !defined(INT16_C)
+  #define INT16_C(x) ((int16_t) (x))
+  #endif
+  #if !defined(INT32_C)
+  #define INT32_C(x) ((int32_t) (x##L))
+  #endif
+  #if !defined(INT64_C)
+  #define INT64_C(x) ((int64_t) (x##LL))
+  #endif
+  #if !defined(INTMAX_C)
+  #define INTMAX_C(x) ((signed long long) (x##LL))
+  #endif
+
+  #if !defined(UINT8_C)
+  #define UINT8_C(x) ((uint8_t) (x##U))
+  #endif
+  #if !defined(UINT16_C)
+  #define UINT16_C(x) ((uint16_t) (x##U))
+  #endif
+  #if !defined(UINT32_C)
+  #define UINT32_C(x) ((uint32_t) (x##UL))
+  #endif
+  #if !defined(UINT64_C)
+  #define UINT64_C(x) ((uint64_t) (x##ULL))
+  #endif
+  #if !defined(UINTMAX_C)
+  #define UINTMAX_C(x) ((unsigned long long) (x##ULL))
+  #endif
+
+  // Implement the integer types having specified widths in <cstdint>
+  // for compilers that do not yet support <cstdint>.
 
   namespace std
   {
-    typedef  ::int8_t    int8_t;
-    typedef  ::int16_t   int16_t;
-    typedef  ::int32_t   int32_t;
-    typedef  ::int32_t   int32_t;
-    typedef ::uint8_t   uint8_t;
-    typedef ::uint16_t  uint16_t;
-    typedef ::uint32_t  uint32_t;
-    typedef ::uint64_t  uint64_t;
-
-    typedef  ::int_least8_t    int_least8_t;
-    typedef  ::int_least16_t   int_least16_t;
-    typedef  ::int_least32_t   int_least32_t;
-    typedef  ::int_least32_t   int_least32_t;
-    typedef ::uint_least8_t   uint_least8_t;
-    typedef ::uint_least16_t  uint_least16_t;
-    typedef ::uint_least32_t  uint_least32_t;
-    typedef ::uint_least64_t  uint_least64_t;
-
-    typedef  ::int_fast8_t    int_fast8_t;
-    typedef  ::int_fast16_t   int_fast16_t;
-    typedef  ::int_fast32_t   int_fast32_t;
-    typedef  ::int_fast32_t   int_fast32_t;
-    typedef ::uint_fast8_t   uint_fast8_t;
-    typedef ::uint_fast16_t  uint_fast16_t;
-    typedef ::uint_fast32_t  uint_fast32_t;
-    typedef ::uint_fast64_t  uint_fast64_t;
-
-    typedef  ::intmax_t   intmax_t;
-    typedef ::uintmax_t  uintmax_t;
+    using ::int8_t;
+    using ::int16_t;
+    using ::int32_t;
+    using ::int64_t;
+    using ::uint8_t;
+    using ::uint16_t;
+    using ::uint32_t;
+    using ::uint64_t;
+
+    using ::int_least8_t;
+    using ::int_least16_t;
+    using ::int_least32_t;
+    using ::int_least64_t;
+    using ::uint_least8_t;
+    using ::uint_least16_t;
+    using ::uint_least32_t;
+    using ::uint_least64_t;
+
+    using ::int_fast8_t;
+    using ::int_fast16_t;
+    using ::int_fast32_t;
+    using ::int_fast64_t;
+    using ::uint_fast8_t;
+    using ::uint_fast16_t;
+    using ::uint_fast32_t;
+    using ::uint_fast64_t;
+
+    using ::intmax_t;
+    using ::uintmax_t;
+    using ::intptr_t;
+    using ::uintptr_t;
   }
 
-#endif // _CSTDINT_2010_02_23_H_
+#endif // CSTDINT_2010_02_23_

examples/chapter02_02/led.cpp

@@ -1,5 +1,5 @@
 ///////////////////////////////////////////////////////////////////////////////
-//  Copyright Christopher Kormanyos 2007 - 2023.
+//  Copyright Christopher Kormanyos 2007 - 2024.
 //  Distributed under the Boost Software License,
 //  Version 1.0. (See accompanying file LICENSE_1_0.txt
 //  or copy at http://www.boost.org/LICENSE_1_0.txt)

examples/chapter02_02/readme.md

@@ -2,7 +2,7 @@
 ## The LED program
 
 <p align="center">
-    <a href="https://godbolt.org/z/v5f45fMqq" alt="godbolt">
+    <a href="https://godbolt.org/z/fxWzb6h6f" alt="godbolt">
         <img src="https://img.shields.io/badge/try%20it%20on-godbolt-green" /></a>
 </p>
 

examples/readme.md

@@ -6,6 +6,8 @@ Real-Time-C++ - Examples
         <img src="https://github.com/ckormanyos/real-time-cpp/actions/workflows/real-time-cpp-examples.yml/badge.svg" alt="Build Examples"></a>
     <a href="https://github.com/ckormanyos/real-time-cpp/blob/master/LICENSE_1_0.txt">
         <img src="https://img.shields.io/badge/license-BSL%201.0-blue.svg" alt="Boost Software License 1.0"></a>
+    <a href="https://godbolt.org/z/fxWzb6h6f" alt="godbolt">
+        <img src="https://img.shields.io/badge/try%20it%20on-godbolt-green" /></a>
 </p>
 
 These examples are motivated by the book
@@ -15,7 +17,6 @@ Efficient Object-Oriented
 and Template Microcontroller Programming, Fourth Edition
 (Springer, Heidelberg, 2021) ISBN 9783662629956.
 
-
 The first couple of example projects can use the ARDUINO board directly
 and non-modified. Examples from the later chapters in the book do, however,
 need additional components at times. These need to be provided independently.
@@ -122,3 +123,17 @@ over multitasking using time slices.
 
 For further informatin on the examples, see the readme notes
 in each individual example directory.
+
+## Try it at _godbolt_
+
+<p align="center">
+    <a href="https://godbolt.org/z/fxWzb6h6f" alt="godbolt">
+        <img src="https://img.shields.io/badge/try%20it%20on-godbolt-green" /></a>
+</p>
+
+Use this [short link](https://godbolt.org/z/fxWzb6h6f)
+to [godbolt](https://godbolt.org) in order to further explore this program.
+
+In the afore-mentioned link, the main source file of
+Example ![chapter02_02](https://github.com/ckormanyos/real-time-cpp/tree/master/examples/chapter02_02)
+(the LED program) is compiled with a modern `avr-gcc` compiler.

readme.md

@@ -102,7 +102,8 @@ The reference application supports the following targets:
 ## Getting Started with the Reference Application
 
 It is easiest to get started with the reference application using one of the
-supported boards, such as Arduino or RaspberryPi ZERO or BeagleBone, etc.
+supported boards, such as `avr` (ARDUINO) or `bcm2835_raspi_b`
+(RaspberryPi ZERO) or `am335x` (BeagleBoneBlack), etc.
 The reference application can be found
 in the directory [ref_app](./ref_app) and its
 subdirectories.

ref_app/src/app/benchmark/readme.md

@@ -81,16 +81,16 @@ template class.
 A typical range of performance classes is shown in the following table.
 The benchmark used is a ${\sim}100$ decimal digit AGM $\pi$ calculation.
 
-| Target      |  runtime [ms] |  relative  |
-|-------------|---------------|------------|
-| am335x      |  1.5          |    1.0     |
-| stm32f446   |  2.5          |    1.7     |
-| avr         |  470          |    370     |
+| Target      |  runtime $[ms]$ |  relative  |
+|-------------|-----------------|------------|
+| `am335x`    |  1.5            |    1.0     |
+| `stm32f446` |  5.1            |    3.4     |
+| `avr`       |  420            |    280     |
 
 There are strikingly differing performance classes
-for the $8$-bit MICROCHIP(R) AVR controller of the Arduino
+for the $8$-bit MICROCHIP(R) AVR controller of the ARDUINO
 and the $32$-bit ARM(R) 8 controller
 of the BeagleBone Black Edition, Rev. C.
 The $\pi$ calculation requires approximately
-$470~\text{ms}$ and $1.5~\text{ms}$,
+$420~\text{ms}$ and $1.5~\text{ms}$,
 respectively, on these two microcontroller systems.

ref_app/src/mcal/nxp_imxrt1062/mcal_port.h

@@ -13,7 +13,7 @@
   // NOTE: The following table reproduces the layout information of Teensy 4.0.
   // See also: https://github.com/KurtE/TeensyDocuments
   // 
-  // Teensy-Pin  "Arduino"-Pin    Name       GPIO
+  // Teensy-Pin  "ARDUINO"-Pin    Name       GPIO
   //  1                          AD_B0_02    1.02
   //  0                          AD_B0_03    1.03
   // 24           A10            AD_B0_12    1.12

ref_app/src/util/STL/cstdint

@@ -1,5 +1,5 @@
 ///////////////////////////////////////////////////////////////////////////////
-//  Copyright Christopher Kormanyos 2007 - 2013.
+//  Copyright Christopher Kormanyos 2007 - 2024.
 //  Distributed under the Boost Software License,
 //  Version 1.0. (See accompanying file LICENSE_1_0.txt
 //  or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -49,35 +49,36 @@
 
   namespace std
   {
-    using  ::int8_t;
-    using  ::int16_t;
-    using  ::int32_t;
-    using  ::int64_t;
+    using ::int8_t;
+    using ::int16_t;
+    using ::int32_t;
+    using ::int64_t;
     using ::uint8_t;
     using ::uint16_t;
     using ::uint32_t;
     using ::uint64_t;
 
-    using  ::int_least8_t;
-    using  ::int_least16_t;
-    using  ::int_least32_t;
-    using  ::int_least64_t;
+    using ::int_least8_t;
+    using ::int_least16_t;
+    using ::int_least32_t;
+    using ::int_least64_t;
     using ::uint_least8_t;
     using ::uint_least16_t;
     using ::uint_least32_t;
     using ::uint_least64_t;
 
-    using  ::int_fast8_t;
-    using  ::int_fast16_t;
-    using  ::int_fast32_t;
-    using  ::int_fast64_t;
+    using ::int_fast8_t;
+    using ::int_fast16_t;
+    using ::int_fast32_t;
+    using ::int_fast64_t;
     using ::uint_fast8_t;
     using ::uint_fast16_t;
     using ::uint_fast32_t;
     using ::uint_fast64_t;
 
-    using  ::intmax_t;
+    using ::intmax_t;
     using ::uintmax_t;
+    using ::intptr_t;
     using ::uintptr_t;
   }
 

ref_app/target/build/build.bat

@@ -1,5 +1,5 @@
 @rem
-@rem  Copyright Christopher Kormanyos 2007 - 2023.
+@rem  Copyright Christopher Kormanyos 2007 - 2024.
 @rem  Distributed under the Boost Software License,
 @rem  Version 1.0. (See accompanying file LICENSE_1_0.txt
 @rem  or copy at http://www.boost.org/LICENSE_1_0.txt)
@@ -11,7 +11,7 @@
 @rem
 @rem %1: target
 @rem       am335x           : BeagleBone with TI(R) AM3359, creates a bare-metal binary file "MLO"
-@rem       avr              : ATMEL(R) AVR(R) ATmega328P i.e., Arduino compatible
+@rem       avr              : ATMEL(R) AVR(R) ATmega328P i.e., ARDUINO compatible
 @rem       bcm2835_raspi_b  : RaspberryPi Zero, creates a bare-metal binary file "kernel.img"
 @rem       rl78             : Renesas(R) RL78
 @rem       rx63n            : Renesas(R) RX600