Mbed OS Reference | mbed_os_timer.h Source File

 /*
  * Copyright (c) 2006-2019, ARM Limited, All Rights Reserved
  * SPDX-License-Identifier: Apache-2.0
  *
  * Licensed under the Apache License, Version 2.0 (the "License"); you may
  * not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 #ifndef MBED_MBED_SLEEP_TIMER_H
 #define MBED_MBED_SLEEP_TIMER_H
 
 #include <chrono>
 #include "platform/internal/SysTimer.h"
 
 #if MBED_CONF_RTOS_PRESENT
 extern "C" {
 #include "rtx_lib.h"
 }
 #endif
 
 namespace mbed {
 namespace internal {
 
 #if MBED_CONF_RTOS_PRESENT
 using OsTimer = SysTimer<std::ratio<1, OS_TICK_FREQ>>;
 #else
 using OsTimer = SysTimer<std::milli>;
 #endif
 
 /* A SysTimer is used to provide the timed sleep - this provides access to share it for
  * other use, such as ticks. If accessed this way, it must not be in use when a sleep function below is called.
  */
 extern OsTimer *os_timer;
 OsTimer *init_os_timer();
 
 /** A C++11 chrono TrivialClock for os_timer
  *
  * Due to the nature of OsTimer/SysTimer, this does not have a single `now` method, but has
  * multiple ways to report the current state:
  *
  *      High-res timeline -------------------------------------------------------------
  *      Ticks               |  a  |  b  |  b  |  b  |  c  |  c  |  c  |  c  |  c  | d ^
  *                                ^                 ^                             ^   os_timer->get_time()
  *                         acknowledged_ticks()   reported_ticks()               now()
  *
  * (a) is time read from hardware by OsTimer, reported to the user of OsTimer, and acknowledged by that user.
  * (b) is time read from hardware by OsTimer, reported to the user of OsTimer, but not yet acknowledged.
  * (c) is time already elapsed in the hardware but yet to be read and processed as ticks by OsTimer.
  * (d) is time already elapsed in the hardware that doesn't yet form a tick.
  *
  * Time is "reported" either by:
  *   * calls to the OsTimer's handler following start_tick - these must be acknowledged
  *   * the result of OsTimer::update_and_get_tick() / OsClock::now() - calling this implies acknowledgment.
  *
  * As such `now()` is used when the ticker is not in use - it processes ticks that would have been
  * processed by the tick handler. If the ticker is in uses `reported_ticks` or `acknowleged_ticks` must be used.
  *
  * @note To fit better into the chrono framework, OsClock uses
  *       chrono::milliseconds as its representation, which makes it signed
  *       and at least 45 bits, so it will be int64_t or equivalent, unlike
  *       OsTimer which uses uint64_t rep.
  */
 struct OsClock {
     /* Standard TrivialClock fields */
     using period = OsTimer::period;
     using rep = std::chrono::milliseconds::rep;
     using duration = std::chrono::duration<rep, period>; // == std::chrono::milliseconds, if period is std::milli
     using time_point = std::chrono::time_point<OsClock, duration>;
     static constexpr bool is_steady = true;
     // Read the hardware, and return the updated time_point.
     // Initialize the timing system if necessary - this could be the first call.
     // See SysTimer::update_and_get_tick for more details.
     static time_point now()
     {
         // We are a real Clock with a well-defined epoch. As such we distinguish ourselves
         // from the less-well-defined SysTimer pseudo-Clock. This means our time_points
         // are not convertible, so need to fiddle here.
         return time_point(init_os_timer()->update_and_get_tick().time_since_epoch());
     }
     // Return the current reported tick count, without update.
     // Assumes timer has already been initialized, as ticker should have been in use to
     // keep that tick count up-to-date. See SysTimer::get_tick for more details.
     static time_point reported_ticks()
     {
         return time_point(os_timer->get_tick().time_since_epoch());
     }
     // Return the acknowledged tick count.
     static time_point acknowledged_ticks()
     {
         return reported_ticks() - os_timer->unacknowledged_ticks();
     }
     // Slightly-optimised variant of OsClock::now() that assumes os_timer is initialised.
     static time_point now_with_init_done()
     {
         return time_point(os_timer->update_and_get_tick().time_since_epoch());
     }
     static void set_wake_time(time_point wake_time)
     {
         return os_timer->set_wake_time(OsTimer::time_point(wake_time.time_since_epoch()));
     }
     /* Extension to
      * make it easy to use 32-bit durations for some APIs, as we historically do */
     using duration_u32 = std::chrono::duration<uint32_t, period>;
 };
 
 /* time_point::max() is effectively "sleep forever" */
 OsClock::time_point do_timed_sleep_absolute(OsClock::time_point wake_time, bool (*wake_predicate)(void *) = NULL, void *wake_predicate_handle = NULL);
 
 #if MBED_CONF_RTOS_PRESENT
 /* Maximum sleep time is 2^32-1 ticks; timer is always set to achieve this */
 /* Assumes that ticker has been in use prior to call, so restricted to RTOS use */
 OsClock::duration_u32 do_timed_sleep_relative_to_acknowledged_ticks(OsClock::duration_u32 wake_delay, bool (*wake_predicate)(void *) = NULL, void *wake_predicate_handle = NULL);
 #else
 
 void do_untimed_sleep(bool (*wake_predicate)(void *), void *wake_predicate_handle = NULL);
 
 /* duration_u32::max() delay is sleep forever */
 
 void do_timed_sleep_relative_or_forever(OsClock::duration_u32 wake_delay, bool (*wake_predicate)(void *) = NULL, void *wake_predicate_handle = NULL);
 
 #endif
 
 }
 }
 
 #endif
Important Information for this Arm website
