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 Retained Memory API
13  */
14 
15 #ifndef DFM_RETAINED_MEMORY_H
16 #define DFM_RETAINED_MEMORY_H
17 
18 #include <stdint.h>
19 #include <dfmConfig.h>
20 #include <dfmTypes.h>
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 #ifndef DFM_CFG_RETAINED_MEMORY
27 #define DFM_CFG_RETAINED_MEMORY 0
28 #endif
29 
30 #if (defined(DFM_CFG_ENABLED) && (DFM_CFG_ENABLED >= 1)) && (defined(DFM_CFG_RETAINED_MEMORY) && (DFM_CFG_RETAINED_MEMORY >= 1))
31 
32 #include <dfmRetainedMemoryPort.h>
33 
34 /**
35  * @defgroup dfm_alert_apis DFM Alert API
36  * @ingroup dfm_apis
37  * @{
38  */
39 
40 typedef struct DfmRetainedMemoryData
41 {
42 	uint32_t ulInitialized;
43 	uint32_t ulWriteOffset;
44 	uint32_t ulReadOffset;
45 	uint32_t alignment;
46 	DfmRetainedMemoryPortData_t xRetainedMemoryPortData;
47 } DfmRetainedMemoryData_t;
48 
49 /**
50  * @brief Initialize Retained Memory system
51  *
52  * @param[in] pxBuffer Retained Memory system buffer.
53  *
54  * @retval DFM_FAIL Failure
55  * @retval DFM_SUCCESS Success
56  */
57 DfmResult_t xDfmRetainedMemoryInitialize(DfmRetainedMemoryData_t *pxBuffer);
58 
59 /**
60  * @brief Write Alert Entry
61  *
62  * @param[in] xEntryHandle Entry handle.
63  *
64  * @retval DFM_FAIL Failure
65  * @retval DFM_SUCCESS Success
66  */
67 DfmResult_t xDfmRetainedMemoryWriteAlert(DfmEntryHandle_t xEntryHandle);
68 
69 /**
70  * @brief Read Alert Entry
71  *
72  * @param[in] pvBuffer Pointer to Alert Entry buffer.
73  * @param[in] ulBufferSize Alert Entry buffer size.
74  *
75  * @retval DFM_FAIL Failure
76  * @retval DFM_SUCCESS Success
77  */
78 DfmResult_t xDfmRetainedMemoryReadAlert(void* pvBuffer, uint32_t ulBufferSize);
79 
80 /**
81  * @brief Write Payload chunk Entry
82  *
83  * @param[in] xEntryHandle Entry handle.
84  *
85  * @retval DFM_FAIL Failure
86  * @retval DFM_SUCCESS Success
87  */
88 DfmResult_t xDfmRetainedMemoryWritePayloadChunk(DfmEntryHandle_t xEntryHandle);
89 
90 /**
91  * @brief Read Payload chunk Entry
92  *
93  * @param[in] szSessionId Requested Session Id.
94  * @param[in] ulAlertId Requested Alert Id.
95  * @param[in] pvBuffer Pointer to Payload chunk Entry buffer.
96  * @param[in] ulBufferSize Payload chunk Entry buffer size.
97  *
98  * @retval DFM_FAIL Failure
99  * @retval DFM_SUCCESS Success
100  */
101 DfmResult_t xDfmRetainedMemoryReadPayloadChunk(char* szSessionId, uint32_t ulAlertId, void* pvBuffer, uint32_t ulBufferSize);
102 
103 /**
104  * @brief Clear all stored alerts from Retained Memory
105  *
106  * @retval DFM_FAIL Failure
107  * @retval DFM_SUCCESS Success
108  */
109 DfmResult_t xDfmRetainedMemoryClear(void);
110 
111 /** @} */
112 
113 #else
114 
115 #define xDfmRetainedMemoryInitialize(pxBuffer) ((void)(pxBuffer), DFM_SUCCESS)
116 #define xDfmRetainedMemoryWriteAlert(xEntryHandle, ulOverwrite) ((void)(xEntryHandle), (void)(ulOverwrite), DFM_FAIL)
117 #define xDfmRetainedMemoryReadAlert(pvBuffer, ulBufferSize) ((void)(pvBuffer), (void)(ulBufferSize), DFM_FAIL)
118 #define xDfmRetainedMemoryWritePayloadChunk(xEntryHandle, ulOverwrite) ((void)(xEntryHandle), (void)(ulOverwrite), DFM_FAIL)
119 #define xDfmRetainedMemoryReadPayloadChunk(szSessionId, ulAlertId, pvBuffer, ulBufferSize) ((void)(szSessionId), (void)(ulAlertId), (void)(pvBuffer), (void)(ulBufferSize), DFM_FAIL)
120 #define xDfmRetainedMemoryReset(void) (DFM_SUCCESS)
121 
122 #endif
123 
124 #ifdef __cplusplus
125 }
126 #endif
127 
128 #endif
129