/*
    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.

    This file is part of ChibiOS/RT.

    ChibiOS/RT is free software; you can redistribute it and/or modify
    it 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.

    ChibiOS/RT is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/**
 * @page article_mutual_exclusion Mutual Exclusion guide
 * The most common problem when writing multithreaded code is the
 * synchronization on the shared resources/services.<br>
 * ChibiOS/RT offers a rich variety of mechanisms that apparently solve the
 * same problem. I wrote apparently because each mechanism has its pro and
 * cons.
 * This article will introduce the various mechanisms and the explain the
 * right scenarios for each one.
 *
 * <h2>Basics</h2>
 * Some of the concepts mentioned in this article can be found in the
 * following Wikipedia articles:
 * - <a href="http://en.wikipedia.org/wiki/Mutual_exclusion" target="_blank">
 *   Mutual Exclusion</a>
 * - <a href="http://en.wikipedia.org/wiki/Priority_inversion" target="_blank">
 *   Priority Inversion</a>
 * - <a href="http://en.wikipedia.org/wiki/Priority_inheritance"
 *   target="_blank">Priority Inheritance</a>
 * - <a href="http://en.wikipedia.org/wiki/Priority_ceiling" target="_blank">
 *   Priority Ceiling</a>
 * .
 * <h2>Mutual exclusion by System Locks</h2>
 * This is the lowest level mechanism, the system is locked by invoking the
 * @p chSysLock() API and then unlocked by invoking @p chSysUnlock().<br>
 * The implementation is architecture dependent but it is guaranteed to, at
 * least, disable the interrupt sources with hardware priority below or equal
 * the kernel level.
 *
 * <h3>Advantages</h3>
 * - It is the lightest as execution time, often a lock or unlock becomes just a
 *   single inlined assembler instruction.
 * - It ensures mutual exclusion among threads but also interrupt handling code.
 * - The implementation would ensure mutual exclusion even on multicore
 *   architectures where multiple hardware threads are present.
 * .
 * <h3>Disadvantages</h3>
 * - Disabling interrupts for a long period of time can deteriorate the overall
 *   system response time and/or introduce jitter.
 * .
 * <h3>When use Locks</h3>
 * - When mutual exclusion with interrupt handlers is required.
 * - When the operation within the lock zone is very simple and has finite
 *   time.
 * .
 * <h3>Example</h3>
 * @code
 * ...
 * chSysLock();
 * /* Protected code */
 * chSysUnlock();
 * ...
 * @endcode
 *
 * <h2>Mutual exclusion by Semaphores</h2>
 * In ChibiOS/RT the counting semaphores are mainly meant as a
 * synchronization mechanism between interrupt handlers and high level code
 * running at thread level. Usually a thread waits on a semaphore that is
 * signaled asynchronously by an interrupt handler.<br>
 * The semaphores can, however, be used as simple mutexes by initializing
 * counter to one.
 *
 * <h3>Advantages</h3>
 * - The semaphores code is "already there" if you use the I/O queues and
 *   you don't want to enable the mutexes too because space constraints.
 * - Semaphores are lighter than mutexes because their queues are FIFO
 *   ordered and do not have any overhead caused by the priority inheritance
 *   algorithm.
 * - A semaphore takes less RAM than a mutex (12 vs 16 bytes on 32 bit
 *   architectures).
 * .
 * <h3>Disadvantages</h3>
 * - Semaphore queues are FIFO ordered by default, an option exist to make
 *   them priority ordered but this can impact I/O performance because
 *   semaphores are used in I/O queues.
 * - Semaphores do not implement the Priority Inheritance algorithm.
 * .
 * <h3>When use Semaphores</h3>
 * - When you don't need queuing by priority nor the Priority Inheritance
 *   algorithm.
 * - When RAM/ROM space is scarce.
 * .
 * <h3>Example</h3>
 * @code
 * static Semaphore sem; /* Semaphore declaration */
 * ...
 * chSemInit(&sem, 1); /* Semaphore initialization before use */
 * ...
 * chSemWait(&sem);
 * /* Protected code */
 * chSemSignal(&sem);
 * ...
 * @endcode
 *
 * <h2>Mutual exclusion by Mutexes</h2>
 * The mutexes, also known as binary semaphores (we choose to not use this
 * terminology to avoid confusion with counting semaphores), are the mechanism
 * intended as general solution for Mutual Exclusion.
 *
 * <h3>Advantages</h3>
 * - Mutexes implement the Priority Inheritance algorithm that is an important
 *   tool in reducing jitter and improve overall system response time (it is
 *   not a magic solution, just a tool for the system designer).
 * .
 * <h3>Disadvantages</h3>
 * - Heaviest among all the possible choices. The Priority Inheritance method
 *   is efficiently implemented but nothing is more efficient than no code at
 *   all.
 * .
 * <h3>When use Mutexes</h3>
 * - When you are designing a very complex system with hard realtime
 *   requirements.
 * .
 * <h3>Example</h3>
 * @code
 * static Mutex mtx; /* Mutex declaration */
 * ...
 * chMtxInit(&mtx); /* Mutex initialization before use */
 * ...
 * chMtxLock(&mtx);
 * /* Protected code */
 * chMtxUnlock();
 * ...
 * @endcode
 *
 * <h2>Mutual exclusion by priority boost</h2>
 * Another way to implement mutual exclusion is to boost the thread priority
 * to a level higher than all of the threads competing for a certain resource.
 * This solution effectively implements an Immediate Priority Ceiling
 * algorithm.
 *
 * <h3>Advantages</h3>
 * - Almost free as code size, you need no semaphores nor mutexes.
 * - No RAM overhead.
 * - Fast execution, priority change is a quick operation under ChibiOS/RT.
 * - The Priority Ceiling protocol can help mitigate potential Priority
 *   Inversion problems.
 * .
 * <h3>Disadvantages</h3>
 * - Makes the design more complicated because priorities must be assigned to
 *   not just threads but also assigned to the resources to be protected.
 * - Locking a resource affects all the threads with lower priority even if
 *   not interested to the resource.
 * - All the threads that can access the resource must have lower priority
 *   than the resource itself.
 * - The mechanism is not easy to understand in the code unless it is clearly
 *   documented.
 * - This method does not work in on multicore architectures where multiple
 *   hardware threads are present.
 * - Only useful in very simple applications.
 * .
 * <h3>Example</h3>
 * @code
 * /* Priority assigned to the resource, threads must have lower
 *    priority than this.*/
 * #define AAA_RESOURCE_PRIORITY NORMALPRIO+10
 * ...
 * /* Locks the resources AAA.*/
 * tprio_t aaa_old_prio = chThdSetPriority(AAA_RESOURCE_PRIORITY);
 * /* Accessing resource AAA */
 * chThdSetPriority(aaa_old_prio); /* Unlocks AAA.*/
 * ...
 * @endcode
 *
 * <h2>Mutual exclusion by message passing</h2>
 * Another method is to make a single dedicated thread execute the critical
 * code and make it work as a messages server. The other threads can request
 * the service to the server by sending a properly formatted message and
 * then wait for the answer with the result.<br>
 * This method is very useful when integrating into the system components not
 * designed to be reentrant or to be executed in a multithreaded environment,
 * as example a 3rd part file system or a networking protocol stack.
 *
 * <h3>Advantages</h3>
 * - It is possible to encapsulate very complex logic without worry about
 *   about concurrent accesses.
 * - If the encapsulate code uses a large stack area only the server thread
 *   have to allocate enough RAM, the client threads save RAM by just
 *   requesting the service to the server.
 * - Clean system architecture.
 * - This method also implements a form of Priority Ceiling. The ceiling is
 *   the priority of the server thread itself.
 * .
 * <h3>Disadvantages</h3>
 * - More complex implementation, a protocol must be created between clients
 *   and server.
 * - Two context switches are required for each request to the server (but
 *   ChibiOSRT is very efficient at that).
 * - Requires a dedicated thread as server.
 * .
 */