src/system/SystemClock.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2018 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This is an internal header file that defines the interface to a platform-supplied
  22  *      function for retrieving the current system time.
  23  */
  24
  25 #pragma once
  26
  27 // Include configuration headers
  28 #include <system/SystemConfig.h>
  29
  30 // Include dependent headers
  31 #include <support/DLLUtil.h>
  32
  33 #include <system/SystemError.h>
  34
  35 namespace chip {
  36 namespace System {
  37
  38 enum
  39 {
  40     kTimerFactor_nano_per_micro  = 1000, /** Number of nanoseconds in a microsecond. */
  41     kTimerFactor_micro_per_milli = 1000, /** Number of microseconds in a millisecond. */
  42     kTimerFactor_milli_per_unit  = 1000, /** Number of milliseconds in a second. */
  43
  44     kTimerFactor_nano_per_milli = 1000000, /** Number of nanoseconds in a millisecond. */
  45     kTimerFactor_micro_per_unit = 1000000  /** Number of microseconds in a second. */
  46 };
  47
  48 namespace Platform {
  49 namespace Layer {
  50
  51 /**
  52  * @brief
  53  *   Platform-specific function for getting monotonic system time in microseconds.
  54  *
  55  * This function is expected to return elapsed time in microseconds since an arbitrary, platform-defined
  56  * epoch.  Platform implementations are obligated to return a value that is ever-increasing (i.e. never
  57  * wraps) between reboots of the system.  Additionally, the underlying time source is required to tick
  58  * continuously during any system sleep modes that do not entail a restart upon wake.
  59  *
  60  * The epoch for time returned by this function is *not* required to be the same that for any of the
  61  * other GetClock... functions, including GetClock_MonotonicMS().
  62  *
  63  * This function is expected to be thread-safe on any platform that employs threading.
  64  *
  65  * @note
  66  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
  67  *   Layer should call System::Layer::GetClock_Monotonic().
  68  *
  69  * @returns             Elapsed time in microseconds since an arbitrary, platform-defined epoch.
  70  */
  71 extern uint64_t GetClock_Monotonic();
  72
  73 /**
  74  * @brief
  75  *   Platform-specific function for getting monotonic system time in milliseconds.
  76  *
  77  * This function is expected to return elapsed time in milliseconds since an arbitrary, platform-defined
  78  * epoch.  Platform implementations are obligated to return a value that is ever-increasing (i.e. never
  79  * wraps) between reboots of the system.  Additionally, the underlying time source is required to tick
  80  * continuously during any system sleep modes that do not entail a restart upon wake.
  81  *
  82  * The epoch for time returned by this function is *not* required to be the same as that for any of the
  83  * other GetClock... functions, including GetClock_Monotonic().
  84  *
  85  * This function is expected to be thread-safe on any platform that employs threading.
  86  *
  87  * @note
  88  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
  89  *   Layer should call System::Layer::GetClock_MonotonicMS().
  90  *
  91  * @returns             Elapsed time in milliseconds since an arbitrary, platform-defined epoch.
  92  */
  93 extern uint64_t GetClock_MonotonicMS();
  94
  95 /**
  96  * @brief
  97  *   Platform-specific function for getting high-resolution monotonic system time in microseconds.
  98  *
  99  * This function is expected to return elapsed time in microseconds since an arbitrary, platform-defined
 100  * epoch.  Values returned by GetClock_MonotonicHiRes() are required to be ever-increasing (i.e. never
 101  * wrap).  However, the underlying timer is *not* required to tick continuously during system
 102  * deep-sleep states.
 103  *
 104  * Platform are encouraged to implement GetClock_MonotonicHiRes() using a high-resolution timer
 105  * that is not subject to gradual clock adjustments (slewing).  On platforms without such a timer,
 106  * GetClock_MonotonicHiRes() can return the same value as GetClock_Monotonic().
 107  *
 108  * The epoch for time returned by this function is not required to be the same that for any of the
 109  * other GetClock... functions.
 110  *
 111  * This function is expected to be thread-safe on any platform that employs threading.
 112  *
 113  * @note
 114  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
 115  *   Layer should call System::Layer::GetClock_MonotonicHiRes().
 116  *
 117  * @returns             Elapsed time in microseconds since an arbitrary, platform-defined epoch.
 118  */
 119 extern uint64_t GetClock_MonotonicHiRes();
 120
 121 /**
 122  * @brief
 123  *   Platform-specific function for getting the current real (civil) time in microsecond Unix time
 124  *   format.
 125  *
 126  * This function is expected to return the local platform's notion of current real time, expressed
 127  * as a Unix time value scaled to microseconds.  The underlying clock is required to tick at a
 128  * rate of least at whole seconds (values of 1,000,000), but may tick faster.
 129  *
 130  * On those platforms that are capable of tracking real time, GetClock_RealTime() must return the
 131  * error CHIP_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED whenever the system is unsynchronized with real time.
 132  *
 133  * Platforms that are incapable of tracking real time should not implement the GetClock_RealTime()
 134  * function, thereby forcing link-time failures of features that depend on access to real time.
 135  * Alternatively, such platforms may supply an implementation of GetClock_RealTime() that returns
 136  * the error CHIP_SYSTEM_ERROR_NOT_SUPPORTED.
 137  *
 138  * This function is expected to be thread-safe on any platform that employs threading.
 139  *
 140  * @note
 141  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
 142  *   Layer should call System::Layer::GetClock_RealTime().
 143  *
 144  * @param[out] curTime                  The current time, expressed as Unix time scaled to microseconds.
 145  *
 146  * @retval #CHIP_SYSTEM_NO_ERROR       If the method succeeded.
 147  * @retval #CHIP_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED
 148  *                                      If the platform is capable of tracking real time, but is
 149  *                                      is currently unsynchronized.
 150  * @retval #CHIP_SYSTEM_ERROR_NOT_SUPPORTED
 151  *                                      If the platform is incapable of tracking real time.
 152  */
 153 extern Error GetClock_RealTime(uint64_t & curTime);
 154
 155 /**
 156  * @brief
 157  *   Platform-specific function for getting the current real (civil) time in millisecond Unix time
 158  *   format.
 159  *
 160  * This function is expected to return the local platform's notion of current real time, expressed
 161  * as a Unix time value scaled to milliseconds.
 162  *
 163  * See the documentation for GetClock_RealTime() for details on the expected behavior.
 164  *
 165  * @note
 166  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
 167  *   Layer should call System::Layer::GetClock_RealTimeMS().
 168  *
 169  * @param[out] curTimeMS               The current time, expressed as Unix time scaled to milliseconds.
 170  *
 171  * @retval #CHIP_SYSTEM_NO_ERROR       If the method succeeded.
 172  * @retval #CHIP_SYSTEM_ERROR_REAL_TIME_NOT_SYNCED
 173  *                                      If the platform is capable of tracking real time, but is
 174  *                                      is currently unsynchronized.
 175  * @retval #CHIP_SYSTEM_ERROR_NOT_SUPPORTED
 176  *                                      If the platform is incapable of tracking real time.
 177  */
 178 extern Error GetClock_RealTimeMS(uint64_t & curTimeMS);
 179
 180 /**
 181  * @brief
 182  *   Platform-specific function for setting the current real (civil) time.
 183  *
 184  * CHIP calls this function to set the local platform's notion of current real time.  The new current
 185  * time is expressed as a Unix time value scaled to microseconds.
 186  *
 187  * Once set, underlying platform clock is expected to track real time with a granularity of at least whole
 188  * seconds.
 189  *
 190  * On platforms that support tracking real time, the SetClock_RealTime() function must return the error
 191  * CHIP_SYSTEM_ERROR_ACCESS_DENIED if the calling application does not have the privilege to set the
 192  * current time.
 193  *
 194  * Platforms that are incapable of tracking real time, or do not offer the ability to set real time,
 195  * should not implement the SetClock_RealTime() function, thereby forcing link-time failures of features
 196  * that depend on setting real time.  Alternatively, such platforms may supply an implementation of
 197  * SetClock_RealTime() that returns the error CHIP_SYSTEM_ERROR_NOT_SUPPORTED.
 198  *
 199  * This function is expected to be thread-safe on any platform that employs threading.
 200  *
 201  * @note
 202  *   This function is reserved for internal use by the CHIP System Layer.  Users of the CHIP System
 203  *   Layer should call System::Layer::GetClock_RealTimeMS().
 204  *
 205  * @param[in] newCurTime                The new current time, expressed as Unix time scaled to microseconds.
 206  *
 207  * @retval #CHIP_SYSTEM_NO_ERROR       If the method succeeded.
 208  * @retval #CHIP_SYSTEM_ERROR_NOT_SUPPORTED
 209  *                                      If the platform is incapable of tracking real time.
 210  * @retval #CHIP_SYSTEM_ERROR_ACCESS_DENIED
 211  *                                      If the calling application does not have the privilege to set the
 212  *                                      current time.
 213  */
 214 extern Error SetClock_RealTime(uint64_t newCurTime);
 215
 216 } // namespace Layer
 217 } // namespace Platform
 218 } // namespace System
 219 } // namespace chip