forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
196 lines
5.5 KiB
196 lines
5.5 KiB
\input texinfo @c -*-texinfo-*- |
|
@c %**start of header |
|
@setfilename chopstx.info |
|
@set VERSION 1.14 |
|
@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 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:: Poll or Pole. |
|
* Note (Use of sleep mode):: Use it carefully. |
|
* Compile-time macro:: Macro to be defined. |
|
* API:: API. |
|
|
|
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 and GNU/Linux emulation. Specifically, it is used for |
|
STM32F030, MKL27Z, STM32F103, GD32F103 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 |
|
minimize use of threads. |
|
|
|
|
|
@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 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 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 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 |
|
|
|
|
|
@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
|
|
|