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_SESSION_H 16 #define DFM_SESSION_H 17 18 #include <stdint.h> 19 #include <dfmTypes.h> 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #if ((DFM_CFG_ENABLED) >= 1) 26 27 /** 28 * @defgroup dfm_session_api DFM Session API 29 * @ingroup dfm_apis 30 * @{ 31 */ 32 33 34 /** 35 * @brief Session system data 36 */ 37 typedef struct DfmSessionData 38 { 39 uint32_t ulInitialized; 40 41 uint32_t ulEnabled; 42 43 DfmStorageStrategy_t xStorageStrategy; 44 DfmCloudStrategy_t xCloudStrategy; 45 DfmSessionIdStrategy_t xSessionIdStrategy; 46 47 /* The product number */ 48 uint32_t ulProduct; 49 50 /* DFM Status */ 51 uint32_t ulDfmStatus; 52 53 /* Firmware Version with a pre-calculated 4-byte aligned size with room for zero termination */ 54 char cFirmwareVersionBuffer[DFM_FIRMWARE_VERSION_MAX_LEN]; 55 56 char cDeviceNameBuffer[DFM_DEVICE_NAME_MAX_LEN]; /* The device name */ 57 58 char cUniqueSessionIdBuffer[DFM_SESSION_ID_MAX_LEN]; /* The Session ID */ 59 60 uint32_t ulAlertCounter; 61 } DfmSessionData_t; 62 63 /** 64 * @internal Initializes the Session system 65 * 66 * @param[in] pxBuffer Session system buffer. 67 * 68 * @retval DFM_FAIL Failure 69 * @retval DFM_SUCCESS Success 70 */ 71 DfmResult_t xDfmSessionInitialize(DfmSessionData_t* pxBuffer); 72 73 /** 74 * @brief Enable DFM. 75 * 76 * @param[in] ulOverride Flag indicating if it should override any previous disable calls. Setting this to 1 means that if for some reason it was decided to disable DFM on this device and it was stored to Flash, this Enable attempt will not do anything. 77 * 78 * @retval DFM_FAIL Failure 79 * @retval DFM_SUCCESS Success 80 */ 81 DfmResult_t xDfmSessionEnable(uint32_t ulOverride); 82 83 /** 84 * @brief Disable DFM. 85 * 86 * @param[in] ulRemember Flag indicating if the Disable should be stored in permanent storage. Setting this to 1 means that any reboots of the device will remember the "Disabled" flag and xDfmEnable(1) must be called to override and re-enable DFM. 87 * 88 * @retval DFM_FAIL Failure 89 * @retval DFM_SUCCESS Success 90 */ 91 DfmResult_t xDfmSessionDisable(uint32_t ulRemember); 92 93 /** 94 * @brief Query DFM enabled/disabled. 95 * 96 * @retval DFM_FAIL Failure 97 * @retval DFM_SUCCESS Success 98 */ 99 uint32_t ulDfmSessionIsEnabled(void); 100 101 /** 102 * @brief Set Session status. 103 * 104 * @param[in] ulStatus Status. 105 * 106 * @retval DFM_FAIL Failure 107 * @retval DFM_SUCCESS Success 108 */ 109 DfmResult_t xDfmSessionSetStatus(uint32_t ulStatus); 110 111 /** 112 * @brief Get Session status. 113 * 114 * @param[out] pulStatus Pointer to status. 115 * 116 * @retval DFM_FAIL Failure 117 * @retval DFM_SUCCESS Success 118 */ 119 DfmResult_t xDfmSessionGetStatus(uint32_t* pulStatus); 120 121 /** 122 * @brief Generate new Alert Id. 123 * 124 * @retval DFM_FAIL Failure 125 * @retval DFM_SUCCESS Success 126 */ 127 DfmResult_t xDfmSessionGenerateNewAlertId(void); 128 129 /** 130 * @brief Get Alert Id. 131 * 132 * @param[out] pulAlertId Pointer to Alert Id. 133 * 134 * @retval DFM_FAIL Failure 135 * @retval DFM_SUCCESS Success 136 */ 137 DfmResult_t xDfmSessionGetAlertId(uint32_t* pulAlertId); 138 139 /** 140 * @brief Get product. 141 * 142 * @param[out] pulProduct Pointer to product. 143 * 144 * @retval DFM_FAIL Failure 145 * @retval DFM_SUCCESS Success 146 */ 147 DfmResult_t xDfmSessionGetProduct(uint32_t* pulProduct); 148 149 /** 150 * @brief Get firmware version. 151 * 152 * @param[out] pszFirmwareVersionBuffer Pointer to firmware version. 153 * 154 * @retval DFM_FAIL Failure 155 * @retval DFM_SUCCESS Success 156 */ 157 DfmResult_t xDfmSessionGetFirmwareVersion(char **pszFirmwareVersionBuffer); 158 159 /** 160 * @brief Set device name 161 * 162 * @param[in] szDeviceName Device name. 163 * 164 * @retval DFM_FAIL Failure 165 * @retval DFM_SUCCESS Success 166 */ 167 DfmResult_t xDfmSessionSetDeviceName(const char* szDeviceName); 168 169 /** 170 * @brief Get device name 171 * 172 * @param[out] pszDeviceName Pointer to device name. 173 * 174 * @retval DFM_FAIL Failure 175 * @retval DFM_SUCCESS Success 176 */ 177 DfmResult_t xDfmSessionGetDeviceName(const char** pszDeviceName); 178 179 /** 180 * @brief Get Session Id. 181 * 182 * @param[in] pszUniqueSessionId Pointer to Session Id. 183 * 184 * @retval DFM_FAIL Failure 185 * @retval DFM_SUCCESS Success 186 */ 187 DfmResult_t xDfmSessionGetUniqueSessionId(char** pszUniqueSessionId); 188 189 /** 190 * @brief Set Cloud strategy. 191 * 192 * @param[in] xStrategy Cloud strategy. 193 * 194 * @retval DFM_FAIL Failure 195 * @retval DFM_SUCCESS Success 196 */ 197 DfmResult_t xDfmSessionSetCloudStrategy(DfmCloudStrategy_t xStrategy); 198 199 /** 200 * @brief Get Cloud strategy. 201 * 202 * @param[out] pxStrategy Pointer to Cloud strategy. 203 * 204 * @retval DFM_FAIL Failure 205 * @retval DFM_SUCCESS Success 206 */ 207 DfmResult_t xDfmSessionGetCloudStrategy(DfmCloudStrategy_t* pxStrategy); 208 209 /** 210 * @brief Set Storage strategy. 211 * 212 * @param[in] xStrategy Storage strategy. 213 * 214 * @retval DFM_FAIL Failure 215 * @retval DFM_SUCCESS Success 216 */ 217 DfmResult_t xDfmSessionSetStorageStrategy(DfmStorageStrategy_t xStrategy); 218 219 /** 220 * @brief Get Storage strategy. 221 * 222 * @param[out] pxStrategy Pointer to Storage strategy. 223 * 224 * @retval DFM_FAIL Failure 225 * @retval DFM_SUCCESS Success 226 */ 227 DfmResult_t xDfmSessionGetStorageStrategy(DfmStorageStrategy_t* pxStrategy); 228 229 /** 230 * @brief Set Session Id strategy. 231 * 232 * @param[in] xStrategy Session Id strategy. 233 * 234 * @retval DFM_FAIL Failure 235 * @retval DFM_SUCCESS Success 236 */ 237 DfmResult_t xDfmSessionSetSessionIdStrategy(DfmSessionIdStrategy_t xStrategy); 238 239 /** 240 * @brief Get Session Id strategy. 241 * 242 * @param[out] pxStrategy Pointer to Session Id strategy. 243 * 244 * @retval DFM_FAIL Failure 245 * @retval DFM_SUCCESS Success 246 */ 247 DfmResult_t xDfmSessionGetSessionIdStrategy(DfmSessionIdStrategy_t* pxStrategy); 248 249 /** @} */ 250 251 #else 252 253 /* Dummy defines */ 254 #define xDfmSessionEnable(ulOverride) (DFM_FAIL) 255 #define xDfmSessionDisable() (DFM_FAIL) 256 #define ulDfmSessionIsEnabled() (0) 257 #define xDfmSessionSetStatus(ulStatus) (DFM_FAIL) 258 #define xDfmSessionGetStatus(pulStatus) (DFM_FAIL) 259 #define xDfmSessionAssignAlertId(pulAlertId) (DFM_FAIL) 260 #define xDfmSessionGetProduct(pulProduct) (DFM_FAIL) 261 #define xDfmSessionGetFirmwareVersion(pszFirmwareVersionBuffer) (DFM_FAIL) 262 #define xDfmSessionGetDeviceName(pszDeviceName) (DFM_FAIL) 263 #define xDfmSessionGetUniqueSessionId(pszUniqueSessionId) (DFM_FAIL) 264 #define xDfmSessionSetAlertStrategy(xStrategy) (DFM_FAIL) 265 #define xDfmSessionGetAlertStrategy(pxStrategy) (DFM_FAIL) 266 #define xDfmSessionSetCloudStrategy(xStrategy) (DFM_FAIL) 267 #define xDfmSessionGetCloudStrategy(pxStrategy) (DFM_FAIL) 268 #define xDfmSessionSetStorageStrategy(xStrategy) (DFM_FAIL) 269 #define xDfmSessionGetStorageStrategy(pxStrategy) (DFM_FAIL) 270 #define xDfmSessionSetSessionIdStrategy(xStrategy) (DFM_FAIL) 271 #define xDfmSessionGetSessionIdStrategy(pxStrategy) (DFM_FAIL) 272 #define xDfmSessionSetDeviceNameStrategy(xStrategy) (DFM_FAIL) 273 #define xDfmSessionGetDeviceNameStrategy(pxStrategy) (DFM_FAIL) 274 275 #endif 276 277 #ifdef __cplusplus 278 } 279 #endif 280 281 #endif 282
