1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2017-2019 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without modification, 8 * are permitted provided that the following conditions are met: 9 * 10 * o Redistributions of source code must retain the above copyright notice, this list 11 * of conditions and the following disclaimer. 12 * 13 * o Redistributions in binary form must reproduce the above copyright notice, this 14 * list of conditions and the following disclaimer in the documentation and/or 15 * other materials provided with the distribution. 16 * 17 * o Neither the name of the copyright holder nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 25 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*! 34 * Header file containing the public API for the System Controller (SC) 35 * Timer function. 36 * 37 * @addtogroup TIMER_SVC TIMER: Timer Service 38 * 39 * Module for the Timer service. This includes support for the watchdog, RTC, 40 * and system counter. Note every resource partition has a watchdog it can 41 * use. 42 * 43 * @{ 44 */ 45 46 #ifndef SC_TIMER_API_H 47 #define SC_TIMER_API_H 48 49 /* Includes */ 50 51 #include "main/types.h" 52 #include "svc/rm/rm_api.h" 53 54 /* Defines */ 55 56 /*! 57 * @name Defines for type widths 58 */ 59 /*@{*/ 60 #define SC_TIMER_ACTION_W 3U /*!< Width of sc_timer_wdog_action_t */ 61 /*@}*/ 62 63 /*! 64 * @name Defines for sc_timer_wdog_action_t 65 */ 66 /*@{*/ 67 #define SC_TIMER_WDOG_ACTION_PARTITION 0U /*!< Reset partition */ 68 #define SC_TIMER_WDOG_ACTION_WARM 1U /*!< Warm reset system */ 69 #define SC_TIMER_WDOG_ACTION_COLD 2U /*!< Cold reset system */ 70 #define SC_TIMER_WDOG_ACTION_BOARD 3U /*!< Reset board */ 71 #define SC_TIMER_WDOG_ACTION_IRQ 4U /*!< Only generate IRQs */ 72 /*@}*/ 73 74 /* Types */ 75 76 /*! 77 * This type is used to configure the watchdog action. 78 */ 79 typedef uint8_t sc_timer_wdog_action_t; 80 81 /*! 82 * This type is used to declare a watchdog time value in milliseconds. 83 */ 84 typedef uint32_t sc_timer_wdog_time_t; 85 86 /* Functions */ 87 88 /*! 89 * @name Watchdog Functions 90 * @{ 91 */ 92 93 /*! 94 * This function sets the watchdog timeout in milliseconds. If not 95 * set then the timeout defaults to the max. Once locked this value 96 * cannot be changed. 97 * 98 * @param[in] ipc IPC handle 99 * @param[in] timeout timeout period for the watchdog 100 * 101 * @return Returns an error code (SC_ERR_NONE = success, SC_ERR_LOCKED 102 * = locked). 103 */ 104 sc_err_t sc_timer_set_wdog_timeout(sc_ipc_t ipc, 105 sc_timer_wdog_time_t timeout); 106 107 /*! 108 * This function sets the watchdog pre-timeout in milliseconds. If not 109 * set then the pre-timeout defaults to the max. Once locked this value 110 * cannot be changed. 111 * 112 * @param[in] ipc IPC handle 113 * @param[in] pre_timeout pre-timeout period for the watchdog 114 * 115 * When the pre-timout expires an IRQ will be generated. Note this timeout 116 * clears when the IRQ is triggered. An IRQ is generated for the failing 117 * partition and all of its child partitions. 118 * 119 * @return Returns an error code (SC_ERR_NONE = success). 120 */ 121 sc_err_t sc_timer_set_wdog_pre_timeout(sc_ipc_t ipc, 122 sc_timer_wdog_time_t pre_timeout); 123 124 /*! 125 * This function sets the watchdog window in milliseconds. If not 126 * set then the window defaults to the 0. Once locked this value 127 * cannot be changed. 128 * 129 * @param[in] ipc IPC handle 130 * @param[in] window window period for the watchdog 131 * 132 * @return Returns an error code (SC_ERR_NONE = success, SC_ERR_LOCKED 133 * = locked). 134 * 135 * Calling sc_timer_ping_wdog() before the window time has expired will 136 * result in the watchdog action being taken. 137 */ 138 sc_err_t sc_timer_set_wdog_window(sc_ipc_t ipc, 139 sc_timer_wdog_time_t window); 140 141 /*! 142 * This function starts the watchdog. 143 * 144 * @param[in] ipc IPC handle 145 * @param[in] lock boolean indicating the lock status 146 * 147 * @return Returns an error code (SC_ERR_NONE = success). 148 * 149 * Return errors: 150 * - SC_ERR_NOACCESS if caller's partition is not isolated 151 * 152 * If \a lock is set then the watchdog cannot be stopped or the timeout 153 * period changed. 154 * 155 * If the calling partition is not isolated then the wdog cannot be used. 156 * This is always the case if a non-secure partition is running on the same 157 * CPU as a secure partition (e.g. Linux under TZ). See sc_rm_partition_alloc(). 158 */ 159 sc_err_t sc_timer_start_wdog(sc_ipc_t ipc, sc_bool_t lock); 160 161 /*! 162 * This function stops the watchdog if it is not locked. 163 * 164 * @param[in] ipc IPC handle 165 * 166 * @return Returns an error code (SC_ERR_NONE = success, SC_ERR_LOCKED 167 * = locked). 168 */ 169 sc_err_t sc_timer_stop_wdog(sc_ipc_t ipc); 170 171 /*! 172 * This function pings (services, kicks) the watchdog resetting the time 173 * before expiration back to the timeout. 174 * 175 * @param[in] ipc IPC handle 176 * 177 * @return Returns an error code (SC_ERR_NONE = success). 178 */ 179 sc_err_t sc_timer_ping_wdog(sc_ipc_t ipc); 180 181 /*! 182 * This function gets the status of the watchdog. All arguments are 183 * in milliseconds. 184 * 185 * @param[in] ipc IPC handle 186 * @param[out] timeout pointer to return the timeout 187 * @param[out] max_timeout pointer to return the max timeout 188 * @param[out] remaining_time pointer to return the time remaining 189 * until trigger 190 * 191 * @return Returns an error code (SC_ERR_NONE = success). 192 */ 193 sc_err_t sc_timer_get_wdog_status(sc_ipc_t ipc, 194 sc_timer_wdog_time_t *timeout, sc_timer_wdog_time_t *max_timeout, 195 sc_timer_wdog_time_t *remaining_time); 196 197 /*! 198 * This function gets the status of the watchdog of a partition. All 199 * arguments are in milliseconds. 200 * 201 * @param[in] ipc IPC handle 202 * @param[in] pt partition to query 203 * @param[out] enb pointer to return enable status 204 * @param[out] timeout pointer to return the timeout 205 * @param[out] remaining_time pointer to return the time remaining 206 * until trigger 207 * 208 * @return Returns an error code (SC_ERR_NONE = success). 209 */ 210 sc_err_t sc_timer_pt_get_wdog_status(sc_ipc_t ipc, sc_rm_pt_t pt, sc_bool_t *enb, 211 sc_timer_wdog_time_t *timeout, sc_timer_wdog_time_t *remaining_time); 212 213 /*! 214 * This function configures the action to be taken when a watchdog 215 * expires. 216 * 217 * @param[in] ipc IPC handle 218 * @param[in] pt partition to affect 219 * @param[in] action action to take 220 * 221 * Default action is inherited from the parent. 222 * 223 * @return Returns an error code (SC_ERR_NONE = success). 224 * 225 * Return errors: 226 * - SC_ERR_PARM if invalid parameters, 227 * - SC_ERR_NOACCESS if caller's partition is not the SYSTEM owner, 228 * - SC_ERR_LOCKED if the watchdog is locked 229 */ 230 sc_err_t sc_timer_set_wdog_action(sc_ipc_t ipc, 231 sc_rm_pt_t pt, sc_timer_wdog_action_t action); 232 233 /* @} */ 234 235 /*! 236 * @name Real-Time Clock (RTC) Functions 237 * @{ 238 */ 239 240 /*! 241 * This function sets the RTC time. Only the owner of the SC_R_SYSTEM 242 * resource or a partition with access permissions to SC_R_SYSTEM can 243 * set the time. 244 * 245 * @param[in] ipc IPC handle 246 * @param[in] year year (min 1970) 247 * @param[in] mon month (1-12) 248 * @param[in] day day of the month (1-31) 249 * @param[in] hour hour (0-23) 250 * @param[in] min minute (0-59) 251 * @param[in] sec second (0-59) 252 * 253 * @return Returns an error code (SC_ERR_NONE = success). 254 * 255 * Return errors: 256 * - SC_ERR_PARM if invalid time/date parameters, 257 * - SC_ERR_NOACCESS if caller's partition cannot access SC_R_SYSTEM 258 */ 259 sc_err_t sc_timer_set_rtc_time(sc_ipc_t ipc, uint16_t year, uint8_t mon, 260 uint8_t day, uint8_t hour, uint8_t min, uint8_t sec); 261 262 /*! 263 * This function gets the RTC time. 264 * 265 * @param[in] ipc IPC handle 266 * @param[out] year pointer to return year (min 1970) 267 * @param[out] mon pointer to return month (1-12) 268 * @param[out] day pointer to return day of the month (1-31) 269 * @param[out] hour pointer to return hour (0-23) 270 * @param[out] min pointer to return minute (0-59) 271 * @param[out] sec pointer to return second (0-59) 272 * 273 * @return Returns an error code (SC_ERR_NONE = success). 274 */ 275 sc_err_t sc_timer_get_rtc_time(sc_ipc_t ipc, uint16_t *year, uint8_t *mon, 276 uint8_t *day, uint8_t *hour, uint8_t *min, uint8_t *sec); 277 278 /*! 279 * This function gets the RTC time in seconds since 1/1/1970. 280 * 281 * @param[in] ipc IPC handle 282 * @param[out] sec pointer to return second 283 * 284 * @return Returns an error code (SC_ERR_NONE = success). 285 */ 286 sc_err_t sc_timer_get_rtc_sec1970(sc_ipc_t ipc, uint32_t *sec); 287 288 /*! 289 * This function sets the RTC alarm. 290 * 291 * @param[in] ipc IPC handle 292 * @param[in] year year (min 1970) 293 * @param[in] mon month (1-12) 294 * @param[in] day day of the month (1-31) 295 * @param[in] hour hour (0-23) 296 * @param[in] min minute (0-59) 297 * @param[in] sec second (0-59) 298 * 299 * Note this alarm setting clears when the alarm is triggered. This is an 300 * absolute time. 301 * 302 * @return Returns an error code (SC_ERR_NONE = success). 303 * 304 * Return errors: 305 * - SC_ERR_PARM if invalid time/date parameters 306 */ 307 sc_err_t sc_timer_set_rtc_alarm(sc_ipc_t ipc, uint16_t year, uint8_t mon, 308 uint8_t day, uint8_t hour, uint8_t min, uint8_t sec); 309 310 /*! 311 * This function sets the RTC alarm (periodic mode). 312 * 313 * @param[in] ipc IPC handle 314 * @param[in] sec period in seconds 315 * 316 * @return Returns an error code (SC_ERR_NONE = success). 317 * 318 * Note this is a relative time. 319 * 320 * Return errors: 321 * - SC_ERR_PARM if invalid time/date parameters 322 */ 323 sc_err_t sc_timer_set_rtc_periodic_alarm(sc_ipc_t ipc, uint32_t sec); 324 325 /*! 326 * This function cancels the RTC alarm. 327 * 328 * @param[in] ipc IPC handle 329 * 330 * Note this alarm setting clears when the alarm is triggered. 331 * 332 * @return Returns an error code (SC_ERR_NONE = success). 333 * 334 * Return errors: 335 * - SC_ERR_PARM if invalid time/date parameters 336 */ 337 sc_err_t sc_timer_cancel_rtc_alarm(sc_ipc_t ipc); 338 339 /*! 340 * This function sets the RTC calibration value. Only the owner of the SC_R_SYSTEM 341 * resource or a partition with access permissions to SC_R_SYSTEM can set the 342 * calibration. 343 * 344 * @param[in] ipc IPC handle 345 * @param[in] count calibration count (-16 to 15) 346 * 347 * The calibration value is a 5-bit value including the sign bit, which is 348 * implemented in 2's complement. It is added or subtracted from the RTC on 349 * a periodic basis, once per 32768 cycles of the RTC clock. 350 * 351 * @return Returns an error code (SC_ERR_NONE = success). 352 */ 353 sc_err_t sc_timer_set_rtc_calb(sc_ipc_t ipc, int8_t count); 354 355 /* @} */ 356 357 /*! 358 * @name System Counter (SYSCTR) Functions 359 * @{ 360 */ 361 362 /*! 363 * This function sets the SYSCTR alarm. 364 * 365 * @param[in] ipc IPC handle 366 * @param[in] ticks number of 8MHz cycles 367 * 368 * Note the \a ticks parameter is an absolute time. This alarm 369 * setting clears when the alarm is triggered. 370 * 371 * @return Returns an error code (SC_ERR_NONE = success). 372 * 373 * Return errors: 374 * - SC_ERR_PARM if invalid time/date parameters 375 */ 376 sc_err_t sc_timer_set_sysctr_alarm(sc_ipc_t ipc, uint64_t ticks); 377 378 /*! 379 * This function sets the SYSCTR alarm (periodic mode). 380 * 381 * @param[in] ipc IPC handle 382 * @param[in] ticks number of 8MHz cycles 383 * 384 * Note the \a ticks parameter is a relative time. 385 * 386 * @return Returns an error code (SC_ERR_NONE = success). 387 * 388 * Return errors: 389 * - SC_ERR_PARM if invalid time/date parameters 390 */ 391 sc_err_t sc_timer_set_sysctr_periodic_alarm(sc_ipc_t ipc, 392 uint64_t ticks); 393 394 /*! 395 * This function cancels the SYSCTR alarm. 396 * 397 * @param[in] ipc IPC handle 398 * 399 * Note this alarm setting clears when the alarm is triggered. 400 * 401 * @return Returns an error code (SC_ERR_NONE = success). 402 * 403 * Return errors: 404 * - SC_ERR_PARM if invalid time/date parameters 405 */ 406 sc_err_t sc_timer_cancel_sysctr_alarm(sc_ipc_t ipc); 407 408 /* @} */ 409 410 #endif /* SC_TIMER_API_H */ 411 412 /**@}*/ 413 414
