doc: Add a memo.

doc/chopstx.texi

@@ -60,8 +60,8 @@ section entitled ``Copying''.
 @menu
 * Introduction::                 What is Chopstx.
 * Threads and only Threads::     Threads and only Threads.
-* Poll or Pole::                 Poll or Pole.
-* Note (Use of sleep mode)::     Use it carefully.
+* Poll or Pole::
+* Use of sleep mode::            Use it carefully.
 * Compile-time macro::           Macro to be defined.
 * API::                          API.
 * Memorandom::                   Memorandom for the implementation.
@@ -90,8 +90,8 @@ Indexes
 
 Chopstx is an RT thread library for ARM Cortex-M0, Cortex-M0plus,
 Cortex-M3, Cortex-M4 with no FPU or DSP, and GNU/Linux emulation.
-Specifically, it is used for STM32F030, MKL27Z, STM32F103, GD32F103
-and as a command on GNU/Linux.
+Specifically, it is used for STM32F030, MKL27Z, STM32F103, GD32F103,
+STM32L432 and as a command on GNU/Linux.
 
 While most RTOSes come with many features, drivers, and stacks,
 Chopstx just offers an RT thread library.
@@ -147,8 +147,8 @@ programming style, with minimum number of threads, avoiding
 complicated dependency between threads.
 
 
-@node Note (Use of sleep mode)
-@chapter Note (Use of sleep mode)
+@node Use of sleep mode
+@chapter Use of sleep mode
 
 Calling the chopstx_conf_idle function (> 0) to allow the idle thread
 going to sleep.  MCU will be in sleep mode when no threads are
@@ -180,15 +180,18 @@ Running CPU clock in MHz.  Used for chopstx_usec_wait.
 
 @include chopstx-api.texi
 
-@node Memorandom for the implementation
+@node Memorandom
 @chapter Memorandom for the implementation
 
 @menu
 * Honourable poverty::          Wabi and Sabi.
-* Better interrupt handling::   Better interrupt handling.
+* Better interrupt handling::
+* Static and deterministic when possible::
+@end menu
 
 @node Honourable poverty
 @section Honourable poverty
+
 Chopstx is an effort against many features.  It encourages doing
 harder decision earlier.
 
@@ -206,12 +209,12 @@ complexity matters.  Now, it's more difficult to manage the
 complexity.
 
 With full of resources, it became possible deferring difficult
-hardware or lower-level decisions to upper level, by supporting both
+hardware or lower-level decisions to upper layer, by supporting both
 ways, when we have a choice.  It used to be considered a good
 practice.
 
 But, eventually, as a system, it may result many knobs, full of
-options, which might difficult to manage.
+options, which might be too difficult to manage.
 
 In this situation, against existing practice, Chopstx is a challenge
 to handle all food by only two wooden sticks.  It's not fork and exec
@@ -228,7 +231,7 @@ I hope Chopstx is the one for you.
 @section Better interrupt handling
 
 In Chopstx, all interrupt handling is done by a single routine named
-chx_handle_intr.  It uses liner list search to find a thread which
+chx_handle_intr.  It uses linear list search to find a thread which
 handles the interrupt.  In the fixed vector_table, we see many of
 chx_handle_intr entries.
 
@@ -248,6 +251,20 @@ When I have an opportunity to design MCU, I don't support larger
 interrupt vector table.
 
 
+@node Static and deterministic when possible
+@section Static and deterministic when possible
+
+When an application enables features dynamically, it may invite
+non-deterministic bugs.  Typical example: the order of driver
+initialization matters, because of hidden dependency in a hardware
+implementation.  To cover all the cases, tests needed can become huge.
+
+A simple practice like following is good when it's enough: doing all
+initialization at start, then running threads to work.
+
+If possible, avoid supporting fine grain power control and/or dynamic
+clock frequency change.
+
 @c ********************************************
 
 @include gpl.texi