mbed-os/platform/source/mbed_os_timer.h

/*
 * 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 "source/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