Update docs

ckormanyos · ckormanyos · commit 05e976ad47b7 · 2025-11-09T14:17:25.000+01:00
diff --git a/examples/chapter12_04a/chapter12_04a.vcxproj b/examples/chapter12_04a/chapter12_04a.vcxproj
@@ -391,6 +391,7 @@
   <ItemGroup>
     <None Include="build.bat" />
     <None Include="build.sh" />
+    <None Include="readme.md" />
     <None Include="src\util\STL\algorithm">
       <ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</ExcludedFromBuild>
       <ExcludedFromBuild Condition="'$(Configuration)|$(Platform)'=='Release|x64'">true</ExcludedFromBuild>
diff --git a/examples/chapter12_04a/chapter12_04a.vcxproj.filters b/examples/chapter12_04a/chapter12_04a.vcxproj.filters
@@ -82,6 +82,9 @@
     <Filter Include="src\mcal\bl602_sifive_e24_riscv">
       <UniqueIdentifier>{fb640df6-2af7-454a-9b2a-828b481ce10f}</UniqueIdentifier>
     </Filter>
+    <Filter Include="_doc">
+      <UniqueIdentifier>{761f3b28-a64f-4507-93e8-aae698775a95}</UniqueIdentifier>
+    </Filter>
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="src\mcal\mcal.cpp">
@@ -525,5 +528,8 @@
     </None>
     <None Include="build.bat" />
     <None Include="build.sh" />
+    <None Include="readme.md">
+      <Filter>_doc</Filter>
+    </None>
   </ItemGroup>
 </Project>
diff --git a/examples/chapter12_04a/readme.md b/examples/chapter12_04a/readme.md
@@ -7,170 +7,16 @@ mathematics.
 
 ## Selected Special Functions
 
-Special functions such as the gamma function, Bessel functions,
-Legendre functions, zeta-type functions and many others
-are essential in pure and applied mathematics.
-Special functions are _special_ in the sense of generally
-being considered more specialized than elementary
-transecndental functions like trigonometric functions,
-logarithmic functions, exponential functions and the like.
+The same special functions and arguments are used as in
+Example Chapter12_04. In variation 12_04a, however,
+the open-source 32-bit BL602 single-core RISC-V (SiFive E24)
+microcontroller is used.
 
-Many special functions, although they can be very difficult to calculate
-over wide parameter and argument ranges, have remarkably
-simple small-argument approximations such as a modest Taylor series.
+## Hardware Setup
 
-Cylindrical Bessel functions of complex-valued argument $z$
-and complex-valued order $\nu$,
-for instance, have a Bessel function Taylor series representation:
+In this particular example, we have simply used a commercially-available
+BL602 single-core RISC-V (SiFive E24) board placed on a breadboard
+with soldered-on pins.
 
-$$
-J_{\nu}(z)~=~\left(\frac{1}{2}z\right)^{\nu}\sum_{k=0}^{\infty}
-\frac{\left(-\frac{1}{4}z^{2}\right)^{k}}{{k!}\Gamma\left(\nu+k+1\right)}~{\text{.}}
-$$
-
-## Application Description
-
-The application benchmark task `app::benchmark::task_func()`
-calculates three individual floating-point special function
-values in small argument range. These include a cylindrical Bessel function,
-a generalized hypergeometric geometric function and a generalized
-Legendre function.
-
-The Bessel function calculation, for instance, calculates the approximate numerical value
-of
-
-$$J_{11/9}\left(\gamma\right)~{\approx}~0.1890533651853886085356717332711858771597{\ldots}$$
-
-at fixed parameter points.
-See also [WolframAlpha](https://www.wolframalpha.com/input?i=N%5BBesselJ%5B11%2F9%2C+EulerGamma%5D%2C+40%5D)
-with the input `N[BesselJ[11/9, EulerGamma], 40]`.
-
-Other fixed parameter points have been selected
-for the Legendre and hypergeometric functions as well, can be found
-in the original example code and is also shown in the snippet below.
-
-```cpp
-void app::benchmark::task_func()
-{
-  static std::uint_fast8_t app_benchmark_index;
-
-  app_benchmark_result_is_ok = true;
-
-  // Use a port pin to provide a real-time measurement.
-  app_benchmark_port_type::set_pin_high();
-
-  if(app_benchmark_index == 0U)
-  {
-    // Test the value of a Bessel function.
-    // Here is a control value from Wolfram Alpha.
-    // N[BesselJ[11/9, EulerGamma], 40]
-    // 0.1890533651853886085356717332711858771597
-
-    constexpr std::float32_t v = FLOAT32_C(11.0) / FLOAT32_C(9.0);
-
-    app_benchmark_result_bessel =
-      math::functions::cyl_bessel_j(v, math::constants::euler<std::float32_t>());
-
-    app_benchmark_result_is_ok &= is_close_fraction(FLOAT32_C(0.1890533652),
-                                                    app_benchmark_result_bessel,
-                                                    app_benchmark_tolerance);
-  }
-  else if(app_benchmark_index == 1U)
-  {
-    // Test the value of a hypergeometric function.
-    // Here is a control value from Wolfram Alpha.
-    // N[HypergeometricPFQ[3/{7, 8, 9, 10}, 7/{13, 14, 15, 16, 17}, Log[2]], 40]
-    // 1.583596313998374915091256357139915173598
-
-    constexpr std::array<std::float32_t, 4U> ap =
-    {{
-      FLOAT32_C(3.0) / FLOAT32_C( 7.0),
-      FLOAT32_C(3.0) / FLOAT32_C( 8.0),
-      FLOAT32_C(3.0) / FLOAT32_C( 9.0),
-      FLOAT32_C(3.0) / FLOAT32_C(10.0)
-    }};
-
-    constexpr std::array<std::float32_t, 5U> bq =
-    {{
-      FLOAT32_C(7.0) / FLOAT32_C(13.0),
-      FLOAT32_C(7.0) / FLOAT32_C(14.0),
-      FLOAT32_C(7.0) / FLOAT32_C(15.0),
-      FLOAT32_C(7.0) / FLOAT32_C(16.0),
-      FLOAT32_C(7.0) / FLOAT32_C(17.0)
-    }};
-
-    app_benchmark_result_hypergeometric =
-      math::functions::hypergeometric_pfq(ap.cbegin(),
-                                          ap.cend(),
-                                          bq.cbegin(),
-                                          bq.cend(),
-                                          math::constants::ln_two<std::float32_t>());
-
-    app_benchmark_result_is_ok &= is_close_fraction(FLOAT32_C(1.5835963140),
-                                                    app_benchmark_result_hypergeometric,
-                                                    app_benchmark_tolerance);
-  }
-  else if(app_benchmark_index == 2U)
-  {
-    // Test the value of a Legendre function of the first kind.
-    // Here is a control value from Wolfram Alpha.
-    // N[LegendreP[1/11, 14/19, 2/7], 40]
-    // 0.2937838815278435137954432141091105343408
-    constexpr std::float32_t v = FLOAT32_C( 1.0) / FLOAT32_C(11.0);
-    constexpr std::float32_t u = FLOAT32_C(14.0) / FLOAT32_C(19.0);
-    constexpr std::float32_t x = FLOAT32_C( 2.0) / FLOAT32_C( 7.0);
-
-    app_benchmark_result_legendre = math::functions::legendre_p(v, u, x);
-
-    app_benchmark_result_is_ok &= is_close_fraction(FLOAT32_C(0.2937838815),
-                                                    app_benchmark_result_legendre,
-                                                    app_benchmark_tolerance);
-  }
-
-  app_benchmark_port_type::set_pin_low();
-
-  ++app_benchmark_index;
-
-  if(app_benchmark_index == 3U)
-  {
-    app_benchmark_index = 0U;
-  }
-
-  if(app_benchmark_result_is_ok == false)
-  {
-    // The result of this floating-point benchmark is not OK.
-
-    // Crash the system and toggle a port to provide an indication of failure.
-    for(;;) { app_benchmark_port_type::toggle_pin(); mcal::cpu::nop(); }
-  }
-}
-```
-
-As usual, the benchmark port is toggled high prior to the
-floating-point calculation and low after the floating-point calculation.
-The three individual calculations are not calculated all at once
-in a single call of the benchmark task. Rather an index
-counting from zero to one to two selects one single special function
-calculation to be carried out per call cycle of the task.
-
-The success of the calculation uses a relative
-measure of floating-point closeness based on the ratio of
-the expected answer with the control value compared with one.
-A simple template function called `is_close_fraction()`
-is used to test floating-point closeness as a ratio.
-
-```cpp
-template<typename float_type>
-auto is_close_fraction(const float_type& left,
-                       const float_type& right,
-                       const float_type& tolerance) -> bool
-{
-  const float_type ratio = left / right;
-
-  using std::fabs;
-
-  const float_type delta = fabs(static_cast<float_type>(FLOATMAX_C(1.0)) - fabs(ratio));
-
-  return (delta < tolerance);
-}
-```
+The wiring is straightforward. The blinking LED uses an external green LED
+controlled by pin `IO3`. THe benchmark toggle pin is `IO4`.
diff --git a/examples/readme.md b/examples/readme.md
@@ -104,6 +104,10 @@ This example makes straightforward use of preemptive multitasking scheduling wit
 Example ![chapter12_04](https://github.com/ckormanyos/real-time-cpp/tree/master/examples/chapter12_04) Benchmarking Floating-Point Calculations.\
 This example performs a variety of floating-point calculations of selected special functions of pure and applied mathematics.
 
+Example ![chapter12_04a](https://github.com/ckormanyos/real-time-cpp/tree/master/examples/chapter12_04a) Benchmarking Floating-Point Calculations (32-bit variation).\
+The same special functions and arguments are used as in Example Chapter12_04. In variation 12_04a, however,
+the open-source 32-bit BL602 single-core RISC-V (SiFive E24) microcontroller is used.
+
 Example ![chapter16_08](https://github.com/ckormanyos/real-time-cpp/tree/master/examples/chapter16_08) Generating and displaying 128-bit Random Prime Numbers.\
 This advanced example uses an extended integer class to create 128-bit unsigned prime integers with primality testing performed via Miller-Rabin.
 This example also provides fascinating, intuitive, visual insight into the prime number theory of pure mathematics.
