1 //***************************************************************************** 2 // 3 //! @file am_hal_dcu.h 4 //! 5 //! @brief Implementation for Debug Control Unit functionality 6 //! 7 //! @addtogroup dcu_4p DCU - Debug Control Unit 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision release_sdk_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_DCU_H 49 #define AM_HAL_DCU_H 50 51 #ifdef __cplusplus 52 extern "C" 53 { 54 #endif 55 56 #define AM_HAL_DCU_NUMDCU 21 // Number of valid bits 57 58 // Qualified DCU Controls 59 #define AM_HAL_DCU_CPUDBG_INVASIVE 0x00000002UL 60 #define AM_HAL_DCU_CPUDBG_NON_INVASIVE 0x00000004UL 61 #define AM_HAL_DCU_CPUTRC_ETM 0x00000008UL 62 #define AM_HAL_DCU_CPUTRC_ITM 0x00000004UL // Same as NON_INVASIVE 63 #define AM_HAL_DCU_CPUTRC_TPIU_SWO 0x00000010UL 64 #define AM_HAL_DCU_CPUTRC_PERFCNT 0x00000020UL 65 #define AM_HAL_DCU_CACHEDBG 0x00000040UL 66 #define AM_HAL_DCU_SWD 0x00000800UL 67 #define AM_HAL_DCU_ETB 0x00002000UL 68 #define AM_HAL_DCU_TRACE 0x00004000UL 69 70 71 // Following macros define Raw DCU Values as in HOSTDCU registers 72 // These are provided only for reference 73 // The HAL APIs work only with Qualified values (AM_HAL_DCU_* above) 74 75 // 3 bit encoding for individual DCU fields 76 #define AM_HAL_DCURAWVAL_ENABLE 0x5 77 #define AM_HAL_DCURAWVAL_DISABLE 0x2 78 #define AM_HAL_DCURAWVAL_MASK 0x7 79 80 // Raw DCU control masks 81 #define AM_HAL_DCURAW_CPUDBG_INVASIVE 0x0000000000000007ULL 82 #define AM_HAL_DCURAW_CPUDBG_NON_INVASIVE 0x0000000000000038ULL 83 #define AM_HAL_DCURAW_CPUTRC_ETM 0x00000000000001C0ULL 84 #define AM_HAL_DCURAW_CPUTRC_ITM 0x0000000000000038ULL // Same as NON_INVASIVE 85 #define AM_HAL_DCURAW_CPUTRC_TPIU_SWO 0x0000000000000E00ULL 86 #define AM_HAL_DCURAW_CPUTRC_PERFCNT 0x0000000000007000ULL 87 #define AM_HAL_DCURAW_CACHEDBG 0x0000000000038000ULL 88 #define AM_HAL_DCURAW_SWD 0x00000001C0000000ULL 89 #define AM_HAL_DCURAW_ETB 0x0000007000000000ULL 90 #define AM_HAL_DCURAW_TRACE 0x0000038000000000ULL 91 92 93 // All possible controls 94 #define AM_HAL_DCURAW_MASK 0x000003F1C003FFFFULL 95 #define AM_HAL_DCURAW_ENABLE 0x000002D14002DB6DULL 96 #define AM_HAL_DCURAW_DISABLE 0x0000012080012492ULL 97 98 // Convenience wrappers 99 //! @param ui32Mask - DCU controls to be modified - OR'ing of AM_HAL_DCU_* masks defined above 100 #define am_hal_dcu_enable(ui32Mask) am_hal_dcu_update(true, (ui32Mask)) 101 //! @param ui32Mask - DCU controls to be modified - OR'ing of AM_HAL_DCU_* masks defined above 102 #define am_hal_dcu_disable(ui32Mask) am_hal_dcu_update(false, (ui32Mask)) 103 104 //***************************************************************************** 105 // 106 //! @brief Read DCU Lock 107 //! 108 //! @param pui32Val - Pointer to word for returned data (Qualified DCU Mask) 109 //! 110 //! This will retrieve the DCU Lock information 111 //! 112 //! @return Returns AM_HAL_STATUS_SUCCESS on success 113 // 114 //***************************************************************************** 115 extern uint32_t am_hal_dcu_lock_status_get(uint32_t *pui32Val); 116 117 //***************************************************************************** 118 // 119 //! @brief Write DCU Lock (Qualified Values) 120 //! 121 //! @param ui32Mask - Mask for lock values 122 //! 123 //! This will lock the DCU from further changes 124 //! 125 //! @return Returns AM_HAL_STATUS_SUCCESS on success 126 // 127 //***************************************************************************** 128 extern uint32_t am_hal_dcu_lock(uint32_t ui32Mask); 129 130 //***************************************************************************** 131 // 132 //! @brief Read DCU Enables (Qualified Values) 133 //! 134 //! @param pui32Val - Pointer to Mask for returned data 135 //! 136 //! This will get the current DCU Enable settings 137 //! 138 //! @return Returns AM_HAL_STATUS_SUCCESS on success 139 // 140 //***************************************************************************** 141 extern uint32_t am_hal_dcu_get(uint32_t *pui32Val); 142 143 //***************************************************************************** 144 // 145 //! @brief Update DCU Enable (Qualified Values) 146 //! 147 //! @param ui32Mask - DCU controls to be modified 148 //! @param bEnable - Whether to enable or disable 149 //! 150 //! This will update the DCU Enable settings, if not locked 151 //! 152 //! @return Returns AM_HAL_STATUS_SUCCESS on success 153 // 154 //***************************************************************************** 155 extern uint32_t am_hal_dcu_update(bool bEnable, uint32_t ui32Mask); 156 157 //***************************************************************************** 158 // 159 //! @brief DCU Disable - Using MCUCTRL Override 160 //! 161 //! @param ui32Mask - DCU controls to be modified (Qualified Values) 162 //! 163 //! This will update the MCUCTRL DCU Disable Override settings 164 //! This can only further lock things if the corresponding DCU Enable was open 165 //! 166 //! @return Returns AM_HAL_STATUS_SUCCESS on success 167 // 168 //***************************************************************************** 169 extern uint32_t am_hal_dcu_mcuctrl_override(uint32_t ui32Mask); 170 171 172 #ifdef __cplusplus 173 } 174 #endif 175 176 #endif // AM_HAL_DCU_H 177 178 //***************************************************************************** 179 // 180 // End Doxygen group. 181 //! @} 182 // 183 //***************************************************************************** 184 185
