283 lines
8.6 KiB
Plaintext
283 lines
8.6 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename chopstx.info
|
|
@set VERSION 1.15
|
|
@settitle Chopstx Reference Manual
|
|
@c Unify some of the indices.
|
|
@syncodeindex tp fn
|
|
@syncodeindex pg fn
|
|
@c %**end of header
|
|
@copying
|
|
This manual is for Chopstx (version @value{VERSION}).
|
|
|
|
@noindent
|
|
Copyright @copyright{} 2013, 2015, 2016, 2017, 2018, 2019 Flying Stone Technology @*
|
|
|
|
@quotation
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU General Public License as published by the
|
|
Free Software Foundation; either version 3 of the License, or (at your
|
|
option) any later version. The text of the license can be found in the
|
|
section entitled ``Copying''.
|
|
@end quotation
|
|
@end copying
|
|
|
|
|
|
@c ********************************************
|
|
|
|
@dircategory Development
|
|
@direntry
|
|
* chopstx: (chopstx). Chopstx, the thread library for embedded system.
|
|
@end direntry
|
|
|
|
@c
|
|
@c Titlepage
|
|
@c
|
|
@setchapternewpage odd
|
|
@titlepage
|
|
@title Chopstx Reference Manual
|
|
@subtitle Version @value{VERSION}
|
|
@author NIIBE Yutaka (@email{gniibe@@fsij.org})
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
|
|
@ifnothtml
|
|
@summarycontents
|
|
@contents
|
|
@page
|
|
@end ifnothtml
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Chopstx, The Thread Library
|
|
@insertcopying
|
|
@end ifnottex
|
|
|
|
|
|
@menu
|
|
* Introduction:: What is Chopstx.
|
|
* Threads and only Threads:: Threads and only Threads.
|
|
* Poll or Pole::
|
|
* Use of sleep mode:: Use it carefully.
|
|
* Compile-time macro:: Macro to be defined.
|
|
* API:: API.
|
|
* Memorandom:: Memorandom for the implementation.
|
|
|
|
Appendix
|
|
|
|
* Copying:: The GNU General Public License says how you
|
|
can copy and share the program.
|
|
|
|
Indexes
|
|
|
|
* Concept Index:: Index of concepts and programs.
|
|
* Function and Data Index:: Index of functions, variables and data types.
|
|
|
|
@end menu
|
|
|
|
@ifhtml
|
|
@page
|
|
@summarycontents
|
|
@contents
|
|
@end ifhtml
|
|
|
|
@c ********************************************
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
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,
|
|
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.
|
|
|
|
With Chopstx, interrupt handling is also done by a thread. This
|
|
enables coherent code for ease of maintenance.
|
|
|
|
While threads are important, we don't need more threads than
|
|
necessary. Chopstx provides a feature of poll, so that we can
|
|
handle multiple events by a single 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 a 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 Poll or Pole
|
|
@chapter Poll or Pole
|
|
Chopstx provides the @code{chopstx_poll} function to wait on multiple events.
|
|
|
|
Using @code{chopstx_poll}, we can write an application by event-driven
|
|
programming style, with minimum number of threads, avoiding
|
|
complicated dependency between threads.
|
|
|
|
|
|
@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
|
|
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 your
|
|
program carefully. Enabling sleep, it may result a bricked board; A
|
|
board with no RESET pin cannot be debugged by JTAG/SWD.
|
|
|
|
|
|
@node Compile-time macro
|
|
@chapter Compile-time macro
|
|
|
|
Compiling Chopstx, a macro MHZ should be supplied.
|
|
|
|
For example, when using the makefile rule of chopstx/rules.mk, please
|
|
define the make variable DEFS with -DMHZ=72 before inclusion of the rule file.
|
|
|
|
@subheading MHZ
|
|
@anchor{MHZ}
|
|
@defmac {MHZ}
|
|
Running CPU clock in MHz. Used for chopstx_usec_wait.
|
|
@end defmac
|
|
|
|
|
|
@node API
|
|
@chapter API
|
|
|
|
@include chopstx-api.texi
|
|
|
|
@node Memorandom
|
|
@chapter Memorandom for the implementation
|
|
|
|
@menu
|
|
* Honourable poverty:: Wabi and Sabi.
|
|
* 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 (because of less features).
|
|
|
|
Along with Moore's law, MCU implementations and their software are
|
|
getting more complex. It's been getting more flexibile, versatile,
|
|
and powerful.
|
|
|
|
Here is a question: the bigger is the better?
|
|
|
|
Historically, it used to be ``Yes, and it's even cheaper!''. And, for
|
|
a while, this trend continues.
|
|
|
|
However, in my opinion, it has been arrived to the point where
|
|
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 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 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
|
|
nor forks and knives.
|
|
|
|
In Japan, it is common among families, to have private chopsticks for
|
|
each individual at home. It's like: these chopsticks are father's,
|
|
these chopsticks are mother's... son's and daughter's.
|
|
|
|
I hope Chopstx is the one for you.
|
|
|
|
|
|
@node Better interrupt handling
|
|
@section Better interrupt handling
|
|
|
|
In Chopstx, all interrupt handling is done by a single routine named
|
|
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.
|
|
|
|
Obviously, this is suboptimal. It kills the hardware effort to
|
|
decrease interrupt latency.
|
|
|
|
I is certainly possible to support configurable vector table and/or
|
|
better dispatch.
|
|
|
|
The reason why I keep this badness is that I believe that when
|
|
interrupt latency matters (to the level of supporting larger vector
|
|
table, despite only few cycles elimination), something is going wrong.
|
|
You should have better solution or work around, instead of eliminating
|
|
few cycles in an interrupt handler.
|
|
|
|
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, it's better to avoid supporting fine grain power control
|
|
and/or dynamic clock frequency change.
|
|
|
|
@c ********************************************
|
|
|
|
@include gpl.texi
|
|
|
|
@node Concept Index
|
|
@unnumbered Concept Index
|
|
|
|
@printindex cp
|
|
|
|
@node Function and Data Index
|
|
@unnumbered Function and Data Index
|
|
|
|
@printindex fn
|
|
|
|
@bye
|