--- /dev/null
+/**\r
+ * \file\r
+ *\r
+ * \brief DFLL management\r
+ *\r
+ * Copyright (c) 2010-2012 Atmel Corporation. All rights reserved.\r
+ *\r
+ * \asf_license_start\r
+ *\r
+ * \page License\r
+ *\r
+ * Redistribution and use in source and binary forms, with or without\r
+ * modification, are permitted provided that the following conditions are met:\r
+ *\r
+ * 1. Redistributions of source code must retain the above copyright notice,\r
+ * this list of conditions and the following disclaimer.\r
+ *\r
+ * 2. Redistributions in binary form must reproduce the above copyright notice,\r
+ * this list of conditions and the following disclaimer in the documentation\r
+ * and/or other materials provided with the distribution.\r
+ *\r
+ * 3. The name of Atmel may not be used to endorse or promote products derived\r
+ * from this software without specific prior written permission.\r
+ *\r
+ * 4. This software may only be redistributed and used in connection with an\r
+ * Atmel microcontroller product.\r
+ *\r
+ * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
+ * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
+ * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\r
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\r
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN\r
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
+ * POSSIBILITY OF SUCH DAMAGE.\r
+ *\r
+ * \asf_license_stop\r
+ *\r
+ */\r
+#ifndef CLK_DFLL_H_INCLUDED\r
+#define CLK_DFLL_H_INCLUDED\r
+\r
+#include <parts.h>\r
+#include "conf_clock.h"\r
+\r
+#if UC3L\r
+# include "uc3l/dfll.h"\r
+#elif SAM4L\r
+# include "sam4l/dfll.h"\r
+#else\r
+# error Unsupported chip type\r
+#endif\r
+\r
+/**\r
+ * \ingroup clk_group\r
+ * \defgroup dfll_group DFLL Management\r
+ *\r
+ * A Digital Frequency Locked Loop can be used to generate a highly\r
+ * accurate frequency from a slower-running reference clock, in much the\r
+ * same way as a PLL. DFLLs typically have shorter startup times and\r
+ * less jitter. They can also be used in open-loop mode to generate a\r
+ * less accurate frequency without the use of a reference clock.\r
+ *\r
+ * There may be significant variations between platforms in the support\r
+ * for certain features.\r
+ *\r
+ * \par Example: Setting up DFLL0 with default parameters and dithering enabled\r
+ *\r
+ * The following example shows how to configure and enable DFLL0 in\r
+ * closed-loop mode using the default parameters specified through\r
+ * configuration symbols.\r
+ * \code\r
+ dfll_enable_config_defaults(0); \endcode\r
+ *\r
+ * To configure and enable DFLL0 in closed-loop mode using the default\r
+ * parameters and to enable specific feature like dithering for better accuracy,\r
+ * you can use this initialization process.\r
+ * \code\r
+ struct dfll_config dfllcfg;\r
+\r
+ dfll_enable_source(CONFIG_DFLL0_SOURCE);\r
+ dfll_config_defaults(&dfllcfg, 0);\r
+ dfll_config_enable_dithering(&dfllcfg);\r
+ dfll_enable(&dfllcfg, 0);\r
+ dfll_wait_for_accurate_lock(0); \endcode\r
+ *\r
+ * When the last function call returns, DFLL0 is running at a frequency\r
+ * which matches the default configuration as accurately as possible.\r
+ * Any additional alterations to the default configuration can be added\r
+ * at the same place as the call to dfll_config_enable_dithering(), but\r
+ * note that the DFLL will never achieve "accurate" lock if dithering is\r
+ * disabled.\r
+ *\r
+ * @{\r
+ */\r
+\r
+//! \name Chip-specific DFLL characteristics\r
+//@{\r
+/**\r
+ * \def NR_DFLLS\r
+ * \brief Number of on-chip DFLLs.\r
+ */\r
+/**\r
+ * \def DFLL_MIN_HZ\r
+ * \brief Minimum frequency that the DFLL can generate.\r
+ */\r
+/**\r
+ * \def DFLL_MAX_HZ\r
+ * \brief Maximum frequency that the DFLL can generate.\r
+ */\r
+//@}\r
+\r
+/**\r
+ * \typedef dfll_refclk_t\r
+ * \brief Type used for identifying a reference clock source for the DFLL.\r
+ */\r
+\r
+//! \name DFLL Configuration\r
+//@{\r
+\r
+/**\r
+ * \struct dfll_config\r
+ * \brief Hardware-specific representation of DFLL configuration.\r
+ *\r
+ * This structure contains one or more device-specific values\r
+ * representing the current DFLL configuration. The contents of this\r
+ * structure is typically different from platform to platform, and the\r
+ * user should not access any fields except through the DFLL\r
+ * configuration API.\r
+ */\r
+\r
+/**\r
+ * \fn void dfll_config_init_open_loop_mode(struct dfll_config *cfg)\r
+ * \brief Configure the DFLL configuration \a cfg for open-loop mode.\r
+ *\r
+ * \param cfg The DFLL configuration to be initialized.\r
+ */\r
+/**\r
+ * \fn void dfll_config_init_closed_loop_mode(struct dfll_config *cfg,\r
+ * dfll_refclk_t refclk, uint16_t div, uint16_t mul)\r
+ * \brief Configure the DFLL configuration \a cfg for closed-loop mode.\r
+ *\r
+ * \param cfg The DFLL configuration to be initialized.\r
+ * \param refclk The reference clock source.\r
+ * \param div Reference clock divider.\r
+ * \param mul Multiplier (integer part only).\r
+ */\r
+/**\r
+ * \def dfll_config_defaults(cfg, dfll_id)\r
+ * \brief Initialize DFLL configuration using default parameters.\r
+ *\r
+ * After this function returns, \a cfg will contain a configuration\r
+ * which will make the DFLL run at (CONFIG_DFLLx_MUL / CONFIG_DFLLx_DIV)\r
+ * times the frequency of CONFIG_DFLLx_SOURCE. The default configuration\r
+ * will always use closed-loop mode with no fractional multiplier.\r
+ *\r
+ * \param cfg The DFLL configuration to be initialized.\r
+ * \param dfll_id Use defaults for this DFLL.\r
+ */\r
+/**\r
+ * \def dfll_get_default_rate(dfll_id)\r
+ * \brief Return the default rate in Hz of \a dfll_id.\r
+ */\r
+\r
+/**\r
+ * \fn void dfll_config_set_fractional_multiplier(struct dfll_config *cfg,\r
+ * uint16_t mul_i, uint16_t mul_f)\r
+ * \brief Set a fractional multiplier.\r
+ *\r
+ * This function has no effect in open-loop mode, and is only available\r
+ * on devices which support fractional multipliers.\r
+ *\r
+ * The fractional part of the multiplier is assumed to be 16 bits. The\r
+ * low-level driver will make sure to shift this value to match the\r
+ * hardware if necessary.\r
+ *\r
+ * \param cfg The DFLL configuration to be modified.\r
+ * \param mul_i Integer part of multiplier.\r
+ * \param mul_f Fractional part of multiplier.\r
+ */\r
+/**\r
+ * \fn void dfll_config_enable_dithering(struct dfll_config *cfg)\r
+ * \brief Enable dithering for more accurate frequency generation.\r
+ *\r
+ * The fine LSB input to the VCO is dithered to achieve fractional\r
+ * approximation to the correct multiplication ratio.\r
+ *\r
+ * \param cfg The DFLL configuration to be modified.\r
+ */\r
+/**\r
+ * \fn void dfll_config_disable_dithering(struct dfll_config *cfg)\r
+ * \brief Disable dithering.\r
+ *\r
+ * \see dfll_config_enable_dithering()\r
+ *\r
+ * \param cfg The DFLL configuration to be modified.\r
+ */\r
+/**\r
+ * \fn void dfll_config_set_initial_tuning(struct dfll_config *cfg,\r
+ * uint16_t coarse, uint16_t fine)\r
+ * \brief Set initial VCO tuning.\r
+ *\r
+ * In open loop mode, this will determine the frequency of the output.\r
+ *\r
+ * In closed loop mode, this will provide an initial estimate of the VCO\r
+ * tuning. While the DFLL will automatically adjust these values to\r
+ * match the desired output frequency, careful selection of initial\r
+ * values might reduce the time to achieve coarse and fine lock.\r
+ *\r
+ * \param cfg The DFLL configuration to be modified.\r
+ * \param coarse Coarse tuning of the frequency generator.\r
+ * \param fine Fine tuning of the frequency generator.\r
+ */\r
+/**\r
+ * \fn void dfll_config_set_max_step(struct dfll_config *cfg,\r
+ * uint16_t coarse, uint16_t fine)\r
+ * \brief Set the maximum VCO tuning step size.\r
+ *\r
+ * This function has no effect in open-loop mode.\r
+ *\r
+ * By default, both of these values are set to 50% of their respective\r
+ * maximums. It is not recommended to set the values any higher than\r
+ * this, but setting them lower might reduce the frequency overshoot at\r
+ * the expense of longer time to achieve coarse and/or fine lock.\r
+ *\r
+ * \param cfg The DFLL configuration to be modified\r
+ * \param coarse The maximum step size of the coarse VCO tuning.\r
+ * \param fine The maximum step size of the fine VCO tuning.\r
+ */\r
+/**\r
+ * \fn void dfll_config_enable_ssg(struct dfll_config *cfg,\r
+ * uint16_t amplitude, uint16_t step_size)\r
+ * \brief Enable Spread Spectrum Generator.\r
+ *\r
+ * \param cfg The DFLL configuration to be modified.\r
+ * \param amplitude The amplitude of the spread spectrum.\r
+ * \param step_size The step size of the spread spectrum.\r
+ */\r
+/**\r
+ * \fn void dfll_config_disable_ssg(struct dfll_config *cfg)\r
+ * \brief Disable Spread Spectrum Generator.\r
+ *\r
+ * \param cfg The DFLL configuration to be modified.\r
+ */\r
+//@}\r
+\r
+//! \name Interaction with the DFLL hardware\r
+//@{\r
+/**\r
+ * \fn void dfll_enable_open_loop(const struct dfll_config *cfg,\r
+ * unsigned int dfll_id)\r
+ * \brief Activate the configuration \a cfg and enable DFLL \a dfll_id\r
+ * in open-loop mode.\r
+ *\r
+ * \pre The configuration in \a cfg must represent an open-loop\r
+ * configuration.\r
+ *\r
+ * \param cfg The configuration to be activated.\r
+ * \param dfll_id The ID of the DFLL to be enabled.\r
+ */\r
+/**\r
+ * \fn void dfll_enable_closed_loop(const struct dfll_config *cfg,\r
+ * unsigned int dfll_id)\r
+ * \brief Activate the configuration \a cfg and enable DFLL \a dfll_id\r
+ * in closed-loop mode.\r
+ *\r
+ * \pre The configuration in \a cfg must represent a closed-loop\r
+ * configuration.\r
+ *\r
+ * \param cfg The configuration to be activated.\r
+ * \param dfll_id The ID of the DFLL to be enabled.\r
+ */\r
+/**\r
+ * \fn void dfll_disable_open_loop(unsigned int dfll_id)\r
+ * \brief Disable the DFLL identified by \a dfll_id.\r
+ *\r
+ * \pre The DFLL must have been enabled in open loop mode.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to be disabled.\r
+ */\r
+/**\r
+ * \fn void dfll_disable_closed_loop(unsigned int dfll_id)\r
+ * \brief Disable the DFLL identified by \a dfll_id.\r
+ *\r
+ * \pre The DFLL must have been enabled in closed loop mode.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to be disabled.\r
+ */\r
+/**\r
+ * \fn bool dfll_is_coarse_locked(unsigned int dfll_id)\r
+ * \brief Determine whether or not a DFLL has achieved coarse lock.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to check.\r
+ *\r
+ * \retval true The DFLL has determined the final value of the coarse\r
+ * VCO tuning value.\r
+ * \retval false The DFLL has not yet determined the coarse VCO tuning\r
+ * value, or has not been enabled.\r
+ */\r
+/**\r
+ * \fn bool dfll_is_fine_locked(unsigned int dfll_id)\r
+ * \brief Determine whether or not a DFLL has achieved fine lock.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to check.\r
+ *\r
+ * \retval true The DFLL has determined the final value of the fine VCO\r
+ * tuning value.\r
+ * \retval false The DFLL has not yet determined the fine VCO tuning\r
+ * value, or has not been enabled.\r
+ */\r
+/**\r
+ * \fn bool dfll_is_accurate_locked(unsigned int dfll_id)\r
+ * \brief Determine whether or not a DFLL has achieved accurate lock.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to check.\r
+ *\r
+ * \retval true The DFLL has determined the final dithering duty cycle.\r
+ * \retval false The DFLL has not yet determined the dithering duty\r
+ * cycle, or has not been enabled with dithering enabled.\r
+ */\r
+/**\r
+ * \fn void dfll_enable_source(enum dfll_refclk_t src)\r
+ * \brief Enable the source of the dfll.\r
+ * The source is enabled, if the source is not already running.\r
+ *\r
+ * \param dfll_source src The ID of the DFLL source to enable.\r
+ */\r
+/**\r
+ * \fn void dfll_enable_config_defaults(unsigned int dfll_id)\r
+ * \brief Enable the dfll with the default configuration.\r
+ * DFLL is enabled, if the DFLL is not already locked.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to enable.\r
+ */\r
+\r
+/**\r
+ * \brief Wait for the DFLL identified by \a dfll_id to achieve coarse\r
+ * lock.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to wait for.\r
+ *\r
+ * \retval STATUS_OK The DFLL has achieved coarse lock.\r
+ * \retval ERR_TIMEOUT Timed out waiting for lock.\r
+ */\r
+static inline int dfll_wait_for_coarse_lock(unsigned int dfll_id)\r
+{\r
+ /* TODO: Add timeout mechanism */\r
+ while (!dfll_is_coarse_locked(dfll_id)) {\r
+ /* Do nothing */\r
+ }\r
+\r
+ return 0;\r
+}\r
+\r
+/**\r
+ * \brief Wait for the DFLL identified by \a dfll_id to achieve fine\r
+ * lock.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to wait for.\r
+ *\r
+ * \retval STATUS_OK The DFLL has achieved fine lock.\r
+ * \retval ERR_TIMEOUT Timed out waiting for lock.\r
+ */\r
+static inline int dfll_wait_for_fine_lock(unsigned int dfll_id)\r
+{\r
+ /* TODO: Add timeout mechanism */\r
+ while (!dfll_is_fine_locked(dfll_id)) {\r
+ /* Do nothing */\r
+ }\r
+\r
+ return 0;\r
+}\r
+\r
+/**\r
+ * \brief Wait for the DFLL identified by \a dfll_id to achieve accurate\r
+ * lock.\r
+ *\r
+ * \param dfll_id The ID of the DFLL to wait for.\r
+ *\r
+ * \retval STATUS_OK The DFLL has achieved accurate lock.\r
+ * \retval ERR_TIMEOUT Timed out waiting for lock.\r
+ */\r
+static inline int dfll_wait_for_accurate_lock(unsigned int dfll_id)\r
+{\r
+ /* TODO: Add timeout mechanism */\r
+ while (!dfll_is_accurate_locked(dfll_id)) {\r
+ /* Do nothing */\r
+ }\r
+\r
+ return 0;\r
+}\r
+\r
+//@}\r
+//! @}\r
+\r
+#endif /* CLK_DFLL_H_INCLUDED */\r
projects / freertos / blobdiff