From 9e527b05329f37331a9106c394c5fff237259dd0 Mon Sep 17 00:00:00 2001 From: NIIBE Yutaka Date: Fri, 24 Nov 2017 13:41:22 +0900 Subject: [PATCH] Version 1.6. --- ChangeLog | 6 +++++ NEWS | 12 +++++----- README | 10 ++++----- VERSION | 2 +- doc/chopstx-api.texi | 22 +++++++++++++++++- doc/chopstx.texi | 53 +++++++++++++++++++++++++++++++++++++------- 6 files changed, 84 insertions(+), 21 deletions(-) diff --git a/ChangeLog b/ChangeLog index b9d832b..cd21bb2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2017-11-24 NIIBE Yutaka + + * VERSION: 1.6. + * doc/chopstx.texi (VERSION): 1.6. + * doc/chopstx-api.texi: Regenerated. + 2017-11-21 NIIBE Yutaka * example-fsm-55: Update using stack-def.h. diff --git a/NEWS b/NEWS index 8b33feb..686bc62 100644 --- a/NEWS +++ b/NEWS @@ -3,7 +3,7 @@ NEWS - Noteworthy changes * Major changes in Chopstx 1.6 - Released 2017-11-XX + Released 2017-11-24 ** Fix cancellation In Chopstx 1.4 and 1.5, cancellation doesn't work for real MCU. This @@ -11,11 +11,11 @@ is due to the change of chx_sched interface, introduced for GNU/Linux emulation. This bug is fixed. ** New feature: sleep mode -New function chopstx_conf_idle is added to support sleep. Use of -sleep by this feature requires careful preparation. For example, -enabling sleep, a board with no RESET pin cannot be debugged by -JTAG/SWD. Setting of DBGMCU_CR (0xE0042004) is required beforehand -(default is zero). +New function chopstx_conf_idle is added to support sleep. Note that +use of sleep by this feature requires careful preparation. For +example, enabling sleep, a board with no RESET pin cannot be debugged +by JTAG/SWD. Setting of DBGMCU_CR (0xE0042004) is required beforehand +(hardware default is zero). ** API change: chopstx_poll This is a kind of clarification. The third argument is now an array diff --git a/README b/README index 4863a7f..b4aa7e8 100644 --- a/README +++ b/README @@ -1,6 +1,6 @@ Chopstx - Threads and only Threads - Version 1.5 - 2017-10-10 + Version 1.6 + 2017-11-24 Niibe Yutaka Flying Stone Technology @@ -17,12 +17,12 @@ stacks, Chopstx just offers a simple RT thread library. With Chopstx, interrupt handling is also done by a thread. This enables coherent code for ease of maintenance. -This library is _not_ related to the hand game: +Note that this library is _not_ related to the hand game: https://en.wikipedia.org/wiki/Chopsticks_(hand_game) -Thanks to Yao Wei and Enrico Zini for giving me the opportunity -visiting the wiki page. +Thanks to Yao Wei and Enrico Zini for giving me an opportunity +visiting the wiki page above. License diff --git a/VERSION b/VERSION index 6a3342c..eaec816 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -release/1.5 +release/1.6 diff --git a/doc/chopstx-api.texi b/doc/chopstx-api.texi index 827e91a..c789c62 100644 --- a/doc/chopstx-api.texi +++ b/doc/chopstx-api.texi @@ -176,7 +176,7 @@ Returns old state which is 0 when it was enabled. @subheading chopstx_poll @anchor{chopstx_poll} -@deftypefun {int} {chopstx_poll} (uint32_t * @var{usec_p}, int @var{n}, struct chx_poll_head * [] @var{pd_array}) +@deftypefun {int} {chopstx_poll} (uint32_t * @var{usec_p}, int @var{n}, struct chx_poll_head *const [] @var{pd_array}) @var{usec_p}: Pointer to usec for timeout. Forever if NULL. @var{n}: Number of poll descriptors @@ -201,3 +201,23 @@ which starts its execution with priority of CHX_PRIO_MAIN_INIT, and let it change its priority after initialization of other threads. @end deftypefun +@subheading chx_sleep_mode +@anchor{chx_sleep_mode} +@deftypefun {extern void} {chx_sleep_mode} (int @var{enable_sleep}) +@var{enable_sleep}: Enable sleep on idle or not + +If @var{enable_sleep} is > 0, allow sleep for the idle thread. + +Behavior of @var{enable_sleep} >= 1 depends on MCU. + +For STM32F0, 1 for Sleep (CPU clock OFF only), 2 for Stop (Wakeup +by EXTI, voltage regulator on), 3 for Stop (Wakeup by EXTI, voltage +regulator low-power), 4 for Standby (Wakeup by RESET, voltage +regulator off). + +For STM32F103, 1 for normal sleep, and 2 for sleep with lower 8MHz +clock. + +Return previous value of @var{enable_sleep}. +@end deftypefun + diff --git a/doc/chopstx.texi b/doc/chopstx.texi index 762a4b0..7e6994e 100644 --- a/doc/chopstx.texi +++ b/doc/chopstx.texi @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename chopstx.info -@set VERSION 1.5 +@set VERSION 1.6 @settitle Chopstx Reference Manual @c Unify some of the indices. @syncodeindex tp fn @@ -59,7 +59,8 @@ section entitled ``Copying''. @menu * Introduction:: What is Chopstx. -* Use of sleep mode:: Use it carefully. +* Threads and only Threads:: Threads and only Threads. +* Note: Use of sleep mode:: Use it carefully. * API:: API. Appendix @@ -86,7 +87,7 @@ Indexes Chopstx is an RT thread library for ARM Cortex-M0, Cortex-M0plus, Cortex-M3 and GNU/Linux emulation. Specifically, it is used for -STM32F030, MKL27Z and STM32F103. +STM32F030, MKL27Z, STM32F103 and as a command on GNU/Linux. While most RTOSes come with many features, drivers, and stacks, Chopstx just offers a RT thread library. @@ -94,15 +95,51 @@ Chopstx just offers a RT thread library. With Chopstx, interrupt handling is also done by a thread. This enables coherent code for ease of maintenance. -@node Use of sleep mode -Calling the chopstx_conf_idle function with 1 to allow the idle thread +@node Threads and only Threads +@chapter Threads and only Threads + +Chopstx doesn't use the feature of (prioritized) nested vector +interrupt mechanism at all. All interrupts are equally handled by a +single entry of chx_handle_intr which just wakes up corresponding +thread. This is the feature of Chopstx. + +Nested vector interrupt machanism would be useful for interrupt-driven +programming style for specific application targets, or, some other +programing style like the one with spl of Unix. Some engineers +(especially, hardware side) still seem to believe that it is a good +feature to have. But from the view point of programming and +maintenance of software, this is one of the most difficult part with +little benefit, if any. + +With traditional interrupt handling, a demarcation of what should be +done by interrupt handler, bottom half, and thead is crucial for +applications' performance. And because the demarcation should be done +at an early stage of an application development, it has a tendency, +many parts are getting demanding higher priority. Amount of code for +higher priority interrupt hander is getting bigger and bigger, while +losing performance. + +On the other hand, ``Threads (and only Threads)'' programming style +gives us best flexibility and it can make an application more +predictable, deterministic and easy to maintain. + +There are some applications, like square wave generator, which are not +suited to this programming style; Another programming style can +support more performance (frequency). In general, such an example is +best suited by hardware (not software). + + +@node Note: Use of sleep mode +@chapter Note: 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 running. By setting relevant bits of system registers, MCU will be able to be into stop or stand-by mode, which is MCU dependent. -If you use this sleep feature, please consider and implement -carefully. Enabling sleep, it may result a bricked board; A board -with no RESET pin cannot be debugged by JTAG/SWD. +If you use this sleep feature, please consider and implement your +program carefully. Enabling sleep, it may result a bricked board; A +board with no RESET pin cannot be debugged by JTAG/SWD. @node API