1 /* 2 * Percepio DFM v2.0.0 3 * Copyright 2023 Percepio AB 4 * www.percepio.com 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 */ 8 9 /** 10 * @file 11 * 12 * @brief DFM Alert API 13 */ 14 15 #ifndef DFM_ALERT_H 16 #define DFM_ALERT_H 17 18 #include <stdint.h> 19 #include <dfmTypes.h> 20 #include <dfmConfig.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 #if ((DFM_CFG_ENABLED) >= 1) 27 28 /** 29 * @defgroup dfm_alert_apis DFM Alert API 30 * @ingroup dfm_apis 31 * @{ 32 */ 33 34 #ifndef DFM_CFG_USE_TRACE_RECORDER 35 #define DFM_CFG_USE_TRACE_RECORDER 0 36 #endif 37 38 #ifndef DFM_CFG_MAX_SYMPTOMS 39 #error DFM_CFG_MAX_SYMPTOMS not set in dfmConfig.h! 40 #endif 41 42 #ifndef DFM_CFG_DESCRIPTION_MAX_LEN 43 #error DFM_CFG_DESCRIPTION_MAX_LEN not set in dfmConfig.h! 44 #endif 45 46 #if (DFM_FIRMWARE_VERSION_MAX_LEN > 255) 47 #error "Firmware Max Length cannot be larger than 255" 48 #endif 49 50 #if (DFM_DESCRIPTION_MAX_LEN > 255) 51 #error "Description Max Length cannot be larger than 255" 52 #endif 53 54 #if ((DFM_CFG_MAX_SYMPTOMS) <= 0) 55 #error "DFM_CFG_MAX_SYMPTOMS invalid" 56 #endif /*((DFM_CFG_MAX_SYMPTOMS) < 0) */ 57 58 #define DFM_PAYLOAD_DESCRIPTION_MAX_LEN (16) 59 60 /** 61 * @brief Callback type used when retrieving all alert data 62 */ 63 typedef DfmResult_t (*DfmAlertEntryCallback_t)(DfmEntryHandle_t xEntryHandle); 64 65 /** 66 * @brief Alert symptom definition 67 */ 68 typedef struct 69 { 70 uint32_t ulId; /* Symptom ID */ 71 uint32_t ulValue; /* The Symptom value */ 72 } DfmAlertSymptom_t; 73 74 /** 75 * @brief Alert payload definition 76 */ 77 typedef struct 78 { 79 void* pvData; 80 uint32_t ulSize; 81 char cDescriptionBuffer[DFM_PAYLOAD_DESCRIPTION_MAX_LEN]; 82 } DfmAlertPayload_t; 83 84 /** 85 * @brief Alert header 86 */ 87 typedef struct 88 { 89 uint8_t ucStartMarkers[4]; /* The DFM start marker, must be 0x50, 0x44, 0x66, 0x6D ("PDfm") */ 90 91 uint16_t usEndianness; /* The endianness checker, assign to 0x0FF0 */ 92 93 uint8_t ucVersion; /* The version of the DFM subsystem, 0 for not enabled */ 94 uint8_t ucFirmwareVersionSize; /* The maximum length of cFirmwareVersionBuffer */ 95 uint8_t ucMaxSymptoms; /* The maximum number of symptoms, initialized to DFM_CFG_MAX_SYMPTOMS */ 96 uint8_t ucSymptomCount; /* The number of registered symptoms. */ 97 uint8_t ucDescriptionSize; /* The size of the description field, can be 0 for no description included */ 98 99 uint8_t ucReserved0; /* Reserved for future use */ 100 101 uint32_t ulProduct; /* The product code, can be 0 to indicate the default product. */ 102 103 uint32_t ulAlertType; /* The alert type */ 104 105 DfmAlertSymptom_t xSymptoms[DFM_CFG_MAX_SYMPTOMS]; /* The symptoms */ 106 107 char cFirmwareVersionBuffer[DFM_FIRMWARE_VERSION_MAX_LEN]; /* Size is 4-byte aligned and with room for zero termination */ 108 109 char cAlertDescription[DFM_DESCRIPTION_MAX_LEN]; /* Size is 4-byte aligned and with room for zero termination */ 110 111 uint8_t ucEndMarkers[4]; /* The DFM start marker, must be 0x6D, 0x66, 0x44, 0x50 ("mfDP") */ 112 113 uint32_t ulChecksum; /* Checksum on the whole thing, 0 for not enabled */ 114 } DfmAlert_t; 115 116 /** 117 * @brief Struct containing the Alert header and payload info 118 */ 119 typedef struct DfmAlertData 120 { 121 uint32_t ulInitialized; 122 DfmAlert_t xAlert; 123 DfmAlertPayload_t xPayloads[DFM_CFG_MAX_PAYLOADS]; /* The payloads */ 124 uint32_t ulPayloadCount; 125 } DfmAlertData_t; 126 127 extern DfmAlertData_t* pxDfmAlertData; 128 129 /** 130 * @internal Initializes the Alert system 131 * 132 * @param[in] pxBuffer Alert system buffer. 133 * 134 * @retval DFM_FAIL Failure 135 * @retval DFM_SUCCESS Success 136 */ 137 DfmResult_t xDfmAlertInitialize(DfmAlertData_t* pxBuffer); 138 139 /** 140 * @brief Retrieve Alert version from Alert handle 141 * 142 * @param[in] pvSession Session data. 143 * @param[out] pucVersion Pointer to version. 144 * 145 * @retval DFM_FAIL Failure 146 * @retval DFM_SUCCESS Success 147 */ 148 DfmResult_t xDfmAlertGetVersion(DfmAlertHandle_t xAlertHandle, uint8_t * pucVersion); 149 150 /** 151 * @brief Retrieve product id from Alert handle 152 * 153 * @param[in] pvSession Session data. 154 * @param[out] pulProduct Pointer to product id. 155 * 156 * @retval DFM_FAIL Failure 157 * @retval DFM_SUCCESS Success 158 */ 159 DfmResult_t xDfmAlertGetProduct(DfmAlertHandle_t xAlertHandle, uint32_t* pulProduct); 160 161 /** 162 * @brief Retrieve Firmware version from Alert handle 163 * 164 * @param[in] xAlertHandle Alert handle. 165 * @param[out] pszFirmwareVersion Pointer to firmware version. 166 * 167 * @retval DFM_FAIL Failure 168 * @retval DFM_SUCCESS Success 169 */ 170 DfmResult_t xDfmAlertGetFirmwareVersion(DfmAlertHandle_t xAlertHandle, const char** pszFirmwareVersion); 171 172 /** 173 * @brief Reset Alert 174 * 175 * @param[in] xAlertHandle Alert handle. 176 * 177 * @retval DFM_FAIL Failure 178 * @retval DFM_SUCCESS Success 179 */ 180 DfmResult_t xDfmAlertReset(DfmAlertHandle_t xAlertHandle); 181 182 /** 183 * @brief Begins creation of Alert 184 * 185 * @param[in] ulAlertType Type of Alert. 186 * @param[in] szAlertDescription Alert description. 187 * @param[out] pxAlertHandle Alert handle. 188 * 189 * @retval DFM_FAIL Failure 190 * @retval DFM_SUCCESS Success 191 */ 192 DfmResult_t xDfmAlertBegin(uint32_t ulAlertType, const char* szAlertDescription, DfmAlertHandle_t* pxAlertHandle); 193 194 /** 195 * @brief Ends Alert creation and sends/stores it 196 * 197 * @param[in] xAlertHandle Alert handle. 198 * 199 * @retval DFM_FAIL Failure 200 * @retval DFM_SUCCESS Success 201 */ 202 DfmResult_t xDfmAlertEnd(DfmAlertHandle_t xAlertHandle); 203 204 /** 205 * @brief Ends Alert creation by only storing it 206 * 207 * @param[in] xAlertHandle Alert handle. 208 * 209 * @retval DFM_FAIL Failure 210 * @retval DFM_SUCCESS Success 211 */ 212 DfmResult_t xDfmAlertEndOffline(DfmAlertHandle_t xAlertHandle); 213 214 /** 215 * @brief Add Symptom to Alert 216 * 217 * @param[in] xAlertHandle Alert handle. 218 * @param[in] ulSymptomId Symptom ID. 219 * @param[in] ulValue Symptom value. 220 * 221 * @retval DFM_FAIL Failure 222 * @retval DFM_SUCCESS Success 223 */ 224 DfmResult_t xDfmAlertAddSymptom(DfmAlertHandle_t xAlertHandle, uint32_t ulSymptomId, uint32_t ulValue); 225 226 /** 227 * @brief Get Symptom from Alert 228 * 229 * @param[in] xAlertHandle Alert handle. 230 * @param[in] ulIndex Symptom index. 231 * @param[out] pulSymptomId Symptom ID. 232 * @param[out] pulValue Symptom value. 233 * 234 * @retval DFM_FAIL Failure 235 * @retval DFM_SUCCESS Success 236 */ 237 DfmResult_t xDfmAlertGetSymptom(DfmAlertHandle_t xAlertHandle, uint32_t ulIndex, uint32_t *pulSymptomId, uint32_t *pulValue); 238 239 /** 240 * @brief Add Payload to Alert 241 * 242 * @param[in] xAlertHandle Alert handle. 243 * @param[in] pvData Pointer to Payload. 244 * @param[in] ulSize Payload size. 245 * @param[in] szDescription Payload description. 246 * 247 * @retval DFM_FAIL Failure 248 * @retval DFM_SUCCESS Success 249 */ 250 DfmResult_t xDfmAlertAddPayload(DfmAlertHandle_t xAlertHandle, void* pvData, uint32_t ulSize, const char* szDescription); 251 252 /** 253 * @brief Get Payload from Alert 254 * 255 * @param[in] xAlertHandle Alert handle. 256 * @param[in] ulIndex Symptom index. 257 * @param[out] ppvData Payload pointer. 258 * @param[out] pulSize Payload size. 259 * @param[out] pszDescription Payload description. 260 * 261 * @retval DFM_FAIL Failure 262 * @retval DFM_SUCCESS Success 263 */ 264 DfmResult_t xDfmAlertGetPayload(DfmAlertHandle_t xAlertHandle, uint32_t ulIndex, void** ppvData, uint32_t* pulSize, char **pszDescription); 265 266 /** 267 * @brief Get Payload Type from Alert 268 * 269 * @param[in] xAlertHandle Alert handle. 270 * @param[out] pulAlertType Payload type. 271 * 272 * @retval DFM_FAIL Failure 273 * @retval DFM_SUCCESS Success 274 */ 275 DfmResult_t xDfmAlertGetType(DfmAlertHandle_t xAlertHandle, uint32_t* pulAlertType); 276 277 /** 278 * @brief Retrieve Alert description 279 * 280 * @param[in] xAlertHandle Alert handle. 281 * @param[out] pszAlertDescription Alert description. 282 * 283 * @retval DFM_FAIL Failure 284 * @retval DFM_SUCCESS Success 285 */ 286 DfmResult_t xDfmAlertGetDescription(DfmAlertHandle_t xAlertHandle, const char** pszAlertDescription); 287 288 /** 289 * @brief Send all stored Alerts 290 * 291 * @retval DFM_FAIL Failure 292 * @retval DFM_SUCCESS Success 293 */ 294 DfmResult_t xDfmAlertSendAll(void); 295 296 /** 297 * @brief Get all stored Alerts 298 * 299 * @param[in] xCallback The callback that will be called for every stored Alert/Payload Entry 300 * 301 * @retval DFM_FAIL Failure 302 * @retval DFM_SUCCESS Success 303 */ 304 DfmResult_t xDfmAlertGetAll(DfmAlertEntryCallback_t xCallback); 305 306 /** @} */ 307 308 #else 309 310 /* Dummy defines */ 311 #define xDfmAlertGetVersion(xAlertHandle, pucVersion) 312 #define xDfmAlertGetId(xAlertHandle, pulAlertId) 313 #define xDfmAlertGetProduct(xAlertHandle, pulProduct) 314 #define xDfmAlertGetFirmwareVersion(xAlertHandle, pszFirmwareVersion) 315 #define xDfmAlertReset(xAlertHandle) 316 #define xDfmAlertBegin(ulAlertType, szAlertDescription, pxAlertHandle) 317 #define xDfmAlertEnd(xAlertHandle) 318 #define xDfmAlertAddSymptom(xAlertHandle, ulSymptomId, ulValue) 319 #define xDfmAlertGetSymptom(xAlertHandle, ulIndex, pulSymptomId, pulValue) 320 #define xDfmAlertAddPayload(xAlertHandle, pvData, ulSize, szDescription) 321 #define xDfmAlertAddTracePayload(xAlertHandle) 322 #define xDfmAlertGetPayload(xAlertHandle, ulIndex, ppvData, pulSize, pszDescription) 323 #define xDfmAlertGetType(xAlertHandle, pulAlertType) 324 #define xDfmAlertGetDescription(xAlertHandle, pszAlertDescription) 325 #define xDfmAlertSendAll() 326 #define xDfmAlertGetAll(xCallback) 327 328 #endif 329 330 #ifdef __cplusplus 331 } 332 #endif 333 334 #endif 335
