1 /* 2 * Copyright (C) 2016 Freescale Semiconductor, Inc. 3 * Copyright 2017-2019 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 /*! 9 * Header file containing the public API for the System Controller (SC) 10 * Timer function. 11 * 12 * @addtogroup TIMER_SVC (SVC) Timer Service 13 * 14 * Module for the Timer service. This includes support for the watchdog, RTC, 15 * and system counter. Note every resource partition has a watchdog it can 16 * use. 17 * 18 * @{ 19 */ 20 21 #ifndef SC_TIMER_API_H 22 #define SC_TIMER_API_H 23 24 /* Includes */ 25 26 #include <sci/sci_types.h> 27 28 /* Defines */ 29 30 /*! 31 * @name Defines for type widths 32 */ 33 /*@{*/ 34 #define SC_TIMER_ACTION_W 3U /* Width of sc_timer_wdog_action_t */ 35 /*@}*/ 36 37 /*! 38 * @name Defines for sc_timer_wdog_action_t 39 */ 40 /*@{*/ 41 #define SC_TIMER_WDOG_ACTION_PARTITION 0U /* Reset partition */ 42 #define SC_TIMER_WDOG_ACTION_WARM 1U /* Warm reset system */ 43 #define SC_TIMER_WDOG_ACTION_COLD 2U /* Cold reset system */ 44 #define SC_TIMER_WDOG_ACTION_BOARD 3U /* Reset board */ 45 #define SC_TIMER_WDOG_ACTION_IRQ 4U /* Only generate IRQs */ 46 /*@}*/ 47 48 /* Types */ 49 50 /*! 51 * This type is used to configure the watchdog action. 52 */ 53 typedef uint8_t sc_timer_wdog_action_t; 54 55 /*! 56 * This type is used to declare a watchdog time value in milliseconds. 57 */ 58 typedef uint32_t sc_timer_wdog_time_t; 59 60 /* Functions */ 61 62 /*! 63 * @name Watchdog Functions 64 * @{ 65 */ 66 67 /*! 68 * This function sets the watchdog timeout in milliseconds. If not 69 * set then the timeout defaults to the max. Once locked this value 70 * cannot be changed. 71 * 72 * @param[in] ipc IPC handle 73 * @param[in] timeout timeout period for the watchdog 74 * 75 * @return Returns an error code (SC_ERR_NONE = success, SC_ERR_LOCKED 76 * = locked). 77 */ 78 sc_err_t sc_timer_set_wdog_timeout(sc_ipc_t ipc, sc_timer_wdog_time_t timeout); 79 80 /*! 81 * This function sets the watchdog pre-timeout in milliseconds. If not 82 * set then the pre-timeout defaults to the max. Once locked this value 83 * cannot be changed. 84 * 85 * @param[in] ipc IPC handle 86 * @param[in] pre_timeout pre-timeout period for the watchdog 87 * 88 * When the pre-timeout expires an IRQ will be generated. Note this timeout 89 * clears when the IRQ is triggered. An IRQ is generated for the failing 90 * partition and all of its child partitions. 91 * 92 * @return Returns an error code (SC_ERR_NONE = success). 93 */ 94 sc_err_t sc_timer_set_wdog_pre_timeout(sc_ipc_t ipc, 95 sc_timer_wdog_time_t pre_timeout); 96 97 /*! 98 * This function starts the watchdog. 99 * 100 * @param[in] ipc IPC handle 101 * @param[in] lock boolean indicating the lock status 102 * 103 * @return Returns an error code (SC_ERR_NONE = success). 104 * 105 * If \a lock is set then the watchdog cannot be stopped or the timeout 106 * period changed. 107 */ 108 sc_err_t sc_timer_start_wdog(sc_ipc_t ipc, sc_bool_t lock); 109 110 /*! 111 * This function stops the watchdog if it is not locked. 112 * 113 * @param[in] ipc IPC handle 114 * 115 * @return Returns an error code (SC_ERR_NONE = success, SC_ERR_LOCKED 116 * = locked). 117 */ 118 sc_err_t sc_timer_stop_wdog(sc_ipc_t ipc); 119 120 /*! 121 * This function pings (services, kicks) the watchdog resetting the time 122 * before expiration back to the timeout. 123 * 124 * @param[in] ipc IPC handle 125 * 126 * @return Returns an error code (SC_ERR_NONE = success). 127 */ 128 sc_err_t sc_timer_ping_wdog(sc_ipc_t ipc); 129 130 /*! 131 * This function gets the status of the watchdog. All arguments are 132 * in milliseconds. 133 * 134 * @param[in] ipc IPC handle 135 * @param[out] timeout pointer to return the timeout 136 * @param[out] max_timeout pointer to return the max timeout 137 * @param[out] remaining_time pointer to return the time remaining 138 * until trigger 139 * 140 * @return Returns an error code (SC_ERR_NONE = success). 141 */ 142 sc_err_t sc_timer_get_wdog_status(sc_ipc_t ipc, 143 sc_timer_wdog_time_t *timeout, 144 sc_timer_wdog_time_t *max_timeout, 145 sc_timer_wdog_time_t *remaining_time); 146 147 /*! 148 * This function gets the status of the watchdog of a partition. All 149 * arguments are in milliseconds. 150 * 151 * @param[in] ipc IPC handle 152 * @param[in] pt partition to query 153 * @param[out] enb pointer to return enable status 154 * @param[out] timeout pointer to return the timeout 155 * @param[out] remaining_time pointer to return the time remaining 156 * until trigger 157 * 158 * @return Returns an error code (SC_ERR_NONE = success). 159 */ 160 sc_err_t sc_timer_pt_get_wdog_status(sc_ipc_t ipc, sc_rm_pt_t pt, 161 sc_bool_t *enb, 162 sc_timer_wdog_time_t *timeout, 163 sc_timer_wdog_time_t *remaining_time); 164 165 /*! 166 * This function configures the action to be taken when a watchdog 167 * expires. 168 * 169 * @param[in] ipc IPC handle 170 * @param[in] pt partition to affect 171 * @param[in] action action to take 172 * 173 * Default action is inherited from the parent. 174 * 175 * @return Returns an error code (SC_ERR_NONE = success). 176 * 177 * Return errors: 178 * - SC_ERR_PARM if invalid parameters, 179 * - SC_ERR_NOACCESS if caller's partition is not the SYSTEM owner, 180 * - SC_ERR_LOCKED if the watchdog is locked 181 */ 182 sc_err_t sc_timer_set_wdog_action(sc_ipc_t ipc, 183 sc_rm_pt_t pt, sc_timer_wdog_action_t action); 184 185 /* @} */ 186 187 /*! 188 * @name Real-Time Clock (RTC) Functions 189 * @{ 190 */ 191 192 /*! 193 * This function sets the RTC time. Only the owner of the SC_R_SYSTEM 194 * resource can set the time. 195 * 196 * @param[in] ipc IPC handle 197 * @param[in] year year (min 1970) 198 * @param[in] mon month (1-12) 199 * @param[in] day day of the month (1-31) 200 * @param[in] hour hour (0-23) 201 * @param[in] min minute (0-59) 202 * @param[in] sec second (0-59) 203 * 204 * @return Returns an error code (SC_ERR_NONE = success). 205 * 206 * Return errors: 207 * - SC_ERR_PARM if invalid time/date parameters, 208 * - SC_ERR_NOACCESS if caller's partition is not the SYSTEM owner 209 */ 210 sc_err_t sc_timer_set_rtc_time(sc_ipc_t ipc, uint16_t year, uint8_t mon, 211 uint8_t day, uint8_t hour, uint8_t min, 212 uint8_t sec); 213 214 /*! 215 * This function gets the RTC time. 216 * 217 * @param[in] ipc IPC handle 218 * @param[out] year pointer to return year (min 1970) 219 * @param[out] mon pointer to return month (1-12) 220 * @param[out] day pointer to return day of the month (1-31) 221 * @param[out] hour pointer to return hour (0-23) 222 * @param[out] min pointer to return minute (0-59) 223 * @param[out] sec pointer to return second (0-59) 224 * 225 * @return Returns an error code (SC_ERR_NONE = success). 226 */ 227 sc_err_t sc_timer_get_rtc_time(sc_ipc_t ipc, uint16_t *year, uint8_t *mon, 228 uint8_t *day, uint8_t *hour, uint8_t *min, 229 uint8_t *sec); 230 231 /*! 232 * This function gets the RTC time in seconds since 1/1/1970. 233 * 234 * @param[in] ipc IPC handle 235 * @param[out] sec pointer to return second 236 * 237 * @return Returns an error code (SC_ERR_NONE = success). 238 */ 239 sc_err_t sc_timer_get_rtc_sec1970(sc_ipc_t ipc, uint32_t *sec); 240 241 /*! 242 * This function sets the RTC alarm. 243 * 244 * @param[in] ipc IPC handle 245 * @param[in] year year (min 1970) 246 * @param[in] mon month (1-12) 247 * @param[in] day day of the month (1-31) 248 * @param[in] hour hour (0-23) 249 * @param[in] min minute (0-59) 250 * @param[in] sec second (0-59) 251 * 252 * Note this alarm setting clears when the alarm is triggered. 253 * 254 * @return Returns an error code (SC_ERR_NONE = success). 255 * 256 * Return errors: 257 * - SC_ERR_PARM if invalid time/date parameters 258 */ 259 sc_err_t sc_timer_set_rtc_alarm(sc_ipc_t ipc, uint16_t year, uint8_t mon, 260 uint8_t day, uint8_t hour, uint8_t min, 261 uint8_t sec); 262 263 /*! 264 * This function sets the RTC alarm (periodic mode). 265 * 266 * @param[in] ipc IPC handle 267 * @param[in] sec period in seconds 268 * 269 * @return Returns an error code (SC_ERR_NONE = success). 270 * 271 * Return errors: 272 * - SC_ERR_PARM if invalid time/date parameters 273 */ 274 sc_err_t sc_timer_set_rtc_periodic_alarm(sc_ipc_t ipc, uint32_t sec); 275 276 /*! 277 * This function cancels the RTC alarm. 278 * 279 * @param[in] ipc IPC handle 280 * 281 * Note this alarm setting clears when the alarm is triggered. 282 * 283 * @return Returns an error code (SC_ERR_NONE = success). 284 * 285 * Return errors: 286 * - SC_ERR_PARM if invalid time/date parameters 287 */ 288 sc_err_t sc_timer_cancel_rtc_alarm(sc_ipc_t ipc); 289 290 /*! 291 * This function sets the RTC calibration value. Only the owner of the SC_R_SYSTEM 292 * resource can set the calibration. 293 * 294 * @param[in] ipc IPC handle 295 * @param[in] count calbration count (-16 to 15) 296 * 297 * The calibration value is a 5-bit value including the sign bit, which is 298 * implemented in 2's complement. It is added or subtracted from the RTC on 299 * a perdiodic basis, once per 32768 cycles of the RTC clock. 300 * 301 * @return Returns an error code (SC_ERR_NONE = success). 302 */ 303 sc_err_t sc_timer_set_rtc_calb(sc_ipc_t ipc, int8_t count); 304 305 /* @} */ 306 307 /*! 308 * @name System Counter (SYSCTR) Functions 309 * @{ 310 */ 311 312 /*! 313 * This function sets the SYSCTR alarm. 314 * 315 * @param[in] ipc IPC handle 316 * @param[in] ticks number of 8MHz cycles 317 * 318 * Note this alarm setting clears when the alarm is triggered. 319 * 320 * @return Returns an error code (SC_ERR_NONE = success). 321 * 322 * Return errors: 323 * - SC_ERR_PARM if invalid time/date parameters 324 */ 325 sc_err_t sc_timer_set_sysctr_alarm(sc_ipc_t ipc, uint64_t ticks); 326 327 /*! 328 * This function sets the SYSCTR alarm (periodic mode). 329 * 330 * @param[in] ipc IPC handle 331 * @param[in] ticks number of 8MHz cycles 332 * 333 * @return Returns an error code (SC_ERR_NONE = success). 334 * 335 * Return errors: 336 * - SC_ERR_PARM if invalid time/date parameters 337 */ 338 sc_err_t sc_timer_set_sysctr_periodic_alarm(sc_ipc_t ipc, uint64_t ticks); 339 340 /*! 341 * This function cancels the SYSCTR alarm. 342 * 343 * @param[in] ipc IPC handle 344 * 345 * Note this alarm setting clears when the alarm is triggered. 346 * 347 * @return Returns an error code (SC_ERR_NONE = success). 348 * 349 * Return errors: 350 * - SC_ERR_PARM if invalid time/date parameters 351 */ 352 sc_err_t sc_timer_cancel_sysctr_alarm(sc_ipc_t ipc); 353 354 /* @} */ 355 356 #endif /* SC_TIMER_API_H */ 357 358 /**@}*/ 359