1 /** 2 ****************************************************************************** 3 * @file stm32_adv_trace.h 4 * @author MCD Application Team 5 * @brief Header for stm32_adv_trace.c 6 ****************************************************************************** 7 * @attention 8 * 9 * <h2><center>© Copyright (c) 2019 STMicroelectronics. 10 * All rights reserved.</center></h2> 11 * 12 * This software is licensed under terms that can be found in the LICENSE file 13 * in the root directory of this software component. 14 * If no LICENSE file comes with this software, it is provided AS-IS. 15 * 16 ****************************************************************************** 17 */ 18 19 /* Define to prevent recursive inclusion -------------------------------------*/ 20 #ifndef __ADV_TRACE_H 21 #define __ADV_TRACE_H 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /* Includes ------------------------------------------------------------------*/ 28 #include "stdint.h" 29 #include "utilities_conf.h" 30 31 /** @defgroup ADV_TRACE advanced tracer 32 * @{ 33 */ 34 35 /* Exported types ------------------------------------------------------------*/ 36 /** @defgroup ADV_TRACE_exported_TypeDef ADV_TRACE exported Typedef 37 * @{ 38 */ 39 40 /** 41 * @brief prototype of the time stamp function. 42 */ 43 typedef void cb_timestamp(uint8_t *pData, uint16_t *Size); 44 45 /** 46 * @brief prototype of the overrun function. 47 */ 48 typedef void cb_overrun(uint8_t **pData, uint16_t *size); 49 /** 50 * @brief List the Advanced trace function status. 51 * list of the returned status value, any negative value is corresponding to an error. 52 */ 53 typedef enum{ 54 UTIL_ADV_TRACE_OK = 0, /*!< Operation terminated successfully.*/ 55 UTIL_ADV_TRACE_INVALID_PARAM = -1, /*!< Invalid Parameter. */ 56 UTIL_ADV_TRACE_HW_ERROR = -2, /*!< Hardware Error. */ 57 UTIL_ADV_TRACE_MEM_FULL = -3, /*!< Memory fifo full. */ 58 UTIL_ADV_TRACE_UNKNOWN_ERROR = -4, /*!< Unknown Error. */ 59 #if defined(UTIL_ADV_TRACE_CONDITIONNAL) 60 UTIL_ADV_TRACE_GIVEUP = -5, /*!< trace give up */ 61 UTIL_ADV_TRACE_REGIONMASKED = -6 /*!< trace region masked */ 62 #endif 63 } UTIL_ADV_TRACE_Status_t; 64 65 /** 66 * @brief Advanced trace driver definition 67 */ 68 typedef struct { 69 UTIL_ADV_TRACE_Status_t (* Init)(void (*cb)(void *ptr)); /*!< Media initialization. */ 70 UTIL_ADV_TRACE_Status_t (* DeInit)(void); /*!< Media Un-initialization. */ 71 UTIL_ADV_TRACE_Status_t (* StartRx)(void (*cb)(uint8_t *pdata, uint16_t size, uint8_t error)); /*!< Media to start RX process. */ 72 UTIL_ADV_TRACE_Status_t (* Send)(uint8_t *pdata, uint16_t size); /*!< Media to send data. */ 73 }UTIL_ADV_TRACE_Driver_s; 74 75 /** 76 * @} 77 */ 78 79 /* External variables --------------------------------------------------------*/ 80 /** @defgroup ADV_TRACE_exported_variables ADV_TRACE exported variables 81 * 82 * @{ 83 */ 84 /** 85 * @brief This structure is the linked with the IF layer implementation. 86 */ 87 extern const UTIL_ADV_TRACE_Driver_s UTIL_TraceDriver; 88 89 /** 90 * @} 91 */ 92 93 /* Exported constants --------------------------------------------------------*/ 94 /* Exported macros -----------------------------------------------------------*/ 95 /* Exported functions ------------------------------------------------------- */ 96 /** @defgroup ADV_TRACE_exported_function ADV_TRACE exported function 97 * @{ 98 */ 99 100 /** 101 * @brief TraceInit Initializes Logging feature 102 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 103 */ 104 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_Init(void); 105 106 /** 107 * @brief TraceDeInit module DeInitializes. 108 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 109 */ 110 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_DeInit(void); 111 112 /** 113 * @brief this function check if the buffer is empty. 114 * @retval 1 if the buffer is empty else 0 115 */ 116 uint8_t UTIL_ADV_TRACE_IsBufferEmpty(void); 117 118 /** 119 * @brief start the RX process. 120 * @param UserCallback ptr function used to get the RX data 121 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 122 */ 123 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_StartRxProcess(void (*UserCallback)(uint8_t *PData, uint16_t Size, uint8_t Error)); 124 125 /** 126 * @brief TraceSend decode the strFormat and post it to the circular queue for printing 127 * @param strFormat Trace message and format 128 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 129 */ 130 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_FSend(const char *strFormat, ...); 131 132 /** 133 * @brief post data to the circular queue 134 * @param *pdata pointer to Data 135 * @param length length of data buffer to be sent 136 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 137 */ 138 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_Send(const uint8_t *pdata, uint16_t length); 139 140 /** 141 * @brief ZCSend_Allocation allocate the memory and return information to write the data 142 * @param Length trase size 143 * @param pData pointer on the fifo 144 * @param FifoSize size of the fifo 145 * @param WritePos write position of the fifo 146 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 147 */ 148 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_ZCSend_Allocation(uint16_t Length, uint8_t **pData, uint16_t *FifoSize, uint16_t *WritePos); 149 150 /** 151 * @brief ZCSend finalize the data transfer 152 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 153 */ 154 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_ZCSend_Finalize(void); 155 /** 156 * @brief Trace send started hook 157 * @retval None 158 */ 159 160 /** 161 * @brief Trace send pre hook function 162 */ 163 void UTIL_ADV_TRACE_PreSendHook(void); 164 165 /** 166 * @brief Trace send post hook function 167 */ 168 void UTIL_ADV_TRACE_PostSendHook(void); 169 170 #if defined(UTIL_ADV_TRACE_OVERRUN) 171 /** 172 * @brief Register a function used to add overrun info inside the trace 173 * @param cb pointer of function to return overrun information 174 */ 175 void UTIL_ADV_TRACE_RegisterOverRunFunction(cb_overrun *cb); 176 #endif 177 178 #if defined(UTIL_ADV_TRACE_CONDITIONNAL) 179 180 /** 181 * @brief conditional FSend decode the strFormat and post it to the circular queue for printing 182 * @param VerboseLevel verbose level of the trace 183 * @param Region region of the trace 184 * @param TimeStampState 0 no time stamp insertion, 1 time stamp inserted inside the trace data 185 * @param strFormat formatted string 186 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 187 */ 188 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_COND_FSend(uint32_t VerboseLevel, uint32_t Region,uint32_t TimeStampState, const char *strFormat, ...); 189 190 /** 191 * @brief conditional ZCSend Write user formatted data directly in the FIFO (Z-Cpy) 192 * @param VerboseLevel verbose level of the trace 193 * @param Region region of the trace 194 * @param TimeStampState 0 no time stamp insertion, 1 time stamp inserted inside the trace data 195 * @param length data length 196 * @param pData pointer on the fifo 197 * @param FifoSize size of the fifo 198 * @param WritePos write position of the fifo 199 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 200 */ 201 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_COND_ZCSend_Allocation(uint32_t VerboseLevel, uint32_t Region, uint32_t TimeStampState, uint16_t length,uint8_t **pData, uint16_t *FifoSize, uint16_t *WritePos); 202 203 /** 204 * @brief conditional ZCSend finalize the data transfer 205 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 206 */ 207 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_COND_ZCSend_Finalize(void); 208 209 /** 210 * @brief confitionnal Send post data to the circular queue 211 * @param VerboseLevel verbose level of the trace 212 * @param Region region of the trace 213 * @param TimeStampState 0 no time stamp insertion, 1 time stamp inserted inside the trace data 214 * @param *pdata pointer to Data 215 * @param length length of data buffer ro be sent 216 * @retval Status based on @ref UTIL_ADV_TRACE_Status_t 217 */ 218 UTIL_ADV_TRACE_Status_t UTIL_ADV_TRACE_COND_Send(uint32_t VerboseLevel, uint32_t Region, uint32_t TimeStampState, const uint8_t *pdata, uint16_t length); 219 220 /** 221 * @brief Register a function used to add timestamp inside the trace 222 * @param cb pointer of function to return timestamp information 223 */ 224 void UTIL_ADV_TRACE_RegisterTimeStampFunction(cb_timestamp *cb); 225 226 /** 227 * @brief Set the verbose level 228 * @param Level (0 to 255) 229 * @retval None 230 */ 231 void UTIL_ADV_TRACE_SetVerboseLevel(uint8_t Level); 232 233 /** 234 * @brief Get the verbose level 235 * @retval verbose level 236 */ 237 uint8_t UTIL_ADV_TRACE_GetVerboseLevel(void); 238 239 /** 240 * @brief add to the mask a bit field region. 241 * @param Region bit field of region to enable 242 * @retval None 243 */ 244 void UTIL_ADV_TRACE_SetRegion(uint32_t Region); 245 246 /** 247 * @brief add to the mask a bit field region. 248 * @retval None 249 */ 250 uint32_t UTIL_ADV_TRACE_GetRegion(void); 251 252 /** 253 * @brief remove from the mask a bit field region. 254 * @param Region Region bit field of region to disable 255 * @retval None 256 */ 257 void UTIL_ADV_TRACE_ResetRegion(uint32_t Region); 258 259 #endif 260 261 /** 262 * @} 263 */ 264 265 /** 266 * @} 267 */ 268 269 #ifdef __cplusplus 270 } 271 #endif 272 273 #endif /*__ADV_TRACE_H */ 274
