git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/abstractions/platform/include/platform/iot_clock.h

   1 /*\r
   2  * Amazon FreeRTOS Platform V1.0.0\r
   3  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_clock.h\r
  28  * @brief Time-related functions used by libraries in this SDK.\r
  29  */\r
  30 \r
  31 #ifndef IOT_CLOCK_H_\r
  32 #define IOT_CLOCK_H_\r
  33 \r
  34 /* The config header is always included first. */\r
  35 #include "iot_config.h"\r
  36 \r
  37 /* Standard includes. */\r
  38 #include <stdbool.h>\r
  39 #include <stddef.h>\r
  40 #include <stdint.h>\r
  41 \r
  42 /* Platform layer types include. */\r
  43 #include "types/iot_platform_types.h"\r
  44 \r
  45 /**\r
  46  * @functionspage{platform_clock,platform clock component,Clock}\r
  47  * - @functionname{platform_clock_function_gettimestring}\r
  48  * - @functionname{platform_clock_function_gettimems}\r
  49  * - @functionname{platform_clock_function_sleepms}\r
  50  * - @functionname{platform_clock_function_timercreate}\r
  51  * - @functionname{platform_clock_function_timerdestroy}\r
  52  * - @functionname{platform_clock_function_timerarm}\r
  53  */\r
  54 \r
  55 /**\r
  56  * @functionpage{IotClock_GetTimestring,platform_clock,gettimestring}\r
  57  * @functionpage{IotClock_GetTimeMs,platform_clock,gettimems}\r
  58  * @functionpage{IotClock_SleepMs,platform_clock,sleepms}\r
  59  * @functionpage{IotClock_TimerCreate,platform_clock,timercreate}\r
  60  * @functionpage{IotClock_TimerDestroy,platform_clock,timerdestroy}\r
  61  * @functionpage{IotClock_TimerArm,platform_clock,timerarm}\r
  62  */\r
  63 \r
  64 /**\r
  65  * @brief Generates a human-readable timestring, such as "01 Jan 2018 12:00".\r
  66  *\r
  67  * This function uses the system clock to generate a human-readable timestring.\r
  68  * This timestring is printed by the [logging functions](@ref logging_functions).\r
  69  *\r
  70  * @param[out] pBuffer A buffer to store the timestring in.\r
  71  * @param[in] bufferSize The size of `pBuffer`.\r
  72  * @param[out] pTimestringLength The actual length of the timestring stored in\r
  73  * `pBuffer`.\r
  74  *\r
  75  * @return `true` if a timestring was successfully generated; `false` otherwise.\r
  76  *\r
  77  * @warning The implementation of this function must not call any [logging functions]\r
  78  * (@ref logging_functions).\r
  79  *\r
  80  * <b>Example</b>\r
  81  * @code{c}\r
  82  * char timestring[ 32 ];\r
  83  * size_t timestringLength = 0;\r
  84  *\r
  85  * if( IotClock_GetTimestring( timestring, 32, &timestringLength ) == true )\r
  86  * {\r
  87  *     printf( "Timestring: %.*s", timestringLength, timestring );\r
  88  * }\r
  89  * @endcode\r
  90  */\r
  91 /* @[declare_platform_clock_gettimestring] */\r
  92 bool IotClock_GetTimestring( char * pBuffer,\r
  93                              size_t bufferSize,\r
  94                              size_t * pTimestringLength );\r
  95 /* @[declare_platform_clock_gettimestring] */\r
  96 \r
  97 /**\r
  98  * @brief Returns a nonzero, monotonically-increasing system time in milliseconds.\r
  99  *\r
 100  * This function reads a millisecond-resolution system clock. The clock should\r
 101  * always be monotonically-increasing; therefore, real-time clocks that may be\r
 102  * set by another process are not suitable for this function's implementation.\r
 103  *\r
 104  * @return The value of the system clock. This function is not expected to fail.\r
 105  *\r
 106  * <b>Example</b>\r
 107  * @code{c}\r
 108  * // Get current time.\r
 109  * uint64_t currentTime = IotClock_GetTimeMs();\r
 110  * @endcode\r
 111  */\r
 112 /* @[declare_platform_clock_gettimems] */\r
 113 uint64_t IotClock_GetTimeMs( void );\r
 114 /* @[declare_platform_clock_gettimems] */\r
 115 \r
 116 /**\r
 117  * @brief Delay for the given number of milliseconds.\r
 118  *\r
 119  * This function suspends its calling thread for at least `sleepTimeMs` milliseconds.\r
 120  *\r
 121  * @param[in] sleepTimeMs Sleep time (in milliseconds).\r
 122  */\r
 123 /* @[declare_platform_clock_sleepms] */\r
 124 void IotClock_SleepMs( uint32_t sleepTimeMs );\r
 125 /* @[declare_platform_clock_sleepms] */\r
 126 \r
 127 /**\r
 128  * @brief Create a new timer.\r
 129  *\r
 130  * This function creates a new, unarmed timer. It must be called on an uninitialized\r
 131  * #IotTimer_t. This function must not be called on an already-initialized #IotTimer_t.\r
 132  *\r
 133  * @param[out] pNewTimer Set to a new timer handle on success.\r
 134  * @param[in] expirationRoutine The function to run when this timer expires. This\r
 135  * function should be called in its own <i>detached</i> thread.\r
 136  * @param[in] pArgument The argument to pass to `expirationRoutine`.\r
 137  *\r
 138  * @return `true` if the timer is successfully created; `false` otherwise.\r
 139  *\r
 140  * @see @ref platform_clock_function_timerdestroy, @ref platform_clock_function_timerarm\r
 141  */\r
 142 /* @[declare_platform_clock_timercreate] */\r
 143 bool IotClock_TimerCreate( IotTimer_t * pNewTimer,\r
 144                            IotThreadRoutine_t expirationRoutine,\r
 145                            void * pArgument );\r
 146 /* @[declare_platform_clock_timercreate] */\r
 147 \r
 148 /**\r
 149  * @brief Free resources used by a timer.\r
 150  *\r
 151  * This function frees resources used by a timer. It must be called on an initialized\r
 152  * #IotTimer_t. No other timer functions should be called on `pTimer` after calling\r
 153  * this function (unless the timer is re-created).\r
 154  *\r
 155  * This function will stop the `pTimer` if it is armed.\r
 156  *\r
 157  * @param[in] pTimer The timer to destroy.\r
 158  *\r
 159  * @see @ref platform_clock_function_timercreate, @ref platform_clock_function_timerarm\r
 160  */\r
 161 /* @[declare_platform_clock_timerdestroy] */\r
 162 void IotClock_TimerDestroy( IotTimer_t * pTimer );\r
 163 /* @[declare_platform_clock_timerdestroy] */\r
 164 \r
 165 /**\r
 166  * @brief Arm a timer to expire at the given relative timeout.\r
 167  *\r
 168  * This function arms a timer to run its expiration routine at the given time.\r
 169  *\r
 170  * If `periodMs` is nonzero, the timer should expire periodically at intervals\r
 171  * such as:\r
 172  * - `relativeTimeoutMs`\r
 173  * - `relativeTimeoutMs + periodMs`\r
 174  * - `relativeTimeoutMs + 2 * periodMs`\r
 175  * - Etc. (subject to some jitter).\r
 176  *\r
 177  * Setting `periodMs` to `0` arms a one-shot, non-periodic timer.\r
 178  *\r
 179  * @param[in] pTimer The timer to arm.\r
 180  * @param[in] relativeTimeoutMs When the timer should expire, relative to the time\r
 181  * this function is called.\r
 182  * @param[in] periodMs How often the timer should expire again after `relativeTimerMs`.\r
 183  *\r
 184  * @return `true` if the timer was successfully armed; `false` otherwise.\r
 185  *\r
 186  * @see @ref platform_clock_function_timercreate, @ref platform_clock_function_timerdestroy\r
 187  *\r
 188  * <b>Example</b>\r
 189  * @code{c}\r
 190  *\r
 191  * void timerExpirationRoutine( void * pArgument );\r
 192  *\r
 193  * void timerExample( void )\r
 194  * {\r
 195  *     IotTimer_t timer;\r
 196  *\r
 197  *     if( IotClock_TimerCreate( &timer, timerExpirationRoutine, NULL ) == true )\r
 198  *     {\r
 199  *         // Set the timer to periodically expire every 10 seconds.\r
 200  *         if( IotClock_TimerArm( &timer, 10000, 10000 ) == true )\r
 201  *         {\r
 202  *             // Wait for timer to expire.\r
 203  *         }\r
 204  *\r
 205  *         IotClock_TimerDestroy( &timer );\r
 206  *     }\r
 207  * }\r
 208  * @endcode\r
 209  */\r
 210 /* @[declare_platform_clock_timerarm] */\r
 211 bool IotClock_TimerArm( IotTimer_t * pTimer,\r
 212                         uint32_t relativeTimeoutMs,\r
 213                         uint32_t periodMs );\r
 214 /* @[declare_platform_clock_timerarm] */\r
 215 \r
 216 #endif /* ifndef IOT_CLOCK_H_ */\r