tool/mbed/mbed-sdk/libraries/mbed/targets/hal/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/hal/smc/fsl_smc_hal.h

   1 /*
   2  * Copyright (c) 2013 - 2014, Freescale Semiconductor, Inc.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without modification,
   6  * are permitted provided that the following conditions are met:
   7  *
   8  * o Redistributions of source code must retain the above copyright notice, this list
   9  *   of conditions and the following disclaimer.
  10  *
  11  * o Redistributions in binary form must reproduce the above copyright notice, this
  12  *   list of conditions and the following disclaimer in the documentation and/or
  13  *   other materials provided with the distribution.
  14  *
  15  * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
  16  *   contributors may be used to endorse or promote products derived from this
  17  *   software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #if !defined(__FSL_SMC_HAL_H__)
  32 #define __FSL_SMC_HAL_H__
  33
  34 #include <stdint.h>
  35 #include <stdbool.h>
  36 #include <assert.h>
  37 #include "fsl_device_registers.h"
  38 #include "fsl_smc_features.h"
  39
  40 /*! @addtogroup smc_hal*/
  41 /*! @{*/
  42
  43 /*! @file fsl_smc_hal.h */
  44
  45 /*******************************************************************************
  46  * Definitions
  47  ******************************************************************************/
  48 /*! @brief Power Modes */
  49 typedef enum _power_modes {
  50     kPowerModeRun,
  51     kPowerModeWait,
  52     kPowerModeStop,
  53     kPowerModeVlpr,
  54     kPowerModeVlpw,
  55     kPowerModeVlps,
  56     kPowerModeLls,
  57     kPowerModeVlls,
  58     kPowerModeHsrun,
  59     kPowerModeMax
  60 } power_modes_t;
  61
  62 /*!
  63  * @brief Error code definition for the system mode controller manager APIs.
  64  */
  65 typedef enum _smc_hal_error_code {
  66     kSmcHalSuccess,                           /*!< Success */
  67     kSmcHalNoSuchModeName,                    /*!< Cannot find the mode name specified*/
  68     kSmcHalAlreadyInTheState,                 /*!< Already in the required state*/
  69     kSmcHalFailed                             /*!< Unknown error, operation failed*/
  70 } smc_hal_error_code_t;
  71
  72 /*! @brief Power Modes in PMSTAT*/
  73 typedef enum _power_mode_stat {
  74     kStatRun    = 0x01,             /*!< 0000_0001 - Current power mode is RUN*/
  75     kStatStop   = 0x02,             /*!< 0000_0010 - Current power mode is STOP*/
  76     kStatVlpr   = 0x04,             /*!< 0000_0100 - Current power mode is VLPR*/
  77     kStatVlpw   = 0x08,             /*!< 0000_1000 - Current power mode is VLPW*/
  78     kStatVlps   = 0x10,             /*!< 0001_0000 - Current power mode is VLPS*/
  79     kStatLls    = 0x20,             /*!< 0010_0000 - Current power mode is LLS*/
  80     kStatVlls   = 0x40,             /*!< 0100_0000 - Current power mode is VLLS*/
  81     kStatHsrun  = 0x80              /*!< 1000_0000 - Current power mode is HSRUN*/
  82 } power_mode_stat_t;
  83
  84 /*! @brief Power Modes Protection*/
  85 typedef enum _power_modes_protect {
  86     kAllowHsrun,                    /*!< Allow High Speed Run mode*/
  87     kAllowVlp,                      /*!< Allow Very-Low-Power Modes*/
  88     kAllowLls,                      /*!< Allow Low-Leakage Stop Mode*/
  89     kAllowVlls,                     /*!< Allow Very-Low-Leakage Stop Mode*/
  90     kAllowMax
  91 } power_modes_protect_t;
  92
  93 /*!
  94  * @brief Run mode definition
  95  */
  96 typedef enum _smc_run_mode {
  97     kSmcRun,                                /*!< normal RUN mode*/
  98     kSmcReservedRun,
  99     kSmcVlpr,                               /*!< Very-Low-Power RUN mode*/
 100     kSmcHsrun                               /*!< High Speed Run mode (HSRUN)*/
 101 } smc_run_mode_t;
 102
 103 /*!
 104  * @brief Stop mode definition
 105  */
 106 typedef enum _smc_stop_mode {
 107     kSmcStop,                               /*!< Normal STOP mode*/
 108     kSmcReservedStop1,                      /*!< Reserved*/
 109     kSmcVlps,                               /*!< Very-Low-Power STOP mode*/
 110     kSmcLls,                                /*!< Low-Leakage Stop mode*/
 111     kSmcVlls                                /*!< Very-Low-Leakage Stop mode*/
 112 } smc_stop_mode_t;
 113
 114 /*!
 115  * @brief VLLS/LLS stop sub mode definition
 116  */
 117 typedef enum _smc_stop_submode {
 118     kSmcStopSub0,
 119     kSmcStopSub1,
 120     kSmcStopSub2,
 121     kSmcStopSub3
 122 } smc_stop_submode_t;
 123
 124 /*! @brief Low Power Wake Up on Interrupt option*/
 125 typedef enum _smc_lpwui_option {
 126     kSmcLpwuiEnabled,                        /*!< Low Power Wake Up on Interrupt enabled*/
 127     kSmcLpwuiDisabled                        /*!< Low Power Wake Up on Interrupt disabled*/
 128 } smc_lpwui_option_t;
 129
 130 /*! @brief Partial STOP option*/
 131 typedef enum _smc_pstop_option {
 132     kSmcPstopStop,                          /*!< STOP - Normal Stop mode*/
 133     kSmcPstopStop1,                         /*!< Partial Stop with both system and bus clocks disabled*/
 134     kSmcPstopStop2,                         /*!< Partial Stop with system clock disabled and bus clock enabled*/
 135     kSmcPstopReserved,
 136 } smc_pstop_option_t;
 137
 138 /*! @brief POR option*/
 139 typedef enum _smc_por_option {
 140     kSmcPorEnabled,                        /*!< POR detect circuit is enabled in VLLS0*/
 141     kSmcPorDisabled                        /*!< POR detect circuit is disabled in VLLS0*/
 142 } smc_por_option_t;
 143
 144 /*! @brief LPO power option*/
 145 typedef enum _smc_lpo_option {
 146     kSmcLpoEnabled,                        /*!< LPO clock is enabled in LLS/VLLSx*/
 147     kSmcLpoDisabled                        /*!< LPO clock is disabled in LLS/VLLSx*/
 148 } smc_lpo_option_t;
 149
 150 /*! @brief Power mode control options*/
 151 typedef enum _smc_power_options {
 152     kSmcOptionLpwui,                        /*!< Low Power Wake Up on Interrupt*/
 153     kSmcOptionPropo                         /*!< POR option*/
 154 } smc_power_options_t;
 155
 156 /*! @brief Power mode protection configuration*/
 157 typedef struct _smc_power_mode_protection_config {
 158     bool                vlpProt;            /*!< VLP protect*/
 159     bool                llsProt;            /*!< LLS protect */
 160     bool                vllsProt;           /*!< VLLS protect*/
 161 #if FSL_FEATURE_SMC_HAS_HIGH_SPEED_RUN_MODE
 162     bool                hsrunProt;          /*!< HSRUN protect */
 163 #endif
 164 } smc_power_mode_protection_config_t;
 165
 166 /*! @brief Power mode control configuration used for calling the SMC_SYS_SetPowerMode API. */
 167 typedef struct _smc_power_mode_config {
 168     power_modes_t       powerModeName;      /*!< Power mode(enum), see power_modes_t */
 169     smc_stop_submode_t  stopSubMode;        /*!< Stop submode(enum), see smc_stop_submode_t */
 170 #if FSL_FEATURE_SMC_HAS_LPWUI
 171     bool                lpwuiOption;        /*!< If LPWUI option is needed */
 172     smc_lpwui_option_t  lpwuiOptionValue;   /*!< LPWUI option(enum), see smc_lpwui_option_t */
 173 #endif
 174 #if FSL_FEATURE_SMC_HAS_PORPO
 175     bool                porOption;          /*!< If POR option is needed */
 176     smc_por_option_t    porOptionValue;     /*!< POR option(enum), see smc_por_option_t */
 177 #endif
 178 #if FSL_FEATURE_SMC_HAS_PSTOPO
 179     bool                pstopOption;        /*!< If PSTOPO option is needed */
 180     smc_pstop_option_t  pstopOptionValue;   /*!< PSTOPO option(enum), see smc_por_option_t */
 181 #endif
 182 } smc_power_mode_config_t;
 183
 184 /*******************************************************************************
 185  * API
 186  ******************************************************************************/
 187
 188 #if defined(__cplusplus)
 189 extern "C" {
 190 #endif /* __cplusplus*/
 191
 192 /*! @name System mode controller APIs*/
 193 /*@{*/
 194
 195 /*!
 196  * @brief Configures the power mode.
 197  *
 198  * This function configures the power mode control for both run, stop, and
 199  * stop sub mode if needed. Also it configures the power options for a specific
 200  * power mode. An application should follow the proper procedure to configure and
 201  * switch power modes between  different run and stop modes. For proper procedures
 202  * and supported power modes, see an appropriate chip reference
 203  * manual. See the smc_power_mode_config_t for required
 204  * parameters to configure the power mode and the supported options. Other options
 205  * may need to be individually configured through the HAL driver. See the HAL driver
 206  * header file for details.
 207  *
 208  * @param baseAddr  Base address for current SMC instance.
 209  * @param powerModeConfig Power mode configuration structure smc_power_mode_config_t
 210  * @return errorCode SMC error code
 211  */
 212 smc_hal_error_code_t SMC_HAL_SetMode(uint32_t baseAddr,
 213                                      const smc_power_mode_config_t *powerModeConfig);
 214
 215 /*!
 216  * @brief Configures all power mode protection settings.
 217  *
 218  * This function  configures the power mode protection settings for
 219  * supported power modes in the specified chip family. The available power modes
 220  * are defined in the smc_power_mode_protection_config_t. An application should provide
 221  * the protect settings for all supported power modes on the chip. This
 222  * should be done at an early system level initialization stage. See the reference manual
 223  * for details. This register can only write once after the power reset. If the user has
 224  * only a single option to set,
 225  * either use this function or use the individual set function.
 226  *
 227  *
 228  * @param baseAddr  Base address for current SMC instance.
 229  * @param protectConfig Configurations for the supported power mode protect settings
 230  *                      - See smc_power_mode_protection_config_t for details.
 231  */
 232 void SMC_HAL_SetProtection(uint32_t baseAddr, smc_power_mode_protection_config_t *protectConfig);
 233
 234 /*!
 235  * @brief Configures the individual power mode protection settings.
 236  *
 237  * This function  only configures the power mode protection settings for
 238  * a specified power mode on the specified chip family. The available power modes
 239  * are defined in the smc_power_mode_protection_config_t. See the reference manual
 240  * for details. This register can only write once after the power reset.
 241  *
 242  * @param baseAddr  Base address for current SMC instance.
 243  * @param protect Power mode to set for protection
 244  * @param allow   Allow or not allow the power mode protection
 245  */
 246 void SMC_HAL_SetProtectionMode(uint32_t baseAddr, power_modes_protect_t protect, bool allow);
 247
 248 /*!
 249  * @brief Gets the the current power mode protection setting.
 250  *
 251  * This function  gets the current power mode protection settings for
 252  * a specified power mode.
 253  *
 254  * @param baseAddr  Base address for current SMC instance.
 255  * @param protect Power mode to set for protection
 256  * @return state  Status of the protection setting
 257  *                - true: Allowed
 258  *                - false: Not allowed
 259 */
 260 bool SMC_HAL_GetProtectionMode(uint32_t baseAddr, power_modes_protect_t protect);
 261
 262 /*!
 263  * @brief Configures the the RUN mode control setting.
 264  *
 265  * This function  sets the run mode settings, for example, normal run mode,
 266  * very lower power run mode, etc. See the smc_run_mode_t for supported run
 267  * mode on the chip family and the reference manual for details about the
 268  * run mode.
 269  *
 270  * @param baseAddr  Base address for current SMC instance.
 271  * @param runMode Run mode setting defined in smc_run_mode_t
 272  */
 273 void SMC_HAL_SetRunMode(uint32_t baseAddr, smc_run_mode_t runMode);
 274
 275 /*!
 276  * @brief Gets  the current RUN mode configuration setting.
 277  *
 278  * This function  gets the run mode settings. See the smc_run_mode_t
 279  * for a supported run mode on the chip family and the reference manual for
 280  * details about the run mode.
 281  *
 282  * @param baseAddr  Base address for current SMC instance.
 283  * @return setting Run mode configuration setting
 284  */
 285 smc_run_mode_t SMC_HAL_GetRunMode(uint32_t baseAddr);
 286
 287 /*!
 288  * @brief Configures  the STOP mode control setting.
 289  *
 290  * This function  sets the stop mode settings, for example, normal stop mode,
 291  * very lower power stop mode, etc. See the  smc_stop_mode_t for supported stop
 292  * mode on the chip family and the reference manual for details about the
 293  * stop mode.
 294  *
 295  * @param baseAddr  Base address for current SMC instance.
 296  * @param stopMode Stop mode defined in smc_stop_mode_t
 297  */
 298 void SMC_HAL_SetStopMode(uint32_t baseAddr, smc_stop_mode_t stopMode);
 299
 300 /*!
 301  * @brief Gets the current STOP mode control settings.
 302  *
 303  * This function  gets the stop mode settings, for example, normal stop mode,
 304  * very lower power stop mode, etc. See the  smc_stop_mode_t for supported stop
 305  * mode on the chip family and the reference manual for details about the
 306  * stop mode.
 307  *
 308  * @param baseAddr  Base address for current SMC instance.
 309  * @return setting Current stop mode configuration setting
 310  */
 311 smc_stop_mode_t SMC_HAL_GetStopMode(uint32_t baseAddr);
 312
 313 /*!
 314  * @brief Configures the stop sub mode control setting.
 315  *
 316  * This function  sets the stop submode settings. Some of the stop mode
 317  * further supports submodes. See the  smc_stop_submode_t for supported
 318  * stop submodes and the  reference manual for details about the submodes
 319  * for a specific stop mode.
 320  *
 321  * @param baseAddr  Base address for current SMC instance.
 322  * @param stopSubMode Stop submode setting defined in smc_stop_submode_t
 323  */
 324 void SMC_HAL_SetStopSubMode(uint32_t baseAddr, smc_stop_submode_t stopSubMode);
 325
 326 /*!
 327  * @brief Gets the current stop submode configuration settings.
 328  *
 329  * This function  gets the stop submode settings. Some of the stop mode
 330  * further support  submodes. See the smc_stop_submode_t for supported
 331  * stop submodes and the reference manual for details about the submode
 332  * for a specific stop mode.
 333  *
 334  * @param baseAddr  Base address for current SMC instance.
 335  * @return setting Current stop submode setting
 336 */
 337 smc_stop_submode_t SMC_HAL_GetStopSubMode(uint32_t baseAddr);
 338
 339 #if FSL_FEATURE_SMC_HAS_PORPO
 340 /*!
 341  * @brief Configures the POR (power-on-reset) option.
 342  *
 343  * This function  sets the POR power option setting. It controls whether the
 344  * POR detect circuit (for brown-out detection) is enabled in a certain stop mode.
 345  * The setting either enables or disables the above feature when the POR
 346  * occurs. See the reference manual for details.
 347  *
 348  * @param baseAddr  Base address for current SMC instance.
 349  * @param option POR option setting refer to smc_por_option_t
 350  */
 351 void SMC_HAL_SetPorMode(uint32_t baseAddr, smc_por_option_t option);
 352
 353 /*!
 354  * @brief Gets the configuration settings for the POR option.
 355  *
 356  * This function  sets the POR power option setting. See the configuration function
 357  * header for details.
 358  *
 359  * @param baseAddr  Base address for current SMC instance.
 360  * @return option Current POR option setting
 361 */
 362 smc_por_option_t SMC_HAL_GetPorMode(uint32_t baseAddr);
 363 #endif
 364
 365 #if FSL_FEATURE_SMC_HAS_PSTOPO
 366 /*!
 367  * @brief Configures the PSTOPO (Partial Stop Option).
 368  *
 369  * This function  sets the PSTOPO option. It controls whether a Partial
 370  * Stop mode is entered when the STOPM=STOP. When entering a Partial Stop mode from the
 371  * RUN mode, the PMC, MCG and Flash remain fully powered allowing the device
 372  * to wakeup almost instantaneously at the expense of a higher power consumption.
 373  * In PSTOP2, only the system clocks are gated, which allows the peripherals running on bus
 374  * clock to remain fully functional. In PSTOP1, both system and bus clocks are
 375  * gated. Refer to the smc_pstop_option_t for supported options. See the reference
 376  * manual for details.
 377  *
 378  * @param baseAddr  Base address for current SMC instance.
 379  * @param option PSTOPO option setting defined in smc_pstop_option_t
 380  */
 381 void SMC_HAL_SetPstopMode(uint32_t baseAddr, smc_pstop_option_t option);
 382
 383 /*!
 384  * @brief Gets the configuration of the PSTOPO option.
 385  *
 386  * This function  gets the current PSTOPO option setting. See the  configuration
 387  * function for more details.
 388  *
 389  * @param baseAddr  Base address for current SMC instance.
 390  * @return option Current PSTOPO option setting
 391  */
 392 smc_pstop_option_t SMC_HAL_GetPstopMode(uint32_t baseAddr);
 393 #endif
 394
 395 #if FSL_FEATURE_SMC_HAS_LPOPO
 396 /*!
 397  * @brief Configures the LPO option setting.
 398  *
 399  * This function  sets the LPO option setting. It controls whether the 1 kHZ
 400  * LPO clock is enabled in a certain lower power stop modes. See the
 401  * smc_lpo_option_t for supported options and the reference manual for
 402  * details about this option.
 403  *
 404  * @param baseAddr  Base address for current SMC instance.
 405  * @param option LPO option setting defined in smc_lpo_option_t
 406  */
 407 void SMC_HAL_SetLpoMode(uint32_t baseAddr, smc_lpo_option_t option);
 408
 409 /*!
 410  * @brief Gets the  settings of the LPO option.
 411  *
 412  * This function  gets the current LPO option setting. See the  configuration
 413  * function for details.
 414  *
 415  * @param baseAddr  Base address for current SMC instance.
 416  * @return option Current LPO option setting
 417  */
 418 smc_por_option_t SMC_HAL_GetLpoMode(uint32_t baseAddr);
 419 #endif
 420
 421 #if FSL_FEATURE_SMC_HAS_LPWUI
 422 /*!
 423  * @brief Configures the LPWUI (Low Power Wake Up on interrupt) option.
 424  *
 425  * This function  sets the LPWUI option and cause the system to exit
 426  * to normal RUN mode when any active interrupt occurs while in a specific lower
 427  * power mode. See the  smc_lpwui_option_t for supported options and the
 428  * reference manual for more details about this option.
 429  *
 430  * @param baseAddr  Base address for current SMC instance.
 431  * @param option LPWUI option setting defined in smc_lpwui_option_t
 432  */
 433 void SMC_HAL_SetLpwuiMode(uint32_t baseAddr, smc_lpwui_option_t option);
 434
 435 /*!
 436  * @brief Gets the current LPWUI option.
 437  *
 438  * This function  gets the LPWUI option. See the configuration function for more
 439  * details.
 440  *
 441  * @param baseAddr  Base address for current SMC instance.
 442  * @return setting Current LPWAUI option setting
 443  */
 444 smc_lpwui_option_t SMC_HAL_GetLpwuiMode(uint32_t baseAddr);
 445 #endif
 446
 447 /*!
 448  * @brief Gets the current power mode stat.
 449  *
 450  * This function  returns the current power mode stat. Once application
 451  * switches the power mode, it should always check the stat to check whether it
 452  * runs into the specified mode or not. An application  should  check
 453  * this mode before switching to a different mode. The system  requires that
 454  * only certain modes can switch to other specific modes. See the
 455  * reference manual for details and the _power_mode_stat for information about
 456  * the power stat.
 457  *
 458  * @param baseAddr  Base address for current SMC instance.
 459  * @return stat  Current power mode stat
 460  */
 461 uint8_t SMC_HAL_GetStat(uint32_t baseAddr);
 462
 463 /*@}*/
 464
 465 #if defined(__cplusplus)
 466 }
 467 #endif /* __cplusplus*/
 468
 469 /*! @}*/
 470
 471 #endif /* __FSL_SMC_HAL_H__*/
 472 /*******************************************************************************
 473  * EOF
 474  ******************************************************************************/
 475