diff --git a/docs/Doxyfile b/docs/Doxyfile index 8877df0fb..a3d8f860b 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -18,7 +18,7 @@ FULL_PATH_NAMES = NO STRIP_FROM_PATH = "C:/Documents and Settings/Administrator/" STRIP_FROM_INC_PATH = SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES +JAVADOC_AUTOBRIEF = NO QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO INHERIT_DOCS = NO @@ -84,7 +84,7 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../src/lib ../ports/ARM7 ../ports/ARM7-AT91SAM7X/port.dox ../ports/ARM7-LPC214x/port.dox ../ports/ARMCM3 ../ports/ARMCM3-STM32F103/port.dox ../ports/MSP430 ../ports/AVR +INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../docs/src ../src/lib ../ports/ARM7 ../ports/ARM7-AT91SAM7X/port.dox ../ports/ARM7-LPC214x/port.dox ../ports/ARMCM3 ../ports/ARMCM3-STM32F103/port.dox ../ports/MSP430 ../ports/AVR INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py *.ddf RECURSIVE = YES diff --git a/docs/ch.txt b/docs/ch.txt index e31bd932d..5048cf5f6 100644 --- a/docs/ch.txt +++ b/docs/ch.txt @@ -7,59 +7,57 @@ * means small Real Time Operating System. * Source Wikipedia. * @section ch_features Features - * + * MinGW demo available. + * - Preemptive scheduling. + * - 128 priority levels. + * - Multiple threads at the same priority level allowed. + * - Round robin scheduling for threads at the same priority level. + * - Unlimited number of threads. + * - Unlimited number of virtual timers. + * - Unlimited number of semaphores. + * - Unlimited number of mutexes. + * - Unlimited number of condvars. + * - Unlimited number of event sources. + * - Unlimited number of messages in queue. + * - Unlimited number of I/O queues. + * - No static setup at compile time, there is no need to configure a maximum + * number of all the above resources. + * - No *need* for a memory allocator, all the kernel structures are static + * and declaratively allocated. + * - Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at + * runtime. + * - Optional, thread safe, Heap Allocator subsystem. + * - Optional, thread safe, Memory Pools Allocator subsystem. + * - Blocking and non blocking I/O channels with timeout and events generation + * capability. + * - Minimal system requirements: about 8KiB ROM with all options enabled and + * speed optimizations on. The size can shrink under 2KiB by disabling the + * the unused subsystems and optimizing for size. + * - Small memory footprint, unused subsystems can be excluded by the + * memory image. + * - Almost totally written in C with little ASM code required for ports. * - * ChibiOS/RT architecture:

- * @subpage Concepts + * Related pages: + * - @subpage Concepts + * - @subpage Articles */ /** * @page Concepts Concepts * @{ + * @brief ChibiOS/RT Concepts and Architecture * @section naming Naming Conventions * ChibiOS/RT APIs are all named following this convention: * @a ch\\\(). @@ -236,6 +234,16 @@ */ /** @} */ +/** + * @page Articles Articles + * @{ + * @brief ChibiOS/RT Articles and Code Examples + * + * - @subpage article_atomic + * - @subpage article_saveram + */ +/** @} */ + /** * @defgroup Ports Ports * @{ @@ -351,7 +359,7 @@ * @defgroup Heap Heap * @{ * Heap Allocator related APIs. - * Operation mode

+ *

Operation mode

* The heap allocator implements a first-fit strategy and its APIs are * functionally equivalent to the usual @p malloc() and @p free(). The main * difference is that the heap APIs are thread safe.
@@ -369,7 +377,7 @@ * @defgroup MemoryPools Memory Pools * @{ * Memory Pools related APIs. - * Operation mode

+ *

Operation mode

* The Memory Pools APIs allow to allocate/free fixed size objects in * constant time and reliably without memory fragmentation problems.
* In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be @@ -383,21 +391,16 @@ * @defgroup Semaphores Semaphores * @{ * Semaphores and threads synchronization. - * Operation mode

+ *

Operation mode

* A semaphore is a threads synchronization object, some operations - * are defined on semaphores:
- *
    - *
  • Signal: The semaphore counter is increased and if the result - * is non-positive then a waiting thread is removed from the semaphore - * queue and made ready for execution. - *
    • - *
  • Wait: The semaphore counter is decreased and if the result - * becomes negative the thread is queued in the semaphore and suspended. - *
    • - *
  • Reset: The semaphore counter is reset to a non-negative value - * and all the threads in the queue are released. - *
    • - *
+ * are defined on semaphores: + * - Signal: The semaphore counter is increased and if the result + * is non-positive then a waiting thread is removed from the semaphore + * queue and made ready for execution. + * - Wait: The semaphore counter is decreased and if the result + * becomes negative the thread is queued in the semaphore and suspended. + * - Reset: The semaphore counter is reset to a non-negative value + * and all the threads in the queue are released. * Semaphores can be used as guards for mutual exclusion code zones but * also have other uses, queues guards and counters as example.
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES @@ -411,30 +414,26 @@ * @defgroup Mutexes Mutexes * @{ * Mutexes and threads synchronization. - * Operation mode

+ *

Operation mode

* A mutex is a threads synchronization object, some operations are defined - * on mutexes:
- *
    - *
  • Lock: The mutex is checked, if the mutex is not owned by some - * other thread then it is locked else the current thread is queued on the - * mutex in a list ordered by priority. - *
    • - *
  • Unlock: The mutex is released by the owner and the highest - * priority thread waiting in the queue, if any, is resumed and made owner - * of the mutex. - *
    • - *
+ * on mutexes: + * - Lock: The mutex is checked, if the mutex is not owned by some + * other thread then it is locked else the current thread is queued on the + * mutex in a list ordered by priority. + * - Unlock: The mutex is released by the owner and the highest + * priority thread waiting in the queue, if any, is resumed and made owner + * of the mutex. * In order to use the Event APIs the @p CH_USE_MUTEXES option must be * specified in @p chconf.h.
* - * Constraints

+ *

Constraints

* In ChibiOS/RT the Unlock operations are always performed in Lock-reverse * order. The Unlock API does not even have a parameter, the mutex to unlock * is taken from an internal stack of owned mutexes. * This both improves the performance and is required by the priority * inheritance mechanism. * - * The priority inversion problem

+ *

The priority inversion problem

* The mutexes in ChibiOS/RT implements the full priority * inheritance mechanism in order handle the priority inversion problem.
* When a thread is queued on a mutex, any thread, directly or indirectly, @@ -451,7 +450,7 @@ * @defgroup CondVars Conditional Variables * @{ * Conditional Variables and threads synchronization. - * Operation mode

+ *

Operation mode

* The condition variable is a synchronization object meant to be used inside * a zone protected by a @p Mutex. Mutexes and CondVars together can implement * a Monitor construct.
@@ -465,8 +464,8 @@ /** * @defgroup Events Events * @{ - * Event Sources and Event Listeners.
- * Operation mode

+ * Event Sources and Event Listeners. + *

Operation mode

* An Event Source is a special object that can be signaled by a thread or * an interrupt service routine. Signaling an Event Source has the effect * that all the threads registered on the Event Source will receive @@ -488,8 +487,8 @@ /** * @defgroup Messages Messages * @{ - * Synchronous Messages.
- * Operation Mode

+ * Synchronous inter-thread Messages. + *

Operation Mode

* Messages are an easy to use and fast IPC mechanism, threads can both serve * messages and send messages to other threads, the mechanism allows data to * be carryed in both directions. Data is not copyed between the client and @@ -517,19 +516,17 @@ * routine) and an upper side (upper driver, accessed by the application * threads).
* There are several kind of queues:
- *
    - *
  • Input queue, unidirectional queue where the writer is the - * lower side and the reader is the upper side.
    • - *
  • Output queue, unidirectional queue where the writer is the - * upper side and the reader is the lower side.
    • - *
  • Half duplex queue, bidirectional queue where the buffer is shared - * between a receive and a transmit queues. This means that concurrent - * buffered input and output operations are not possible, this is perfectly - * acceptable for a lot of applications however, as example an RS485 driver. - *
  • Full duplex queue, bidirectional queue where read and write - * operations can happen at the same time. Full duplex queues - * are implemented by pairing an input queue and an output queue together. - *
+ * - Input queue, unidirectional queue where the writer is the + * lower side and the reader is the upper side. + * - Output queue, unidirectional queue where the writer is the + * upper side and the reader is the lower side. + * - Half duplex queue, bidirectional queue where the buffer is shared + * between a receive and a transmit queues. This means that concurrent + * buffered input and output operations are not possible, this is perfectly + * acceptable for a lot of applications however, as example an RS485 driver. + * - Full duplex queue, bidirectional queue where read and write + * operations can happen at the same time. Full duplex queues + * are implemented by pairing an input queue and an output queue together. * In order to use the I/O queues the @p CH_USE_QUEUES option must * be specified in @p chconf.h.
* In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX diff --git a/docs/src/atomic.dox b/docs/src/atomic.dox new file mode 100644 index 000000000..0f678448b --- /dev/null +++ b/docs/src/atomic.dox @@ -0,0 +1,50 @@ +/** + * @page article_atomic Invoking multiple primitives as a single atomic operation + * @{ + * It is often necessary to invoke multiple operations involving a + * reschedulation as a single atomic operation.
+ * ChibiOS/RT already implements APIs that perform complex operations, as + * example the API @p chSemSignalWait() performs two operations atomically.
+ * If more complex operations are required in your application then it is + * possible to build macro-operations, see the following example: + * @code + chSysLock(); + + chSemSignalI(&sem1); + chSemSignalI(&sem2); + if (tp != NULL) { + chThdResumeI(tp); + tp = NULL; + } + chSchRescheduleS(); + + chSysUnlock(); + * @endcode + * The above example performs a signal operation on two semaphores, optionally + * resumes a thread, and performs a final reschedulation. The three operations + * are performed atomically.
+ * An hypotetical @p chSemSignalSignalWait() operation could be implemented as + * follow: + * @code + chSysLock(); + + chSemSignalI(&sem1); + chSemSignalI(&sem2); + /* + * The "if" is required because the chSemWaitS() does not always internally + * reschedule. + */ + if (chSemGetCounter(&sem3) <= 0) + chSemWaitS(&Sem3); + else { + chSemFastWaitS(&sem3); + chSchRescheduleS(); + } + + chSysUnlock(); + * @endcode + * In general multiple I-Class APIs can be included and the block is terminated + * by an S-Class API that performs a reschedulation. Optionally a + * @p chSchRescheduleS() is present at the very end of the block. + */ +/** @} */ diff --git a/docs/src/saveram.dox b/docs/src/saveram.dox new file mode 100644 index 000000000..fec810c81 --- /dev/null +++ b/docs/src/saveram.dox @@ -0,0 +1,66 @@ +/** + * @page article_saveram Saving RAM by declaring thread functions "noreturn" + * @{ + * One of the problems, when writing embedded multi-threaded applications, + * is that the thread functions do save the registers in the function + * entry code even if the system does not require it, exiting such + * a function would terminate the thread so there is no need to preserve + * the register values. This can waste tens of bytes for each thread.
+ * Consider the following code: + * @code +#include + +static WORKING_AREA(waMyThread, 64); + +static t_msg MyThread(void *arg) { + + while (!chThdShoudTerminate()) { + /* Do thread inner work */ + } + return 1; +} + +main() { + chSysInit(); + ... + chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), MyThread, NULL); + ... + chSysPause(); +} + * @endcode + * The resulting ASM code for the thread function would be something like this: + * @code +MyThread: + stmfd sp!, {r4, r5, r6, lr} + ... + ldmfd sp!, {r4, r5, r6, pc} + * @endcode + * Being that function a thread there is no need to save those registers, in + * embedded applications often the RAM is a scarce resource. That space can be + * saved by modifying the code as follow, using some advanced GCC extensions: + * @code +#include + +static BYTE8 waMyThread[UserStackSize(64)]; + +__attribute__((noreturn)) void MyThread(void *arg) { + + while (!chThdShoudTerminate()) { + /* Do thread inner work */ + } + chThdExit(1); +} + +main() { + chSysInit(); + ... + chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), (t_tfunc)MyThread, NULL); + ... + chSysPause(); +} + * @endcode + * This will make GCC believe that the function cannot return and there is no + * need to save registers. The code will be a bit less readable and less + * portable on other compilers however. + */ +/** @} */ diff --git a/ports/ARMCM3/chcore.c b/ports/ARMCM3/chcore.c index 3432a6577..61741c216 100644 --- a/ports/ARMCM3/chcore.c +++ b/ports/ARMCM3/chcore.c @@ -84,6 +84,8 @@ CH_IRQ_HANDLER void SysTickVector(void) { /** * The SVC vector is used for commanded context switch. + * @param otp the thread to be switched out + * @param ntp the thread to be switched it */ /** @cond never */ __attribute__((naked)) diff --git a/readme.txt b/readme.txt index ac8210705..422dd426f 100644 --- a/readme.txt +++ b/readme.txt @@ -85,6 +85,8 @@ Win32-MinGW - ChibiOS/RT simulator and demo into a WIN32 process, - Introduced the concept of interrupt classes, see the documentation. - Introduced the concept of system states, see the documentation. - Huge improvements to the ports documentation. +- Articles and notes previously in the wiki now merged in the general + documentation, the wiki entries are obsolete and will be removed. *** 1.0.0rc2 *** - FIX: Removed unused variable "retaddr" from the Cortex-M3 port.