mbed_os_timer.cpp

00001 /*
00002  * Copyright (c) 2006-2019, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00013  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #include "platform/mbed_power_mgmt.h"
00019 #include "platform/source/mbed_os_timer.h"
00020 #include "platform/CriticalSectionLock.h"
00021 #include "platform/source/SysTimer.h"
00022 #include "us_ticker_api.h"
00023 #include "lp_ticker_api.h"
00024 #include "mbed_critical.h"
00025 #include "mbed_assert.h"
00026 #include <new>
00027 
00028 /* This provides the marshalling point for a system global SysTimer, which
00029  * is used to provide:
00030  * - timed sleeps (for default idle hook in RTOS tickless mode, or non-RTOS sleeps)
00031  * - regular ticks for RTOS
00032  * - absolute system timing (directly for non-RTOS, or indirectly via RTOS tick count)
00033  */
00034 
00035 namespace mbed {
00036 namespace internal {
00037 
00038 OsTimer *os_timer;
00039 
00040 namespace {
00041 uint64_t os_timer_data[(sizeof(OsTimer) + 7) / 8];
00042 }
00043 
00044 OsTimer *init_os_timer()
00045 {
00046     // Do not use SingletonPtr since this relies on the RTOS.
00047     // Locking not required as it will be first called during
00048     // OS init, or else we're a non-RTOS single-threaded setup.
00049     if (!os_timer) {
00050 #if MBED_CONF_TARGET_TICKLESS_FROM_US_TICKER && DEVICE_USTICKER
00051         os_timer = new (os_timer_data) OsTimer(get_us_ticker_data());
00052 #elif !MBED_CONF_TARGET_TICKLESS_FROM_US_TICKER && DEVICE_LPTICKER
00053         os_timer = new (os_timer_data) OsTimer(get_lp_ticker_data());
00054 #else
00055         MBED_ASSERT("OS timer not available - check MBED_CONF_TARGET_TICKLESS_FROM_US_TICKER" && false);
00056         return NULL;
00057 #endif
00058         //os_timer->setup_irq();
00059     }
00060 
00061     return os_timer;
00062 }
00063 
00064 /* These traits classes are designed to permit chunks of code to be
00065  * omitted - in particular eliminating timers. However, we don't want
00066  * to cause template bloat, so don't have too many traits variants.
00067  */
00068 
00069 /* Optionally timed operation, with optional predicate */
00070 struct timed_predicate_op {
00071     timed_predicate_op(uint64_t t) : wake_time(t), orig_predicate(NULL), orig_handle(NULL)
00072     {
00073         init_os_timer();
00074     }
00075 
00076     timed_predicate_op(uint64_t t, bool (*wake_predicate)(void *), void *wake_predicate_handle) : wake_time(t), orig_predicate(wake_predicate), orig_handle(wake_predicate_handle)
00077     {
00078         init_os_timer();
00079     }
00080 
00081     ~timed_predicate_op()
00082     {
00083         // Make sure wake timer is cancelled. (It may or may not be, depending on
00084         // why we woke).
00085         os_timer->cancel_wake();
00086     }
00087 
00088     bool wake_condition() const
00089     {
00090         return (orig_predicate && orig_predicate(orig_handle)) || os_timer->wake_time_passed();
00091     }
00092 
00093     void sleep_prepare()
00094     {
00095         if (wake_time != (uint64_t) -1) {
00096             os_timer->set_wake_time(wake_time);
00097         }
00098     }
00099 
00100     bool sleep_prepared()
00101     {
00102         return wake_time == (uint64_t) -1 || os_timer->wake_time_set();
00103     }
00104 
00105 private:
00106     uint64_t wake_time;
00107     bool (*orig_predicate)(void *);
00108     void *orig_handle;
00109 };
00110 
00111 /* Untimed operation with predicate */
00112 struct untimed_op {
00113     untimed_op(bool (*wake_predicate)(void *), void *wake_predicate_handle) : orig_predicate(wake_predicate), orig_handle(wake_predicate_handle)
00114     {
00115     }
00116 
00117     bool wake_condition() const
00118     {
00119         return orig_predicate(orig_handle);
00120     }
00121 
00122     void sleep_prepare()
00123     {
00124     }
00125 
00126     bool sleep_prepared()
00127     {
00128         return true;
00129     }
00130 
00131 private:
00132     bool (*orig_predicate)(void *);
00133     void *orig_handle;
00134 };
00135 
00136 /* We require that this is called from thread context, outside a critical section,
00137  * and the kernel already suspended if an RTOS, meaning we don't have to worry
00138  * about any potential threading issues.
00139  *
00140  * The wake predicate will be called from both outside and inside a critical
00141  * section, so appropriate atomic care must be taken.
00142  */
00143 template <class OpT>
00144 void do_sleep_operation(OpT &op)
00145 {
00146     // We assume the ticker is not already in use - without RTOS, it
00147     // is never used, with RTOS, it will have been disabled with OS_Tick_Disable
00148     while (!op.wake_condition()) {
00149         // Set (or re-set) the wake time - outside a critical section, as
00150         // it could take long enough to cause UART data loss on some platforms.
00151         op.sleep_prepare();
00152 
00153         // If no target sleep function, nothing else to do - just keep
00154         // rechecking the wake condition.
00155 #if DEVICE_SLEEP
00156         // Now we need to enter the critical section for the race-free sleep
00157         {
00158             CriticalSectionLock lock;
00159 
00160             // Recheck wake conditions before starting sleep, avoiding race
00161             if (op.wake_condition()) {
00162                 break;
00163             }
00164 
00165             // It's possible that an intermediate wake interrupt occurred
00166             // between "set_wake_time" and the critical lock - only sleep
00167             // if we see that the timer is armed or we don't need it. Otherwise,
00168             // we go round to set the timer again.
00169             if (op.sleep_prepared()) {
00170                 // Enter HAL sleep (normal or deep)
00171                 sleep();
00172             }
00173         }
00174 
00175         // Ensure interrupts get a chance to fire, which allows new result from
00176         // wake_predicate() and wake_time_passed()
00177         __ISB();
00178 #endif
00179     }
00180 }
00181 
00182 /* We require that this is called from thread context, outside a critical section,
00183  * and the kernel already suspended if an RTOS, meaning we don't have to worry
00184  * about any potential threading issues.
00185  *
00186  * The wake predicate will be called from both outside and inside a critical
00187  * section, so appropriate atomic care must be taken.
00188  */
00189 uint64_t do_timed_sleep_absolute(uint64_t wake_time, bool (*wake_predicate)(void *), void *wake_predicate_handle)
00190 {
00191     {
00192         timed_predicate_op op(wake_time, wake_predicate, wake_predicate_handle);
00193         do_sleep_operation(op);
00194     }
00195 
00196     return os_timer->update_and_get_tick();
00197 }
00198 
00199 
00200 #if MBED_CONF_RTOS_PRESENT
00201 /* The 32-bit limit is part of the API - we will always wake within 2^32 ticks */
00202 /* This version is tuned for RTOS use, where the RTOS needs to know the time spent sleeping */
00203 uint32_t do_timed_sleep_relative(uint32_t wake_delay, bool (*wake_predicate)(void *), void *wake_predicate_handle)
00204 {
00205     uint64_t sleep_start = init_os_timer()->get_tick();
00206     // When running with RTOS, the requested delay will be based on the kernel's tick count.
00207     // If it missed a tick as entering idle, we should reflect that by moving the
00208     // start time back to reflect its current idea of time.
00209     // Example: OS tick count = 100, our tick count = 101, requested delay = 50
00210     // We need to schedule wake for tick 150, report 50 ticks back to our caller, and
00211     // clear the unacknowledged tick count.
00212     sleep_start -= os_timer->unacknowledged_ticks();
00213 
00214     uint64_t sleep_finish = do_timed_sleep_absolute(sleep_start + wake_delay, wake_predicate, wake_predicate_handle);
00215 
00216     return static_cast<uint32_t>(sleep_finish - sleep_start);
00217 }
00218 
00219 #else
00220 
00221 void do_untimed_sleep(bool (*wake_predicate)(void *), void *wake_predicate_handle)
00222 {
00223     untimed_op op(wake_predicate, wake_predicate_handle);
00224 
00225     do_sleep_operation(op);
00226 }
00227 
00228 /* (uint32_t)-1 delay is treated as "wait forever" */
00229 /* This version is tuned for non-RTOS use, where we don't need to return sleep time, and waiting forever is possible */
00230 void do_timed_sleep_relative_or_forever(uint32_t wake_delay, bool (*wake_predicate)(void *), void *wake_predicate_handle)
00231 {
00232     // Special-case 0 delay, to save multiple callers having to do it. Just call the predicate once.
00233     if (wake_delay == 0) {
00234         wake_predicate(wake_predicate_handle);
00235         return;
00236     }
00237 
00238     uint64_t wake_time;
00239     if (wake_delay == (uint32_t) -1) {
00240         wake_time = (uint64_t) -1;
00241     } else {
00242         wake_time = init_os_timer()->update_and_get_tick() + wake_delay;
00243     }
00244     /* Always use timed_predicate_op here to save pulling in two templates */
00245     timed_predicate_op op(wake_time, wake_predicate, wake_predicate_handle);
00246     do_sleep_operation(op);
00247 }
00248 
00249 #endif
00250 
00251 } // namespace internal
00252 } // namespace mbed