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 Entry 13 */ 14 15 #ifndef DFM_ENTRY_H 16 #define DFM_ENTRY_H 17 18 #include <dfmTypes.h> 19 #include <dfmConfig.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #if ((DFM_CFG_ENABLED) >= 1) 26 27 /** 28 * @defgroup dfm_entry_api DFM Entry API 29 * @ingroup dfm_apis 30 * @{ 31 */ 32 33 34 /** 35 * @brief Entry system data 36 */ 37 typedef struct DfmEntryData 38 { 39 uint32_t ulInitialized; 40 uint8_t buffer[(uint32_t)(DFM_CFG_MAX_PAYLOAD_CHUNK_SIZE) + 128UL]; /* We don't set it to exact size since we might need to read old/new DFM Entry versions that don't match exactly */ 41 } DfmEntryData_t; 42 43 /** 44 * @internal Initializes the Entry system 45 * 46 * @param[in] pxBuffer Entry system buffer. 47 * 48 * @retval DFM_FAIL Failure 49 * @retval DFM_SUCCESS Success 50 */ 51 DfmResult_t xDfmEntryInitialize(DfmEntryData_t* pxBuffer); 52 53 /** 54 * @brief Get the Entry system buffer pointer and size. 55 * 56 * @param[out] ppvBuffer Pointer to buffer. 57 * @param[out] pulBufferSize Buffer size. 58 * 59 * @retval DFM_FAIL Failure 60 * @retval DFM_SUCCESS Success 61 */ 62 DfmResult_t xDfmEntryGetBuffer(void** ppvBuffer, uint32_t* pulBufferSize); 63 64 /** 65 * @brief Create an Alert Entry from Alert handle. 66 * 67 * @param[in] xAlertHandle Alert handle. 68 * @param[out] pxEntryHandle Pointer to Entry handle. 69 * 70 * @retval DFM_FAIL Failure 71 * @retval DFM_SUCCESS Success 72 */ 73 DfmResult_t xDfmEntryCreateAlert(DfmAlertHandle_t xAlertHandle, DfmEntryHandle_t *pxEntryHandle); 74 75 /** 76 * @brief Create an Payload Header Entry from Alert handle and Payload information. 77 * 78 * @param[in] xAlertHandle Alert handle. 79 * @param[in] usEntryId Entry Id. 80 * @param[in] ulPayloadSize Payload size. 81 * @param[in] szDescription Payload description. 82 * @param[out] pxEntryHandle Pointer to Entry handle. 83 * 84 * @retval DFM_FAIL Failure 85 * @retval DFM_SUCCESS Success 86 */ 87 DfmResult_t xDfmEntryCreatePayloadHeader(DfmAlertHandle_t xAlertHandle, uint16_t usEntryId, uint32_t ulPayloadSize, char* szDescription, DfmEntryHandle_t* pxEntryHandle); 88 89 /** 90 * @brief Create an Payload chunk Entry from Alert handle and Payload chunk information. 91 * 92 * @param[in] xAlertHandle Alert handle. 93 * @param[in] usEntryId Entry Id. 94 * @param[in] usChunkIndex This chunk's index. 95 * @param[in] usChunkCount Payload's total chunk count. 96 * @param[in] pvPayload Pointer to Payload chunk. 97 * @param[in] ulSize Payload chunk size. 98 * @param[in] szDescription Payload description. 99 * @param[out] pxEntryHandle Pointer to Entry handle. 100 * 101 * @retval DFM_FAIL Failure 102 * @retval DFM_SUCCESS Success 103 */ 104 DfmResult_t xDfmEntryCreatePayloadChunk(DfmAlertHandle_t xAlertHandle, uint16_t usEntryId, uint16_t usChunkIndex, uint16_t usChunkCount, void* pvPayload, uint32_t ulSize, char* szDescription, DfmEntryHandle_t* pxEntryHandle); 105 106 /** 107 * @brief Create an Alert Entry from the Entry system buffer. 108 * 109 * @param[out] pxEntryHandle Pointer to Entry handle. 110 * 111 * @retval DFM_FAIL Failure 112 * @retval DFM_SUCCESS Success 113 */ 114 DfmResult_t xDfmEntryCreateAlertFromBuffer(DfmEntryHandle_t* pxEntryHandle); 115 116 /** 117 * @brief Create a Payload chunk Entry from the Entry system buffer. 118 * 119 * @param[in] szSessionId Session Id. 120 * @param[in] ulAlertId Alert Id. 121 * @param[out] pxEntryHandle Pointer to Entry handle. 122 * 123 * @retval DFM_FAIL Failure 124 * @retval DFM_SUCCESS Success 125 */ 126 DfmResult_t xDfmEntryCreatePayloadChunkFromBuffer(const char* szSessionId, uint32_t ulAlertId, DfmEntryHandle_t* pxEntryHandle); 127 128 /** 129 * @brief Get the Entry size from Entry handle. 130 * 131 * @param[in] xEntryHandle Entry handle. 132 * @param[out] pulSize Entry size. 133 * 134 * @retval DFM_FAIL Failure 135 * @retval DFM_SUCCESS Success 136 */ 137 DfmResult_t xDfmEntryGetSize(DfmEntryHandle_t xEntryHandle, uint32_t* pulSize); 138 139 /** 140 * @brief Get the start markers from Entry handle. 141 * 142 * @param[in] xEntryHandle Entry handle. 143 * @param[out] pucMarkersBuffer Pointer to start markers. 144 * 145 * @retval DFM_FAIL Failure 146 * @retval DFM_SUCCESS Success 147 */ 148 DfmResult_t xDfmEntryGetStartMarkers(DfmEntryHandle_t xEntryHandle, uint8_t** pucMarkersBuffer); 149 150 /** 151 * @brief Get the endianess from Entry handle. 152 * 153 * @param[in] xEntryHandle Entry handle. 154 * @param[out] pusEndianess Pointer to endianess. 155 * 156 * @retval DFM_FAIL Failure 157 * @retval DFM_SUCCESS Success 158 */ 159 DfmResult_t xDfmEntryGetEndianess(DfmEntryHandle_t xEntryHandle, uint16_t* pusEndianess); 160 161 /** 162 * @brief Get the version from Entry handle. 163 * 164 * @param[in] xEntryHandle Entry handle. 165 * @param[out] pusVersion Pointer to version. 166 * 167 * @retval DFM_FAIL Failure 168 * @retval DFM_SUCCESS Success 169 */ 170 DfmResult_t xDfmEntryGetVersion(DfmEntryHandle_t xEntryHandle, uint16_t* pusVersion); 171 172 /** 173 * @brief Get the Entry type from Entry handle. 174 * 175 * @param[in] xEntryHandle Entry handle. 176 * @param[out] pusType Pointer to Entry type. 177 * 178 * @retval DFM_FAIL Failure 179 * @retval DFM_SUCCESS Success 180 */ 181 DfmResult_t xDfmEntryGetType(DfmEntryHandle_t xEntryHandle, uint16_t* pusType); 182 183 /** 184 * @brief Get the Entry Id from Entry handle. 185 * 186 * @param[in] xEntryHandle Entry handle. 187 * @param[out] pusEntryId Pointer to Entry Id. 188 * 189 * @retval DFM_FAIL Failure 190 * @retval DFM_SUCCESS Success 191 */ 192 DfmResult_t xDfmEntryGetEntryId(DfmEntryHandle_t xEntryHandle, uint16_t* pusEntryId); 193 194 /** 195 * @brief Get the chunk index from Entry handle. 196 * 197 * @param[in] xEntryHandle Entry handle. 198 * @param[out] pusChunkIndex Pointer to chunk index. 199 * 200 * @retval DFM_FAIL Failure 201 * @retval DFM_SUCCESS Success 202 */ 203 DfmResult_t xDfmEntryGetChunkIndex(DfmEntryHandle_t xEntryHandle, uint16_t* pusChunkIndex); 204 205 /** 206 * @brief Get the chunk count from Entry handle. 207 * 208 * @param[in] xEntryHandle Entry handle. 209 * @param[out] pusChunkCount Pointer to chunk count. 210 * 211 * @retval DFM_FAIL Failure 212 * @retval DFM_SUCCESS Success 213 */ 214 DfmResult_t xDfmEntryGetChunkCount(DfmEntryHandle_t xEntryHandle, uint16_t* pusChunkCount); 215 216 /** 217 * @brief Get the Session Id size from Entry handle. 218 * 219 * @param[in] xEntryHandle Entry handle. 220 * @param[out] pusSize Pointer to Session Id size. 221 * 222 * @retval DFM_FAIL Failure 223 * @retval DFM_SUCCESS Success 224 */ 225 DfmResult_t xDfmEntryGetSessionIdSize(DfmEntryHandle_t xEntryHandle, uint16_t* pusSize); 226 227 /** 228 * @brief Get the Device Name size from Entry handle. 229 * 230 * @param[in] xEntryHandle Entry handle. 231 * @param[out] pusSize Pointer to Device Name size. 232 * 233 * @retval DFM_FAIL Failure 234 * @retval DFM_SUCCESS Success 235 */ 236 DfmResult_t xDfmEntryGetDeviceNameSize(DfmEntryHandle_t xEntryHandle, uint16_t* pusSize); 237 238 /** 239 * @brief Get the description size from Entry handle. 240 * 241 * @param[in] xEntryHandle Entry handle. 242 * @param[out] pusSize Pointer to description size. 243 * 244 * @retval DFM_FAIL Failure 245 * @retval DFM_SUCCESS Success 246 */ 247 DfmResult_t xDfmEntryGetDescriptionSize(DfmEntryHandle_t xEntryHandle, uint16_t* pusSize); 248 249 /** 250 * @brief Get the data size from Entry handle. 251 * 252 * @param[in] xEntryHandle Entry handle. 253 * @param[out] pulSize Pointer to data size. 254 * 255 * @retval DFM_FAIL Failure 256 * @retval DFM_SUCCESS Success 257 */ 258 DfmResult_t xDfmEntryGetDataSize(DfmEntryHandle_t xEntryHandle, uint32_t* pulSize); 259 260 /** 261 * @brief Get the Alert Id from Entry handle. 262 * 263 * @param[in] xEntryHandle Entry handle. 264 * @param[out] pulAlertId Pointer to Alert Id. 265 * 266 * @retval DFM_FAIL Failure 267 * @retval DFM_SUCCESS Success 268 */ 269 DfmResult_t xDfmEntryGetAlertId(DfmEntryHandle_t xEntryHandle, uint32_t* pulAlertId); 270 271 /** 272 * @brief Get the Session Id from Entry handle 273 * 274 * @param[in] xEntryHandle Entry handle. 275 * @param[out] pszSessionId Pointer to Session Id. 276 * 277 * @retval DFM_FAIL Failure 278 * @retval DFM_SUCCESS Success 279 */ 280 DfmResult_t xDfmEntryGetSessionId(DfmEntryHandle_t xEntryHandle, const char** pszSessionId); 281 282 /** 283 * @brief Get the Device Name from Entry handle 284 * 285 * @param[in] xEntryHandle Entry handle. 286 * @param[out] pszDeviceName Pointer to Device Name. 287 * 288 * @retval DFM_FAIL Failure 289 * @retval DFM_SUCCESS Success 290 */ 291 DfmResult_t xDfmEntryGetDeviceName(DfmEntryHandle_t xEntryHandle, const char** pszDeviceName); 292 293 /** 294 * @brief Get the description from Entry handle. 295 * 296 * @param[in] xEntryHandle Entry handle. 297 * @param[out] pszDescription Pointer to description. 298 * 299 * @retval DFM_FAIL Failure 300 * @retval DFM_SUCCESS Success 301 */ 302 DfmResult_t xDfmEntryGetDescription(DfmEntryHandle_t xEntryHandle, const char** pszDescription); 303 304 /** 305 * @brief Get the data from Entry handle. 306 * 307 * @param[in] xEntryHandle Entry handle. 308 * @param[out] ppvData Pointer to data. 309 * 310 * @retval DFM_FAIL Failure 311 * @retval DFM_SUCCESS Success 312 */ 313 DfmResult_t xDfmEntryGetData(DfmEntryHandle_t xEntryHandle, void** ppvData); 314 315 /** 316 * @brief Get the end markers from Entry handle. 317 * 318 * @param[in] xEntryHandle Entry handle. 319 * @param[out] pucMarkersBuffer Pointer to end markers. 320 * 321 * @retval DFM_FAIL Failure 322 * @retval DFM_SUCCESS Success 323 */ 324 DfmResult_t xDfmEntryGetEndMarkers(DfmEntryHandle_t xEntryHandle, uint8_t** pucMarkersBuffer); 325 326 /** @} */ 327 328 #else 329 330 /* Dummy defines */ 331 #define xDfmEntryGetBuffer(ppvBuffer, pulBufferSize) (DFM_FAIL) 332 #define xDfmEntryCreateAlert(xAlertHandle, pxEntryHandle) (DFM_FAIL) 333 #define xDfmEntryCreatePayloadHeader(xAlertHandle, usEntryId, ulPayloadSize, szDescription, pxEntryHandle) (DFM_FAIL) 334 #define xDfmEntryCreatePayloadChunk(xAlertHandle, usEntryId, usChunkIndex, usChunkCount, pvPayload, ulSize, szDescription, pxEntryHandle) (DFM_FAIL) 335 #define xDfmEntryCreateAlertFromBuffer(pxEntryHandle) (DFM_FAIL) 336 #define xDfmEntryCreatePayloadChunkFromBuffer(szSessionId, ulAlertId, pxEntryHandle) (DFM_FAIL) 337 #define xDfmEntryGetSize(xEntryHandle, pulSize) (DFM_FAIL) 338 #define xDfmEntryGetStartMarkers(xEntryHandle, pucMarkersBuffer) (DFM_FAIL) 339 #define xDfmEntryGetEndianess(xEntryHandle, pusEndianess) (DFM_FAIL) 340 #define xDfmEntryGetVersion(xEntryHandle, pusVersion) (DFM_FAIL) 341 #define xDfmEntryGetType(xEntryHandle, pusType) (DFM_FAIL) 342 #define xDfmEntryGetEntryId(xEntryHandle, pusEntryId) (DFM_FAIL) 343 #define xDfmEntryGetChunkIndex(xEntryHandle, pusChunkIndex) (DFM_FAIL) 344 #define xDfmEntryGetChunkCount(xEntryHandle, pusChunkCount) (DFM_FAIL) 345 #define xDfmEntryGetSessionIdSize(xEntryHandle, pusSize) (DFM_FAIL) 346 #define xDfmEntryGetDescriptionSize(xEntryHandle, pusSize) (DFM_FAIL) 347 #define xDfmEntryGetDataSize(xEntryHandle, pulSize) (DFM_FAIL) 348 #define xDfmEntryGetAlertId(xEntryHandle, pulAlertId) (DFM_FAIL) 349 #define xDfmEntryGetSessionId(xEntryHandle, pszSessionId) (DFM_FAIL) 350 #define xDfmEntryGetDescription(xEntryHandle, pszDescription) (DFM_FAIL) 351 #define xDfmEntryGetData(xEntryHandle, ppvData) (DFM_FAIL) 352 #define xDfmEntryGetEndMarkers(xEntryHandle, pucMarkersBuffer) (DFM_FAIL) 353 354 #endif 355 356 #ifdef __cplusplus 357 } 358 #endif 359 360 #endif 361
