drivers/ssarc/fsl_ssarc.h

0001 /*
0002  * Copyright 2020-2021 NXP
0003  * All rights reserved.
0004  *
0005  * SPDX-License-Identifier: BSD-3-Clause
0006  */
0007
0008 #ifndef _FSL_SSARC_H_
0009 #define _FSL_SSARC_H_
0010
0011 #include "fsl_common.h"
0012
0013 /*!
0014  * @addtogroup ssarc
0015  * @{
0016  */
0017
0018 /*******************************************************************************
0019  * Definitions
0020  ******************************************************************************/
0021
0022 /*! @name Driver version */
0023 /*@{*/
0024 /*! @brief SSARC driver version 2.1.0. */
0025 #define FSL_SSARC_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
0026 /*@}*/
0027
0028 #define SSARC_INT_STATUS_ALL                                                                                       \
0029     (SSARC_LP_INT_STATUS_ADDR_ERR_MASK | SSARC_LP_INT_STATUS_AHB_ERR_MASK | SSARC_LP_INT_STATUS_SW_REQ_DONE_MASK | \
0030      SSARC_LP_INT_STATUS_TIMEOUT_MASK | SSARC_LP_INT_STATUS_GROUP_CONFLICT_MASK)
0031
0032 /*!
0033  * @brief The enumeration of ssarc status flags.
0034  */
0035 enum _ssarc_interrupt_status_flags
0036 {
0037     kSSARC_AddressErrorFlag = SSARC_LP_INT_STATUS_ADDR_ERR_MASK, /*!< If the descriptor is not in the range,
0038                                                                         assert address error. */
0039     kSSARC_AHBErrorFlag = SSARC_LP_INT_STATUS_AHB_ERR_MASK,      /*!< If any AHB master access receives none-OKAY,
0040                                                                              assert AHB error. */
0041     kSSARC_SoftwareRequestDoneFlag = SSARC_LP_INT_STATUS_SW_REQ_DONE_MASK, /*!< If a software triggered save or restore
0042                                                                                 process is completed, assert sofware
0043                                                                                 request done . */
0044     kSSARC_TimeoutFlag = SSARC_LP_INT_STATUS_TIMEOUT_MASK,              /*!< If processing of a group has exceeded the
0045                                                                             timeout value, assert timeout. */
0046     kSSARC_GroupConflictFlag = SSARC_LP_INT_STATUS_GROUP_CONFLICT_MASK, /*!< Group conflict. */
0047 };
0048
0049 /*!
0050  * @brief The size of the register to be saved/restored.
0051  */
0052 typedef enum _ssarc_descriptor_register_size
0053 {
0054     kSSARC_DescriptorRegister8bitWidth  = 0x0U, /*!< The register to be saved/restored is 8 bit width. */
0055     kSSARC_DescriptorRegister16bitWidth = 0x1U, /*!< The register to be saved/restored is 16 bit width. */
0056     kSSARC_DescriptorRegister32bitWidth = 0x2U, /*!< The register to be saved/restored is 32 bit width. */
0057 } ssarc_descriptor_register_size_t;
0058
0059 /*!
0060  * @brief The operation of the descriptor.
0061  */
0062 typedef enum _ssarc_descriptor_operation
0063 {
0064     kSSARC_SaveDisableRestoreDisable = 0x0U, /*!< Disable Save operation, disable restore operation. */
0065     kSSARC_SaveEnableRestoreDisable  = SSARC_HP_SRAM2_SV_EN_MASK, /*!< Enable Save operation,
0066                                                                        disable restore operation. */
0067     kSSARC_SaveDisableRestoreEnable = SSARC_HP_SRAM2_RT_EN_MASK,  /*!< Disable Save operation,
0068                                                                        enable restore operation. */
0069     kSSARC_SaveEnableRestoreEnable = (SSARC_HP_SRAM2_RT_EN_MASK | SSARC_HP_SRAM2_SV_EN_MASK),
0070     /*!< Enable Save operation, enable restore operation. */
0071 } ssarc_descriptor_operation_t;
0072
0073 /*!
0074  * @brief The type of operation.
0075  */
0076 typedef enum _ssarc_descriptor_type
0077 {
0078     kSSARC_ReadValueWriteBack = 0x00U, /*!< Read the register value on save operation
0079                                             and write it back on restore operation */
0080     kSSARC_WriteFixedValue = 0x01U,    /*!< Always write a fixed value from DATA[31:0] */
0081     kSSARC_RMWOr           = 0x02U,    /*!< Read register, OR with the DATA[31:0], and write it back */
0082     kSSARC_RMWAnd          = 0x03U,    /*!< Read register, AND with the DATA[31:0], and write it back */
0083     kSSARC_DelayCycles     = 0x04U,    /*!< Delay for number of cycles based on the DATA[31:0] */
0084     kSSARC_Polling0        = 0x05U,    /*!< Read the register until read_data[31:0] & DATA[31:0] == 0 */
0085     kSSARC_Polling1        = 0x06U,    /*!< Read the register until read_data[31:0] & DATA[31:0] != 0 */
0086 } ssarc_descriptor_type_t;
0087
0088 /*!
0089  * @brief The order of the restore/save operation.
0090  */
0091 typedef enum _ssarc_save_restore_order
0092 {
0093     kSSARC_ProcessFromStartToEnd = 0U, /*!< Descriptors within the group are processed from start to end. */
0094     kSSARC_ProcessFromEndToStart = 1U, /*!< Descriptors within the group are processed from end to start. */
0095 } ssarc_save_restore_order_t;
0096
0097 /*!
0098  * @brief Software trigger mode.
0099  */
0100 typedef enum _ssarc_software_trigger_mode
0101 {
0102     kSSARC_TriggerSaveRequest = SSARC_LP_DESC_CTRL1_SW_TRIG_SV_MASK, /*!< Don't trigger restore operation, trigger the
0103                                                                           save operation by software. */
0104     kSSARC_TriggerRestoreRequest = SSARC_LP_DESC_CTRL1_SW_TRIG_RT_MASK, /*!< Trigger the restore operation, don't
0105                                                                           trigger the save operation. */
0106 } ssarc_software_trigger_mode_t;
0107
0108 /*!
0109  * @brief The configuration of descriptor.
0110  */
0111 typedef struct _ssarc_descriptor_config
0112 {
0113     uint32_t address; /*!< The address of the register/memory to be saved/restored. */
0114     uint32_t data;    /*!< The value of the register/memory to be saved/restored, please note that if the type
0115                           is selected as kSSARC_ReadValueWriteBack, this data field is useless.  */
0116     ssarc_descriptor_register_size_t size;  /*!< The size of register to be saved/restored. */
0117     ssarc_descriptor_operation_t operation; /*!< The operation mode of descriptor. */
0118     ssarc_descriptor_type_t type;           /*!< The type of operation. */
0119 } ssarc_descriptor_config_t;
0120
0121 /*!
0122  * @brief The configuration of the group.
0123  */
0124 typedef struct _ssarc_group_config
0125 {
0126     ssarc_cpu_domain_name_t cpuDomain;       /*!< CPU domain, define the ownership of this group. */
0127     uint32_t startIndex;                     /*!< The index of the first descriptor of the group. */
0128     uint32_t endIndex;                       /*!< The index of the last descriptor of the group. */
0129     ssarc_save_restore_order_t restoreOrder; /*!< The restore order. */
0130     ssarc_save_restore_order_t saveOrder;    /*!< The save order. */
0131     uint8_t restorePriority;                 /*!< Restore priority of current group.
0132                                                   0 is the highest priority, 15 is the lowest priority */
0133     uint8_t savePriority;                    /*!< Save priority of current group.
0134                                                 0 is the highest priority, 15 is the lowest priority. */
0135     ssarc_power_domain_name_t powerDomain;   /*!< Power domain. */
0136     uint32_t highestAddress; /*!< Highest address that can be accessed for the descriptors in the group. */
0137     uint32_t lowestAddress;  /*!< Lowest address that can be accessed for the descriptors in the group. */
0138 } ssarc_group_config_t;
0139
0140 /*******************************************************************************
0141  * API
0142  ******************************************************************************/
0143
0144 #if defined(__cplusplus)
0145 extern "C" {
0146 #endif
0147
0148 /*!
0149  * @name Descriptor related APIs.
0150  * @{
0151  */
0152
0153 /*!
0154  * @brief Gets the address of the register to be saved/restored.
0155  *
0156  * @param base SSARC_HP peripheral base address.
0157  * @param index The index of descriptor. Range from 0 to 1023.
0158  * @return The address of the register.
0159  */
0160 static inline uint32_t SSARC_GetDescriptorRegisterAddress(SSARC_HP_Type *base, uint32_t index)
0161 {
0162     assert(index < SSARC_HP_SRAM0_COUNT);
0163
0164     return (base->DESC[index].SRAM0);
0165 }
0166
0167 /*!
0168  * @brief Gets the value of the register to be saved/restored.
0169  *
0170  * @param base SSARC_HP peripheral base address.
0171  * @param index The index of descriptor. Range from 0 to 1023.
0172  * @return The value of the register.
0173  */
0174 static inline uint32_t SSARC_GetDescriptorRegisterData(SSARC_HP_Type *base, uint32_t index)
0175 {
0176     assert(index < SSARC_HP_SRAM0_COUNT);
0177
0178     return (base->DESC[index].SRAM1);
0179 }
0180
0181 /*!
0182  * @brief Sets the configuration of the descriptor.
0183  *
0184  * @param base SSARC_HP peripheral base address.
0185  * @param index The index of descriptor. Range from 0 to 1023.
0186  * @param config Pointer to the structure ssarc_descriptor_config_t. Please refer to @ref ssarc_descriptor_config_t for
0187  *               details.
0188  */
0189 void SSARC_SetDescriptorConfig(SSARC_HP_Type *base, uint32_t index, const ssarc_descriptor_config_t *config);
0190
0191 /*!
0192  * @}
0193  */
0194
0195 /*!
0196  * @name Group Related APIs
0197  * @{
0198  */
0199
0200 /*!
0201  * @brief Inits the selected group.
0202  *
0203  * @note For the groups with the same save priority or restore priority,
0204  *       the save/restore operation runs in the group order.
0205  *
0206  * @param base SSARC_LP peripheral base address.
0207  * @param groupID The index of the group. Range from 0 to 15.
0208  * @param config Pointer to the structure ssarc_group_config_t. Please refer to @ref ssarc_group_config_t for details.
0209  */
0210 void SSARC_GroupInit(SSARC_LP_Type *base, uint8_t groupID, const ssarc_group_config_t *config);
0211
0212 /*!
0213  * @brief De-inits the selected group.
0214  *
0215  * @param base SSARC_LP peripheral base address.
0216  * @param groupID The index of the group. Range from 0 to 15.
0217  */
0218 static inline void SSARC_GroupDeinit(SSARC_LP_Type *base, uint8_t groupID)
0219 {
0220     assert(groupID < SSARC_LP_DESC_CTRL0_COUNT);
0221
0222     base->GROUPS[groupID].DESC_CTRL1 &= ~SSARC_LP_DESC_CTRL1_GP_EN_MASK;
0223 }
0224
0225 /*!
0226  * @brief Locks the configuration of the domain.
0227  *
0228  * This function locks the configuration of the domain. Once locked, only the access from the same domain is allowed,
0229  * access from other domains will be blocked. Once locked, it can only be unlocked by a hardware reset.
0230  *
0231  * @param base SSARC_LP peripheral base address.
0232  * @param groupID The index of the group. Range from 0 to 15.
0233  */
0234 static inline void SSARC_LockGroupDomain(SSARC_LP_Type *base, uint8_t groupID)
0235 {
0236     assert(groupID < SSARC_LP_DESC_CTRL0_COUNT);
0237
0238     base->GROUPS[groupID].DESC_CTRL1 |= SSARC_LP_DESC_CTRL1_DL_MASK;
0239 }
0240
0241 /*!
0242  * @brief Locks the write access to the control registers and descriptors for the selected group.
0243  *
0244  * This function Locks the write access to the control registers and descriptors for the selected group.
0245  * All writes are blocked. Once locked, it can only be unlocked by a hardware reset.
0246  *
0247  * @param base SSARC_LP peripheral base address.
0248  * @param groupID The index of the group. Range from 0 to 15.
0249  */
0250 static inline void SSARC_LockGroupWrite(SSARC_LP_Type *base, uint8_t groupID)
0251 {
0252     assert(groupID < SSARC_LP_DESC_CTRL0_COUNT);
0253
0254     base->GROUPS[groupID].DESC_CTRL1 |= SSARC_LP_DESC_CTRL1_WL_MASK;
0255 }
0256
0257 /*!
0258  * @brief Locks the read access to the control registers and descriptors for the selected group.
0259  *
0260  * This function Locks the read access to the control registers and descriptors for the selected group.
0261  * All reads are blocked. Once locked, it can only be unlocked by a hardware reset.
0262  *
0263  * @param base SSARC_LP peripheral base address.
0264  * @param groupID The index of the group. Range from 0 to 15.
0265  */
0266 static inline void SSARC_LockGroupRead(SSARC_LP_Type *base, uint8_t groupID)
0267 {
0268     assert(groupID < SSARC_LP_DESC_CTRL0_COUNT);
0269
0270     base->GROUPS[groupID].DESC_CTRL1 |= SSARC_LP_DESC_CTRL1_RL_MASK;
0271 }
0272
0273 /*!
0274  * @brief Triggers software request.
0275  *
0276  * @note Each group allows software to trigger the save/restore operation without getting the request
0277  *       from basic power controller.
0278  *
0279  * @param base SSARC_LP peripheral base address.
0280  * @param groupID The index of the group. Range from 0 to 15.
0281  * @param mode Software trigger mode. Please refer to @ref ssarc_software_trigger_mode_t for details.
0282  */
0283 void SSARC_TriggerSoftwareRequest(SSARC_LP_Type *base, uint8_t groupID, ssarc_software_trigger_mode_t mode);
0284
0285 /*!
0286  * @}
0287  */
0288
0289 /*!
0290  * @name Global Setting Related APIs
0291  */
0292
0293 /*!
0294  * @brief Resets the whole SSARC block by software.
0295  *
0296  * @note Only reset the SSARC registers, not include the DESC in SRAM.
0297  *
0298  * @param base SSARC_LP peripheral base address.
0299  */
0300 static inline void SSARC_ResetWholeBlock(SSARC_LP_Type *base)
0301 {
0302     base->CTRL |= SSARC_LP_CTRL_SW_RESET_MASK;
0303     base->CTRL &= ~SSARC_LP_CTRL_SW_RESET_MASK;
0304 }
0305
0306 /*!
0307  * @brief Enables/Disables save/restore request from the PGMC module.
0308  *
0309  * @param base SSARC_LP peripheral base address.
0310  * @param enable Used to enable/disable save/restore hardware request.
0311  *             - \b true Enable GPC save/restore requests.
0312  *             - \b false Disable GPC save/restore requests.
0313  */
0314 static inline void SSARC_EnableHardwareRequest(SSARC_LP_Type *base, bool enable)
0315 {
0316     if (enable)
0317     {
0318         base->CTRL &= ~SSARC_LP_CTRL_DIS_HW_REQ_MASK;
0319     }
0320     else
0321     {
0322         base->CTRL |= SSARC_LP_CTRL_DIS_HW_REQ_MASK;
0323     }
0324 }
0325
0326 /*!
0327  * @}
0328  */
0329
0330 /*!
0331  * @name Status Related APIs
0332  * @{
0333  */
0334
0335 /*!
0336  * @brief Gets status flags.
0337  *
0338  * @param base SSARC_LP peripheral base address.
0339  * @return The value of status flags. See @ref _ssarc_interrupt_status_flags for details.
0340  */
0341 static inline uint32_t SSARC_GetStatusFlags(SSARC_LP_Type *base)
0342 {
0343     return ((base->INT_STATUS) & SSARC_INT_STATUS_ALL);
0344 }
0345
0346 /*!
0347  * @brief Clears status flags.
0348  *
0349  * @note Only @ref kSSARC_AddressErrorFlag, @ref kSSARC_AHBErrorFlag, @ref kSSARC_TimeoutFlag and
0350  *       @ref kSSARC_GroupConflictFlag can be cleared.
0351  *
0352  * @param base SSARC_LP peripheral base address.
0353  * @param mask The mask value for flags to be cleared. See @ref _ssarc_interrupt_status_flags for details.
0354  */
0355
0356 static inline void SSARC_ClearStatusFlags(SSARC_LP_Type *base, uint32_t mask)
0357 {
0358     base->INT_STATUS = mask;
0359 }
0360
0361 /*!
0362  * @brief Gets the error index that indicates which descriptor will trigger the AHB_ERR or ADDR_ERR interrupt.
0363  *
0364  * @param base SSARC_LP peripheral base address.
0365  * @return The error index.
0366  */
0367 static inline uint32_t SSARC_GetErrorIndex(SSARC_LP_Type *base)
0368 {
0369     return (base->INT_STATUS & SSARC_LP_INT_STATUS_ERR_INDEX_MASK);
0370 }
0371
0372 /*!
0373  *@}
0374  */
0375
0376 /*!
0377  * @name Time Out Related APIs
0378  * @{
0379  */
0380
0381 /*!
0382  * @brief Sets timeout value for the entire group to complete.
0383  *
0384  * This function sets timeout value for the entire group to complete. Setting timeout value
0385  * to 0 will disable this feature.
0386  *
0387  * @param base SSARC_LP peripheral base address.
0388  * @param value The timeout value, 0 means disable time out feature.
0389  */
0390 static inline void SSARC_SetTimeoutValue(SSARC_LP_Type *base, uint32_t value)
0391 {
0392     base->HP_TIMEOUT = value;
0393 }
0394
0395 /*!
0396  * @brief Gets timeout value for AHB clock.
0397  *
0398  * @param base SSARC_LP peripheral base address.
0399  * @return The timeout value.
0400  */
0401 static inline uint32_t SSARC_GetTimeoutValue(SSARC_LP_Type *base)
0402 {
0403     return base->HP_TIMEOUT;
0404 }
0405
0406 /*!
0407  * @}
0408  */
0409
0410 /*!
0411  * @name Pending Group Related APIs
0412  */
0413
0414 /*!
0415  * @brief Gets the value that indicates which groups are pending for restore from hardware request.
0416  *
0417  * @param base SSARC_LP peripheral base address.
0418  * @return The value of the pending groups.
0419  */
0420 static inline uint16_t SSARC_GetHardwareRequestRestorePendingGroup(SSARC_LP_Type *base)
0421 {
0422     return (uint16_t)(((base->HW_GROUP_PENDING) & SSARC_LP_HW_GROUP_PENDING_HW_RESTORE_PENDING_MASK) >>
0423                       SSARC_LP_HW_GROUP_PENDING_HW_RESTORE_PENDING_SHIFT);
0424 }
0425
0426 /*!
0427  * @brief Gets the value that indicates which groups are pending for save from hardware request.
0428  *
0429  * @param base SSARC_LP peripheral base address.
0430  * @return The value of the pending groups.
0431  */
0432 static inline uint16_t SSARC_GetHardwareRequestSavePendingGroup(SSARC_LP_Type *base)
0433 {
0434     return (uint16_t)(((base->HW_GROUP_PENDING) & SSARC_LP_HW_GROUP_PENDING_HW_SAVE_PENDING_MASK) >>
0435                       SSARC_LP_HW_GROUP_PENDING_HW_SAVE_PENDING_SHIFT);
0436 }
0437
0438 /*!
0439  * @brief Gets the value that indicates which groups are pending for restore from software request.
0440  *
0441  * @param base SSARC_LP peripheral base address.
0442  * @return The value of the pending groups.
0443  */
0444 static inline uint16_t SSARC_GetSoftwareRequestRestorePendingGroup(SSARC_LP_Type *base)
0445 {
0446     return (uint16_t)(((base->SW_GROUP_PENDING) & SSARC_LP_SW_GROUP_PENDING_SW_RESTORE_PENDING_MASK) >>
0447                       SSARC_LP_SW_GROUP_PENDING_SW_RESTORE_PENDING_SHIFT);
0448 }
0449
0450 /*!
0451  * @brief Gets the value that indicates which groups are pending for save from software request.
0452  *
0453  * @param base SSARC_LP peripheral base address.
0454  * @return The value of the pending groups.
0455  */
0456 static inline uint16_t SSARC_GetSoftwareRequestSavePendingGroup(SSARC_LP_Type *base)
0457 {
0458     return (uint16_t)(((base->SW_GROUP_PENDING) & SSARC_LP_SW_GROUP_PENDING_SW_SAVE_PENDING_MASK) >>
0459                       SSARC_LP_SW_GROUP_PENDING_SW_SAVE_PENDING_SHIFT);
0460 }
0461
0462 /*!
0463  * @}
0464  */
0465
0466 #if defined(__cplusplus)
0467 }
0468 #endif
0469
0470 /*!
0471  * @}
0472  */
0473
0474 #endif /* _FSL_SSARC_H_ */