1 /* 2 * Percepio DFM v2.1.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 attempts to send, store or retain it, in that order. 196 * 197 * @param[in] xAlertHandle Alert handle. 198 * 199 * @retval DFM_FAIL Failure 200 * @retval DFM_SUCCESS Success 201 */ 202 #define xDfmAlertEnd(xAlertHandle) xDfmAlertEndCustom(xAlertHandle, DFM_ALERT_END_TYPE_ALL) 203 204 /** 205 * @brief Ends Alert creation and sends, stores or retains it depending on the supplied ulEndType parameter. 206 * The values can be combined to only attempt the appropriate types but the order will always be Send before Store before Retain. 207 * 208 * @param[in] xAlertHandle Alert handle. 209 * @param[in] ulEndType The type of commits to be attempted by the function. 210 * DFM_ALERT_END_TYPE_ALL: Send, store or retain the Alert, in that order. 211 * DFM_ALERT_END_TYPE_SEND: Send the Alert. 212 * DFM_ALERT_END_TYPE_STORE: Store the Alert. 213 * DFM_ALERT_END_TYPE_RETAIN: Retain the Alert. 214 * 215 * @retval DFM_FAIL Failure 216 * @retval DFM_SUCCESS Success 217 */ 218 DfmResult_t xDfmAlertEndCustom(DfmAlertHandle_t xAlertHandle, uint32_t ulEndType); 219 220 /** 221 * @brief Ends Alert creation by only storing it 222 * 223 * @param[in] xAlertHandle Alert handle. 224 * 225 * @retval DFM_FAIL Failure 226 * @retval DFM_SUCCESS Success 227 */ 228 DfmResult_t xDfmAlertEndOffline(DfmAlertHandle_t xAlertHandle); 229 230 /** 231 * @brief Ends Alert creation by only storing it in retained memory 232 * 233 * @param[in] xAlertHandle Alert handle. 234 * 235 * @retval DFM_FAIL Failure 236 * @retval DFM_SUCCESS Success 237 */ 238 DfmResult_t xDfmAlertEndRetainedMemory(DfmAlertHandle_t xAlertHandle); 239 240 /** 241 * @brief Add Symptom to Alert 242 * 243 * @param[in] xAlertHandle Alert handle. 244 * @param[in] ulSymptomId Symptom ID. 245 * @param[in] ulValue Symptom value. 246 * 247 * @retval DFM_FAIL Failure 248 * @retval DFM_SUCCESS Success 249 */ 250 DfmResult_t xDfmAlertAddSymptom(DfmAlertHandle_t xAlertHandle, uint32_t ulSymptomId, uint32_t ulValue); 251 252 /** 253 * @brief Get Symptom from Alert 254 * 255 * @param[in] xAlertHandle Alert handle. 256 * @param[in] ulIndex Symptom index. 257 * @param[out] pulSymptomId Symptom ID. 258 * @param[out] pulValue Symptom value. 259 * 260 * @retval DFM_FAIL Failure 261 * @retval DFM_SUCCESS Success 262 */ 263 DfmResult_t xDfmAlertGetSymptom(DfmAlertHandle_t xAlertHandle, uint32_t ulIndex, uint32_t *pulSymptomId, uint32_t *pulValue); 264 265 /** 266 * @brief Add Payload to Alert 267 * 268 * @param[in] xAlertHandle Alert handle. 269 * @param[in] pvData Pointer to Payload. 270 * @param[in] ulSize Payload size. 271 * @param[in] szDescription Payload description. 272 * 273 * @retval DFM_FAIL Failure 274 * @retval DFM_SUCCESS Success 275 */ 276 DfmResult_t xDfmAlertAddPayload(DfmAlertHandle_t xAlertHandle, void* pvData, uint32_t ulSize, const char* szDescription); 277 278 /** 279 * @brief Get Payload from Alert 280 * 281 * @param[in] xAlertHandle Alert handle. 282 * @param[in] ulIndex Symptom index. 283 * @param[out] ppvData Payload pointer. 284 * @param[out] pulSize Payload size. 285 * @param[out] pszDescription Payload description. 286 * 287 * @retval DFM_FAIL Failure 288 * @retval DFM_SUCCESS Success 289 */ 290 DfmResult_t xDfmAlertGetPayload(DfmAlertHandle_t xAlertHandle, uint32_t ulIndex, void** ppvData, uint32_t* pulSize, char **pszDescription); 291 292 /** 293 * @brief Get Payload Type from Alert 294 * 295 * @param[in] xAlertHandle Alert handle. 296 * @param[out] pulAlertType Payload type. 297 * 298 * @retval DFM_FAIL Failure 299 * @retval DFM_SUCCESS Success 300 */ 301 DfmResult_t xDfmAlertGetType(DfmAlertHandle_t xAlertHandle, uint32_t* pulAlertType); 302 303 /** 304 * @brief Retrieve Alert description 305 * 306 * @param[in] xAlertHandle Alert handle. 307 * @param[out] pszAlertDescription Alert description. 308 * 309 * @retval DFM_FAIL Failure 310 * @retval DFM_SUCCESS Success 311 */ 312 DfmResult_t xDfmAlertGetDescription(DfmAlertHandle_t xAlertHandle, const char** pszAlertDescription); 313 314 /** 315 * @brief Store any alerts in Retained Memory 316 * 317 * @retval DFM_FAIL Failure 318 * @retval DFM_SUCCESS Success 319 */ 320 DfmResult_t xDfmAlertStoreRetainedMemory(void); 321 322 /** 323 * @brief Send all stored Alerts 324 * 325 * @retval DFM_FAIL Failure 326 * @retval DFM_SUCCESS Success 327 */ 328 DfmResult_t xDfmAlertSendAll(void); 329 330 /** 331 * @brief Get all stored Alerts 332 * 333 * @param[in] xCallback The callback that will be called for every stored Alert/Payload Entry 334 * 335 * @retval DFM_FAIL Failure 336 * @retval DFM_SUCCESS Success 337 */ 338 DfmResult_t xDfmAlertGetAll(DfmAlertEntryCallback_t xCallback); 339 340 /** @} */ 341 342 #else 343 344 /* Dummy defines */ 345 #define xDfmAlertGetVersion(xAlertHandle, pucVersion) ((void)(xAlertHandle), (void)(pucVersion), DFM_FAIL) 346 #define xDfmAlertGetId(xAlertHandle, pulAlertId) ((void)(xAlertHandle), (void)(pulAlertId), DFM_FAIL) 347 #define xDfmAlertGetProduct(xAlertHandle, pulProduct) ((void)(xAlertHandle), (void)(pulProduct), DFM_FAIL) 348 #define xDfmAlertGetFirmwareVersion(xAlertHandle, pszFirmwareVersion) ((void)(xAlertHandle), (void)(pszFirmwareVersion), DFM_FAIL) 349 #define xDfmAlertReset(xAlertHandle) ((void)(xAlertHandle), DFM_FAIL) 350 #define xDfmAlertBegin(ulAlertType, szAlertDescription, pxAlertHandle) ((void)(ulAlertType), (void)(szAlertDescription), (void)(pxAlertHandle), DFM_FAIL) 351 #define xDfmAlertEnd(xAlertHandle) ((void)(xAlertHandle), DFM_FAIL) 352 #define xDfmAlertEndOffline(xAlertHandle ((void)(xAlertHandle), DFM_FAIL) 353 #define xDfmAlertEndRetainedMemory(xAlertHandle) ((void)(xAlertHandle), DFM_FAIL) 354 #define xDfmAlertAddSymptom(xAlertHandle, ulSymptomId, ulValue) ((void)(xAlertHandle), (void)(ulSymptomId), (void)(ulValue), DFM_FAIL) 355 #define xDfmAlertGetSymptom(xAlertHandle, ulIndex, pulSymptomId, pulValue) ((void)(xAlertHandle), (void)(ulIndex), (void)(pulSymptomId), (void)(pulValue), DFM_FAIL) 356 #define xDfmAlertAddPayload(xAlertHandle, pvData, ulSize, szDescription) ((void)(xAlertHandle), (void)(pvData), (void)(ulSize), (void)(szDescription), DFM_FAIL) 357 #define xDfmAlertAddTracePayload(xAlertHandle) ((void)(xAlertHandle), DFM_FAIL) 358 #define xDfmAlertGetPayload(xAlertHandle, ulIndex, ppvData, pulSize, pszDescription) ((void)(xAlertHandle), (void)(ulIndex), (void)(ppvData), (void)(pulSize), (void)(pszDescription), DFM_FAIL) 359 #define xDfmAlertGetType(xAlertHandle, pulAlertType) ((void)(xAlertHandle), (void)(pulAlertType), DFM_FAIL) 360 #define xDfmAlertGetDescription(xAlertHandle, pszAlertDescription) ((void)(xAlertHandle), (void)(pszAlertDescription), DFM_FAIL) 361 #define xDfmAlertStoreRetainedMemory() (DFM_FAIL) 362 #define xDfmAlertSendAll() (DFM_FAIL) 363 #define xDfmAlertGetAll(xCallback) ((void)(xCallback), DFM_FAIL) 364 365 #endif 366 367 #ifdef __cplusplus 368 } 369 #endif 370 371 #endif 372
