\input texinfo                      @c -*-texinfo-*-
@c %**start of header
@setfilename chopstx.info
@set VERSION 1.17
@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