TizenRT Libs&Environment  v2.0 M2
clock.h
Go to the documentation of this file.
1 /****************************************************************************
2  *
3  * Copyright 2016 Samsung Electronics All Rights Reserved.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing,
12  * software distributed under the License is distributed on an
13  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
14  * either express or implied. See the License for the specific
15  * language governing permissions and limitations under the License.
16  *
17  ****************************************************************************/
18 
19 /****************************************************************************
20  *
21  * Copyright (C) 2007-2009, 2011-2012, 2014 Gregory Nutt. All rights reserved.
22  * Author: Gregory Nutt <gnutt@nuttx.org>
23  *
24  * Redistribution and use in source and binary forms, with or without
25  * modification, are permitted provided that the following conditions
26  * are met:
27  *
28  * 1. Redistributions of source code must retain the above copyright
29  * notice, this list of conditions and the following disclaimer.
30  * 2. Redistributions in binary form must reproduce the above copyright
31  * notice, this list of conditions and the following disclaimer in
32  * the documentation and/or other materials provided with the
33  * distribution.
34  * 3. Neither the name NuttX nor the names of its contributors may be
35  * used to endorse or promote products derived from this software
36  * without specific prior written permission.
37  *
38  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
39  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
40  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
41  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
42  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
43  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
44  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
45  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
46  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
47  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
48  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
49  * POSSIBILITY OF SUCH DAMAGE.
50  *
51  ****************************************************************************/
52 
61 #ifndef _INCLUDE_CLOCK_H
64 #define _INCLUDE_CLOCK_H
65 
66 /****************************************************************************
67  * Included Files
68  ****************************************************************************/
69 
70 #include <tinyara/config.h>
71 
72 #include <sys/types.h>
73 #include <stdint.h>
74 #include <time.h>
75 
76 #include <tinyara/compiler.h>
77 
78 /****************************************************************************
79  * Pre-processor Definitions
80  ****************************************************************************/
81 /* Configuration ************************************************************/
82 /* Efficient, direct access to OS global timer variables will be supported
83  * if the execution environment has direct access to kernel global data.
84  * The code in this execution context can access the kernel global data
85  * directly if:
86  *
87  * 1. We are not running tick-less (in which case there is no global timer
88  * data),
89  * 2. This is an un-protected, non-kernel build,
90  * 3. This is a protected build, but this code is being built for execution
91  * within the kernel space.
92  * 4. It we are building with SYSCALLs enabled, but not in a kernel build,
93  * then we can't know a priori whether the code has access to the
94  * global variables or not. In that case we have to assume not.
95  */
96 
97 #undef __HAVE_KERNEL_GLOBALS
98 #if defined(CONFIG_SCHED_TICKLESS)
99 /* Case 1: There is no global timer data */
100 
101 #elif defined(CONFIG_BUILD_PROTECTED) && defined(__KERNEL__)
102 /* Case 3: Kernel mode of protected kernel build */
103 
104 #define __HAVE_KERNEL_GLOBALS 1
105 
106 #elif defined(CONFIG_BUILD_KERNEL) && defined(__KERNEL__)
107 /* Case 3: Kernel only build */
108 
109 #define __HAVE_KERNEL_GLOBALS 1
110 
111 #elif defined(CONFIG_LIB_SYSCALL)
112 /* Case 4: Building with SYSCALLs enabled, but not part of a kernel build */
113 
114 #else
115 /* Case 2: Un-protected, non-kernel build */
116 
117 #define __HAVE_KERNEL_GLOBALS 1
118 #endif
119 
120 /* If CONFIG_SYSTEM_TIME64 is selected and the CPU supports long long types,
121  * then a 64-bit system time will be used.
122  */
123 
124 #ifndef CONFIG_HAVE_LONG_LONG
125 #undef CONFIG_SYSTEM_TIME64
126 #endif
127 
128 /* Timing constants *********************************************************/
129 
130 #define NSEC_PER_SEC 1000000000
131 #define USEC_PER_SEC 1000000
132 #define MSEC_PER_SEC 1000
133 #define DSEC_PER_SEC 10
134 #define NSEC_PER_DSEC 100000000
135 #define USEC_PER_DSEC 100000
136 #define MSEC_PER_DSEC 100
137 #define NSEC_PER_MSEC 1000000
138 #define USEC_PER_MSEC 1000
139 #define NSEC_PER_USEC 1000
140 
141 /* If CONFIG_SCHED_TICKLESS is not defined, then the interrupt interval of
142  * the system timer is given by USEC_PER_TICK. This is the expected number
143  * of microseconds between calls from the processor-specific logic to
144  * sched_process_timer(). The default value of USEC_PER_TICK is 10000
145  * microseconds (100KHz). However, this default setting can be overridden
146  * by defining the interval in microseconds as CONFIG_USEC_PER_TICK in the
147  * TinyAra configuration file.
148  *
149  * The following calculations are only accurate when (1) there is no
150  * truncation involved and (2) the underlying system timer is an even
151  * multiple of microseconds. If (2) is not true, you will probably want
152  * to redefine all of the following.
153  */
154 
155 #ifdef CONFIG_USEC_PER_TICK
156 #define USEC_PER_TICK (CONFIG_USEC_PER_TICK)
157 #else
158 #define USEC_PER_TICK (10000)
159 #endif
160 
161 /* MSEC_PER_TICK can be very inaccurate if CONFIG_USEC_PER_TICK is not an
162  * even multiple of milliseconds. Calculations using USEC_PER_TICK are
163  * preferred for that reason (at the risk of overflow)
164  */
165 
166 #define TICK_PER_DSEC (USEC_PER_DSEC / USEC_PER_TICK) /* Truncates! */
167 #define TICK_PER_SEC (USEC_PER_SEC / USEC_PER_TICK) /* Truncates! */
168 #define TICK_PER_MSEC (USEC_PER_MSEC / USEC_PER_TICK) /* Truncates! */
169 #define MSEC_PER_TICK (USEC_PER_TICK / USEC_PER_MSEC) /* Truncates! */
170 #define NSEC_PER_TICK (USEC_PER_TICK * NSEC_PER_USEC) /* Exact */
171 
172 #define NSEC2TICK(nsec) (((nsec)+(NSEC_PER_TICK/2))/NSEC_PER_TICK) /* Rounds */
173 #define USEC2TICK(usec) (((usec)+(USEC_PER_TICK/2))/USEC_PER_TICK) /* Rounds */
174 
175 #if (MSEC_PER_TICK * USEC_PER_MSEC) == USEC_PER_TICK
176 #define MSEC2TICK(msec) (((msec)+(MSEC_PER_TICK/2))/MSEC_PER_TICK) /* Rounds */
177 #else
178 #define MSEC2TICK(msec) USEC2TICK((msec) * USEC_PER_MSEC) /* Rounds */
179 #endif
180 
181 #define DSEC2TICK(dsec) MSEC2TICK((dsec) * MSEC_PER_DSEC) /* Rounds */
182 #define SEC2TICK(sec) MSEC2TICK((sec) * MSEC_PER_SEC) /* Rounds */
183 
184 #define TICK2NSEC(tick) ((tick) * NSEC_PER_TICK) /* Exact */
185 #define TICK2USEC(tick) ((tick) * USEC_PER_TICK) /* Exact */
186 
187 #if (MSEC_PER_TICK * USEC_PER_MSEC) == USEC_PER_TICK
188 #define TICK2MSEC(tick) ((tick)*MSEC_PER_TICK) /* Exact */
189 #else
190 #define TICK2MSEC(tick) (((tick)*USEC_PER_TICK)/USEC_PER_MSEC) /* Rounds */
191 #endif
192 
193 #define TICK2DSEC(tick) (((tick)+(TICK_PER_DSEC/2))/TICK_PER_DSEC) /* Rounds */
194 #define TICK2SEC(tick) (((tick)+(TICK_PER_SEC/2))/TICK_PER_SEC) /* Rounds */
195 
196 /****************************************************************************
197  * Public Types
198  ****************************************************************************/
199 /* This structure is used to report CPU usage for a particular thread */
200 
201 #ifdef CONFIG_SCHED_CPULOAD
202 struct cpuload_s {
203  volatile uint32_t total; /* Total number of clock ticks */
204  volatile uint32_t active; /* Number of ticks while this thread was active */
205 };
206 
207 #ifdef CONFIG_SCHED_MULTI_CPULOAD
208 #define SCHED_NCPULOAD 3
209 #else
210 #define SCHED_NCPULOAD 1
211 #endif
212 #endif
213 
214 /****************************************************************************
215  * Public Data
216  ****************************************************************************/
217 
218 #ifdef __cplusplus
219 #define EXTERN extern "C"
220 extern "C" {
221 #else
222 #define EXTERN extern
223 #endif
224 
225 /* Access to raw system clock ***********************************************/
226 /* Direct access to the system timer/counter is supported only if (1) the
227  * system timer counter is available (i.e., we are not configured to use
228  * a hardware periodic timer), and (2) the execution environment has direct
229  * access to kernel global data
230  */
231 
232 #ifdef __HAVE_KERNEL_GLOBALS
233 EXTERN volatile clock_t g_system_timer;
234 
235 #ifndef CONFIG_SYSTEM_TIME64
236 #define clock_systimer() g_system_timer
237 #endif
238 #endif
239 
240 /****************************************************************************
241  * Public Function Prototypes
242  ****************************************************************************/
243 
244 /****************************************************************************
245  * Function: clock_synchronize
246  *
247  * Description:
248  * Synchronize the system timer to a hardware RTC. This operation is
249  * normally performed automatically by the system during clock
250  * initialization. However, the user may also need to explicitly re-
251  * synchronize the system timer to the RTC under certain conditions where
252  * the system timer is known to be in error. For example, in certain low-
253  * power states, the system timer may be stopped but the RTC will continue
254  * keep correct time. After recovering from such low-power state, this
255  * function should be called to restore the correct system time.
256  *
257  * Calling this function could result in system time going "backward" in
258  * time, especially with certain lower resolution RTC implementations.
259  * Time going backward could have bad consequences if there are ongoing
260  * timers and delays. So use this interface with care.
261  *
262  * Parameters:
263  * None
264  *
265  * Return Value:
266  * None
267  *
268  * Assumptions:
269  *
270  ****************************************************************************/
271 
272 #ifdef CONFIG_RTC
273 
277 void clock_synchronize(void);
281 #endif
282 
283 /****************************************************************************
284  * Function: clock_systimer
285  *
286  * Description:
287  * Return the current value of the 32/64-bit system timer counter.
288  * Indirect access to the system timer counter is required through this
289  * function if the execution environment does not have direct access to
290  * kernel global data.
291  *
292  * Use of this function is also required to assue atomic access to the
293  * 64-bit system timer.
294  *
295  * Parameters:
296  * None
297  *
298  * Return Value:
299  * The current value of the system timer counter
300  *
301  * Assumptions:
302  *
303  ****************************************************************************/
304 
305 #if !defined(__HAVE_KERNEL_GLOBALS) || defined(CONFIG_SYSTEM_TIME64)
306 
315 clock_t clock_systimer(void);
316 #endif
317 
318 /****************************************************************************
319  * Name: clock_systimespec
320  *
321  * Description:
322  * Return the current value of the system timer counter as a struct
323  * timespec.
324  *
325  * Parameters:
326  * ts - Location to return the time
327  *
328  * Return Value:
329  * Current version always returns OK
330  *
331  * Assumptions:
332  *
333  ****************************************************************************/
338 int clock_systimespec(FAR struct timespec *ts);
343 /****************************************************************************
344  * Function: clock_cpuload
345  *
346  * Description:
347  * Return load measurement data for the select PID.
348  *
349  * Parameters:
350  * pid - The task ID of the thread of interest. pid == 0 is the IDLE thread.
351  * cpuload - The location to return the CPU load
352  *
353  * Return Value:
354  * OK (0) on success; a negated errno value on failure. The only reason
355  * that this function can fail is if 'pid' no longer refers to a valid
356  * thread.
357  *
358  * Assumptions:
359  *
360  ****************************************************************************/
361 
362 #ifdef CONFIG_SCHED_CPULOAD
363 
367 int clock_cpuload(int pid, int index, FAR struct cpuload_s *cpuload);
371 #endif
372 
373 #undef EXTERN
374 #ifdef __cplusplus
375 }
376 #endif
377 
378 #endif /* _INCLUDE_CLOCK_H */
379 
#define EXTERN
Definition: clock.h:222
EXTERN volatile clock_t g_system_timer
Definition: clock.h:233
structure represents an elapsed time
Definition: time.h:160
#define clock_systimer()
Definition: clock.h:236
Time APIs.