1 //***************************************************************************** 2 // 3 //! @file am_hal_itm.h 4 //! 5 //! @brief Functions for Operating the Instrumentation Trace Macrocell 6 //! 7 //! @addtogroup itm3p ITM - Instrumentation Trace Macrocell 8 //! @ingroup apollo3p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2024, 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_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_ITM_H 49 #define AM_HAL_ITM_H 50 51 #ifdef __cplusplus 52 extern "C" 53 { 54 #endif 55 56 //***************************************************************************** 57 // 58 //! Sync Packet Defines 59 // 60 //***************************************************************************** 61 #define AM_HAL_ITM_SYNC_REG 23 62 #define AM_HAL_ITM_SYNC_VAL 0xF8F8F8F8 63 64 //***************************************************************************** 65 // 66 //! PrintF Setup 67 // 68 //***************************************************************************** 69 #define AM_HAL_ITM_PRINT_NUM_BYTES 1 70 #define AM_HAL_ITM_PRINT_NUM_REGS 1 71 extern uint32_t am_hal_itm_print_registers[AM_HAL_ITM_PRINT_NUM_REGS]; 72 73 //***************************************************************************** 74 // 75 // External function definitions 76 // 77 //***************************************************************************** 78 //***************************************************************************** 79 // 80 //! @brief Enables the ITM 81 //! 82 //! This function enables the ARM ITM by setting the TRCENA bit in the DEMCR 83 //! register. 84 // 85 //***************************************************************************** 86 extern void am_hal_itm_enable(void); 87 88 //***************************************************************************** 89 // 90 //! @brief Disables the ITM 91 //! 92 //! This function completely disables the ARM ITM by resetting the TRCENA bit 93 //! in the DEMCR register. 94 // 95 //***************************************************************************** 96 extern void am_hal_itm_disable(void); 97 98 //***************************************************************************** 99 // 100 //! @brief Checks if itm is busy and provides a delay to flush the fifo 101 //! 102 //! This function disables the ARM ITM by resetting the TRCENA bit in the DEMCR 103 //! register. 104 // 105 //***************************************************************************** 106 extern void am_hal_itm_not_busy(void); 107 108 //***************************************************************************** 109 // 110 //! @brief Sends a Sync Packet. 111 //! 112 //! Sends a sync packet. This can be useful for external software should it 113 //! become out of sync with the ITM stream. 114 // 115 //***************************************************************************** 116 extern void am_hal_itm_sync_send(void); 117 //***************************************************************************** 118 // 119 //! @brief Enables tracing on a given set of ITM ports 120 //! 121 //! @param ui8portNum - Set ports to be enabled 122 //! @parblock 123 //! 124 //! Enables tracing on the ports referred to by \e ui8portNum by writing the 125 //! associated bit in the Trace Privilege Register in the ITM.\n The value for 126 //! ui8portNum should be the logical OR one or more of the following values: 127 //! 128 //! \e ITM_PRIVMASK_0_7 - enable ports 0 through 7 129 //! \e ITM_PRIVMASK_8_15 - enable ports 8 through 15 130 //! \e ITM_PRIVMASK_16_23 - enable ports 16 through 23 131 //! \e ITM_PRIVMASK_24_31 - enable ports 24 through 31 132 //! @endparblock 133 // 134 //***************************************************************************** 135 extern void am_hal_itm_trace_port_enable(uint8_t ui8portNum); 136 137 //***************************************************************************** 138 // 139 //! @brief Disable tracing on the given ITM stimulus port. 140 //! 141 //! @param ui8portNum 142 //! @parblock 143 //! 144 //! Disables tracing on the ports referred to by \e ui8portNum by writing the 145 //! associated bit in the Trace Privilege Register in the ITM.\n 146 //! The value for ui8portNum should be the logical OR one or 147 //! more of the following values: 148 //! 149 //! \e ITM_PRIVMASK_0_7 - disable ports 0 through 7 150 //! \e ITM_PRIVMASK_8_15 - disable ports 8 through 15 151 //! \e ITM_PRIVMASK_16_23 - disable ports 16 through 23 152 //! \e ITM_PRIVMASK_24_31 - disable ports 24 through 31 153 //! @endparblock 154 // 155 //***************************************************************************** 156 extern void am_hal_itm_trace_port_disable(uint8_t ui8portNum); 157 158 //***************************************************************************** 159 // 160 //! @brief Poll the given ITM stimulus register until not busy. 161 //! 162 //! @param ui32StimReg - stimulus register 163 //! 164 //! @return 165 //! - true if not busy, 166 //! - false if busy (timed out or other error). 167 // 168 //***************************************************************************** 169 extern bool am_hal_itm_stimulus_not_busy(uint32_t ui32StimReg); 170 171 //***************************************************************************** 172 // 173 //! @brief Writes a 32-bit value to the given ITM stimulus register. 174 //! 175 //! @param ui32StimReg - Stimulus register 176 //! @param ui32Value - Value to be written. 177 //! 178 //! Write a word to the desired stimulus register. 179 // 180 //***************************************************************************** 181 extern void am_hal_itm_stimulus_reg_word_write(uint32_t ui32StimReg, 182 uint32_t ui32Value); 183 184 //***************************************************************************** 185 // 186 //! @brief Writes a short to the given ITM stimulus register. 187 //! 188 //! @param ui32StimReg - Stimulus register 189 //! @param ui16Value - Short to be written. 190 //! 191 //! Write a short to the desired stimulus register. 192 // 193 //***************************************************************************** 194 extern void am_hal_itm_stimulus_reg_short_write(uint32_t ui32StimReg, 195 uint16_t ui16Value); 196 197 //***************************************************************************** 198 // 199 //! @brief Writes a byte to the given ITM stimulus register. 200 //! 201 //! @param ui32StimReg - Stimulus register 202 //! @param ui8Value - Byte to be written. 203 //! 204 //! Write a byte to the desired stimulus register. 205 // 206 //***************************************************************************** 207 extern void am_hal_itm_stimulus_reg_byte_write(uint32_t ui32StimReg, 208 uint8_t ui8Value); 209 210 //***************************************************************************** 211 // 212 //! @brief Poll the print stimulus registers until not busy. 213 //! 214 //! @return 215 //! - true if not busy, 216 //! - false if busy (timed out or other error). 217 // 218 //***************************************************************************** 219 extern bool am_hal_itm_print_not_busy(void); 220 221 //***************************************************************************** 222 // 223 //! @brief Prints a char string out of the ITM. 224 //! 225 //! @param pcString - Pointer to the character sting 226 //! 227 //! This function prints a sting out of the ITM. 228 // 229 //***************************************************************************** 230 extern void am_hal_itm_print(char *pcString); 231 232 #ifdef __cplusplus 233 } 234 #endif 235 236 #endif // AM_HAL_ITM_H 237 238 //***************************************************************************** 239 // 240 // End Doxygen group. 241 //! @} 242 // 243 //***************************************************************************** 244
