/*
    ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010,
                 2011,2012 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/>.

                                      ---

    A special exception to the GPL can be applied should you wish to distribute
    a combined work that includes ChibiOS/RT, without being obliged to provide
    the source code for any proprietary components. See the file exception.txt
    for full details of how and when the exception can be applied.
*/

/**
 * @defgroup GPT GPT Driver
 * @brief   Generic GPT Driver.
 * @details This module implements a generic GPT (General Purpose Timer)
 *          driver. The timer can be programmed in order to trigger callbacks
 *          after a specified time period or continuously with a specified
 *          interval.
 * @pre     In order to use the GPT driver the @p HAL_USE_GPT option
 *          must be enabled in @p halconf.h.
 *
 * @section gpt_1 Driver State Machine
 * The driver implements a state machine internally, not all the driver
 * functionalities can be used in any moment, any transition not explicitly
 * shown in the following diagram has to be considered an error and shall
 * be captured by an assertion (if enabled).
 * @dot
  digraph example {
    rankdir="LR";
    node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true",
          width="0.9", height="0.9"];
    edge [fontname=Helvetica, fontsize=8];

    stop  [label="GPT_STOP\nLow Power"];
    uninit [label="GPT_UNINIT", style="bold"];
    ready [label="GPT_READY\nClock Enabled"];
    continuous [label="GPT_CONT..S\nContinuous\nMode"];
    oneshot [label="GPT_ONESHOT\nOne Shot\nMode"];

    uninit -> stop [label=" gptInit()", constraint=false];
    stop -> stop [label="\ngptStop()"];
    stop -> ready [label="\ngptStart()"];
    ready -> stop [label="\ngptStop()"];
    ready -> ready [label="\ngptStart()"];
    ready -> continuous [label="\ngptStartContinuous()"];
    continuous -> ready [label="\ngptStopTimer()"];
    continuous -> continuous [label=">callback<"];
    ready -> oneshot [label="\ngptStartOneShot()\ngptPolledDelay()"];
    oneshot -> ready [label="\n>callback<\nor\nDelay Over"];
  }
 * @enddot
 *
 * @section gpt_2 GPT Operations.
 * This driver abstracts a generic timer composed of:
 * - A clock prescaler.
 * - A main up counter.
 * - A comparator register that resets the main counter to zero when the limit
 *   is reached. A callback is invoked when this happens.
 * .
 * The timer can operate in three different modes:
 * - <b>Continuous Mode</b>, a periodic callback is invoked until the driver
 *   is explicitly stopped.
 * - <b>One Shot Mode</b>, a callback is invoked after the programmed period
 *   and then the timer automatically stops.
 * - <b>Delay Mode</b>, the timer is used for inserting a brief delay into
 *   the execution flow, no callback is invoked in this mode.
 * .
 * @ingroup IO
 */