Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
Kernel.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017-2019 ARM Limited
3  * SPDX-License-Identifier: MIT
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy
6  * of this software and associated documentation files (the "Software"), to deal
7  * in the Software without restriction, including without limitation the rights
8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9  * copies of the Software, and to permit persons to whom the Software is
10  * furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21  * SOFTWARE.
22  */
23 #ifndef KERNEL_H
24 #define KERNEL_H
25 
26 #include <stdint.h>
27 #include <chrono>
28 #include "rtos/mbed_rtos_types.h"
29 #include "platform/mbed_toolchain.h"
30 #if !MBED_CONF_RTOS_PRESENT
31 #include "platform/internal/mbed_os_timer.h"
32 #endif
33 
34 
35 namespace rtos {
36 
37 /** \addtogroup rtos-public-api */
38 /** @{*/
39 
40 /** Functions in the Kernel namespace control RTOS kernel information. */
41 namespace Kernel {
42 
43 namespace impl {
44 /* Internal integer-returning function.
45  *
46  * ARM EABI means that `time_point`s do not get returned in registers, so
47  * it's worth having the actual exteernal definition return an integer, and only
48  * convert to `time_point` via the inline function `now()`.
49  */
50 uint64_t get_tick_count();
51 }
52 
53 /** Read the current RTOS kernel millisecond tick count.
54  The tick count corresponds to the tick count the RTOS uses for timing
55  purposes. It increments monotonically from 0 at boot, so it effectively
56  never wraps. If the underlying RTOS only provides a 32-bit tick count,
57  this method expands it to 64 bits.
58  @return RTOS kernel current tick count
59  @note Mbed OS always uses millisecond RTOS ticks, and this could only wrap
60  after half a billion years.
61  @note You cannot call this function from ISR context.
62  @deprecated Use `Kernel::Clock::now()` to get a chrono time_point instead of an integer millisecond count.
63  */
64 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Use `Kernel::Clock::now()` to get a chrono time_point instead of an integer millisecond count.")
65 uint64_t get_ms_count();
66 
67 /** A C++11 chrono TrivialClock for the kernel millisecond tick count
68  *
69  * @note To fit better into the chrono framework, Kernel::Clock uses
70  * std::chrono::milliseconds as its representation, which makes it signed
71  * and at least 45 bits (so it will be int64_t or equivalent).
72  */
73 struct Clock {
74  Clock() = delete;
75  /* Standard TrivialClock fields */
76  using duration = std::chrono::milliseconds;
77  using rep = duration::rep;
78  using period = duration::period;
79 #if MBED_CONF_RTOS_PRESENT
80  using time_point = std::chrono::time_point<Clock>;
81 #else
82  /* In non-RTOS builds, the clock maps directly to the underlying clock, and must
83  * indicate that here, so we can do implicit conversion internally.
84  */
85  using time_point = std::chrono::time_point<mbed::internal::OsClock, duration>;
86 #endif
87  static constexpr bool is_steady = true;
88  static time_point now()
89  {
90  return time_point(duration(impl::get_tick_count()));
91  }
92  /* Extension to make it easy to use 32-bit durations for some APIs, as we historically have,
93  * for efficiency.
94  */
95  using duration_u32 = std::chrono::duration<uint32_t, period>;
96 
97  /** Lock the clock to ensure it stays running; dummy for API compatibility with HighResClock */
98  static void lock()
99  {
100  }
101 
102  /** Unlock the clock, allowing it to stop during power saving; dummy for API compatibility with HighResClock */
103  static void unlock()
104  {
105  }
106 };
107 
108 /** Maximum duration for Kernel::Clock::duration_u32-based APIs
109  *
110  * @note As duration_u32-based APIs pass through straight to CMSIS-RTOS, they will
111  * interpret duration_u32(0xFFFFFFFF) as "wait forever". Indicate maximum
112  * wait time of 0xFFFFFFFE for these calls (which is ~49 days).
113  */
114 constexpr Clock::duration_u32 wait_for_u32_max{osWaitForever - 1};
115 
116 /** Magic "wait forever" constant for Kernel::Clock::duration_u32-based APIs
117  *
118  * Many duration_u32-based APIs treat duration_u32(0xFFFFFFFF) as "wait forever".
119  */
120 constexpr Clock::duration_u32 wait_for_u32_forever{osWaitForever};
121 
122 /** Attach a function to be called by the RTOS idle task.
123  @param fptr pointer to the function to be called
124 
125  @note You may call this function from ISR context.
126  @note Bare metal profile: This API is not supported.
127 */
128 void attach_idle_hook(void (*fptr)(void));
129 
130 /** Attach a function to be called when a thread terminates.
131  @param fptr pointer to the function to be called
132 
133  @note You may call this function from ISR context.
134  @note Bare metal profile: This API is not supported.
135 */
136 void attach_thread_terminate_hook(void (*fptr)(osThreadId_t id));
137 
138 } // namespace Kernel
139 
140 /** @}*/
141 
142 } // namespace rtos
143 #endif
rtos::Kernel::attach_idle_hook
void attach_idle_hook(void(*fptr)(void))
Attach a function to be called by the RTOS idle task.
rtos::Kernel::wait_for_u32_forever
constexpr Clock::duration_u32 wait_for_u32_forever
Magic "wait forever" constant for Kernel::Clock::duration_u32-based APIs.
Definition: Kernel.h:120
rtos::Kernel::wait_for_u32_max
constexpr Clock::duration_u32 wait_for_u32_max
Maximum duration for Kernel::Clock::duration_u32-based APIs.
Definition: Kernel.h:114
rtos::Kernel::Clock::unlock
static void unlock()
Unlock the clock, allowing it to stop during power saving; dummy for API compatibility with HighResCl...
Definition: Kernel.h:103
rtos::Kernel::Clock
A C++11 chrono TrivialClock for the kernel millisecond tick count.
Definition: Kernel.h:73
rtos::Kernel::get_ms_count
uint64_t get_ms_count()
Read the current RTOS kernel millisecond tick count.
rtos::Kernel::attach_thread_terminate_hook
void attach_thread_terminate_hook(void(*fptr)(osThreadId_t id))
Attach a function to be called when a thread terminates.
rtos::Kernel::Clock::lock
static void lock()
Lock the clock to ensure it stays running; dummy for API compatibility with HighResClock.
Definition: Kernel.h:98
rtos
Definition: TaskBase.h:25
MBED_DEPRECATED_SINCE
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Definition: mbed_toolchain.h:424
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.